XGRIDSДокументация

Руководство по разработке совместимости форматов данных LCC и LCC2

Формат данных LCC2 обеспечивает лучшее сжатие данных и механизмы LOD. Исходный формат LCC постепенно будет заменён на LCC2, а исходный LCC SDK (v1.x) постепенно перестанет поддерживаться. Поскольку старый и новый форматы данных сильно различаются, новый LCC SDK (v2.x) не является обратно совместимым с форматом LCC. Совместимость данных можно обеспечить следующими двумя способами:

  1. Используйте официальный конвертер (LccConverter) exe/dll для преобразования формата данных LCC в LCC2, затем используйте его в SDK;
  2. Реализуйте совместимость форматов данных LCC и LCC2 на уровне приложения.

Это руководство в основном описывает процесс и шаги реализации совместимости форматов данных на уровне приложения, то есть импорт двух версий SDK в один и тот же проект Unity одновременно и автоматический выбор соответствующей версии для рендеринга и обработки на основе формата данных.

Шаг 1: Версия Unity и настройки проекта

Версия Unity и настройки проекта такие же, как при независимом использовании SDK; дополнительная настройка не требуется. См. Руководство по быстрому старту для PC и Руководство по оптимизации настроек проекта.

Шаг 2: Импортируйте две версии SDK

Импортируйте SDK v1.4.8 и новее (рекомендуется v1.4.32) и SDK v2.0.1 и новее через Unity UPM. После импорта версия v1.x будет отображаться как Legacy. Две версии SDK могут сосуществовать, не влияя друг на друга.

Примечание:

  • SDK v1.4.32 можно загрузить с GitHub: https://github.com/xgrids/LCC-Unity-SDK/releases
  • Пространство имён SDK v1.4.32 — LCCCore_Legacy, а его компонент менеджера — LCCManager_Legacy; пространство имён v2.x — LCCCore, а его компонент менеджера — LCCManager.

Шаг 3: Настройте сцену

Создайте в сцене пустой объект с именем LCCController и прикрепите к нему оба компонента — LCCManager_Legacy и LCCManager.

Прикрепление компонентов LCCManager_Legacy и LCCManager к объекту LCCController

Прикрепление компонентов LCCManager_Legacy и LCCManager к объекту LCCController

Примечание:

Настройки Transform GameObject LCCController (Rotation.x = -90, Scale.x = -1) выравнивают его с системой координат данных LCC. Подробнее о выравнивании системы координат см. в разделе «Система координат данных LCC» документа Введение в Unity SDK.

Шаг 4: Напишите скрипт MultiSDKController

Создайте новый скрипт C# с именем MultiSDKController.cs со следующим кодом:

using LCCCore;
using LCCCore_Legacy;
using System.IO;
using UnityEngine;

public class MultiSDKController : MonoBehaviour
{
    public LCCManager_Legacy m_managerLegacy;          // для LCC SDK v1.4.8 и более ранних
    public LCCManager m_manager;                       // для LCC SDK v2.0.0 и более поздних
    public string m_FilePath;                          // путь к файлу LCC
    private LCCCore_Legacy.Renderer m_rendererLegacy;  // для LCC SDK v1.4.8 и более ранних
    private LCCCore.Renderer m_renderer;               // для LCC SDK v2.0.0 и более поздних
    private DataType m_dataType;                       // тип данных, используемый для определения того, какой SDK использовать

    void Start()
    {
        string extension = Path.GetExtension(m_FilePath);
        if (extension == ".lcc")
        {
            m_manager.Enable = false; // отключаем менеджер v2.0.0+
            m_dataType = DataType.LCC;
            m_rendererLegacy = m_managerLegacy.GetRender(this.transform);
            m_rendererLegacy.Load(m_FilePath, LCCCore_Legacy.PlatformType.PC, onLoadCallback);
        }
        else if (extension == ".lcc2")
        {
            m_managerLegacy.Enable = false; // отключаем менеджер v1.4.8 и более ранних
            m_dataType = DataType.LCC2;
            m_renderer = m_manager.GetRender(this.transform);
            m_renderer.Load(m_FilePath, LCCCore.PlatformType.PC, onLoadCallback);
        }
    }

    private void onLoadCallback()
    {
        Debug.Log("данные загружены !!!");
    }

    // Пример вызова метода: определяем, с каким рендерером SDK работать, по типу данных
    public void onRenderPointClick()
    {
        if (m_dataType == DataType.LCC)
            m_rendererLegacy.SwitchRenderMode(LCCCore_Legacy.RenderMode.PointCloud);
        else if (m_dataType == DataType.LCC2)
            m_renderer.SwitchRenderMode(LCCCore.RenderMode.PointCloud);
    }

    void OnDestroy()
    {
        if (m_dataType == DataType.LCC)
            m_rendererLegacy?.Dispose();
        else if (m_dataType == DataType.LCC2)
            m_renderer?.Dispose();
    }

    public enum DataType { LCC, LCC2 }
}

Примечание:

  • Имя файла скрипта должно совпадать с именем класса (MultiSDKController.cs соответствует class MultiSDKController), иначе его нельзя прикрепить к GameObject.
  • У двух версий разные пространства имён (LCCCore и LCCCore_Legacy). При использовании одноимённых типов, таких как Renderer, PlatformType и RenderMode, нужно добавлять префикс пространства имён, чтобы различать их.
  • В примере формат данных определяется по расширению файла (.lcc / .lcc2), и выбирается соответствующая версия SDK.

Шаг 5: Прикрепите скрипт и настройте свойства

  1. Также прикрепите скрипт MultiSDKController.cs к объекту LCCController в сцене.
  2. В окне Inspector перетащите компоненты LCCManager и LCCManager_Legacy на соответствующие свойства скрипта.
  3. Заполните путь к файлу LCC / LCC2 в свойстве File Path скрипта.
Прикрепление скрипта MultiSDKController и настройка его свойств

Прикрепление скрипта MultiSDKController и настройка его свойств в Inspector

Теперь при запуске кода соответствующая версия SDK автоматически используется для рендеринга на основе формата данных LCC, что обеспечивает совместимость форматов данных.

Ключевые шаги

Ключевые шаги для реализации совместимости форматов данных LCC и LCC2 на уровне приложения:

  1. Импортируйте обе версии SDK — v1.x (Legacy) и v2.x — через UPM; они могут сосуществовать.
  2. Прикрепите оба компонента менеджера — LCCManager_Legacy и LCCManager — к одному объекту.
  3. Выберите менеджер соответствующей версии для создания рендерера и загрузки данных на основе формата данных (расширение файла .lcc / .lcc2).
  4. После определения используемой версии отключите менеджер другой версии (Manager.Enable = false).
  5. При переключении данных или уничтожении выгрузите текущие отрендеренные данные через Renderer.Dispose().

Примечания о совместимости форматов данных

  • Одновременный рендеринг LCC и LCC2 не поддерживается. Поэтому при переключении данных сначала необходимо выгрузить текущие отрендеренные данные (вызвать Renderer.Dispose()), иначе это может привести к утечкам памяти и видеопамяти.

  • Отключите неиспользуемый Manager. После определения используемой версии SDK лучше всего отключить объект Manager другой версии SDK (Manager.Enable = false), иначе это может привести к некоторым неэффективным накладным расходам на производительность.

  • Интерфейсы API согласованы, но вы должны вызывать правильный Renderer. Интерфейсы API двух версий SDK абсолютно одинаковы (в v2.x многие API перемещены в класс Manager; см. руководство по API), но вы должны убедиться, что вызываете Renderer правильной версии (m_rendererLegacy или m_renderer). Кроме того, v2.0.0 и новее больше не поддерживают сохранение данных коррекции цвета и обрезки, а некоторые другие API также устарели; пожалуйста, проверьте документацию разработчика для соответствующей версии.

Связанные API

Это решение в основном связано с API менеджера и рендерера двух версий SDK. Ниже используется v2.x (LCCCore) в качестве примера; v1.x (LCCCore_Legacy) имеет тот же интерфейс, отличается только пространство имён.

LCCManager.Enable

// Свойство
public bool Enable { get; set; }

Переключатель включения менеджера. Установка значения false отключает менеджер этой версии SDK, избегая неэффективных накладных расходов на производительность при одновременной работе с другой версией.

Пример использования:

// При использовании данных LCC2 отключаем менеджер Legacy
m_managerLegacy.Enable = false;

Примечания:

  • После определения используемой версии рекомендуется отключить менеджер другой версии.

GetRender

// Возвращаемое значение: Renderer → экземпляр рендерера, null при ошибке
public Renderer GetRender(Transform _transform)

Создаёт экземпляр рендерера и привязывает его к указанному Transform.

ПараметрТипОписание
_transformTransformTransform, к которому прикрепляется экземпляр рендерера

Пример использования:

m_renderer = m_manager.GetRender(this.transform);

Примечания:

  • Должен создаваться через менеджер соответствующей версии, чтобы рендерер соответствовал формату данных.

Renderer.Dispose

// Возвращаемое значение: void
public void Dispose()

Уничтожает экземпляр рендерера и освобождает все ресурсы GPU и память. После уничтожения экземпляр больше нельзя использовать.

Пример использования:

m_renderer?.Dispose();

Примечания:

  • Перед переключением данных необходимо сначала выгрузить текущие данные, иначе это может привести к утечкам памяти и видеопамяти.
  • После вызова автоматически уведомляет Manager об удалении ссылки.
  • Рекомендуется вызывать при уничтожении объекта (OnDestroy).