ULCCComponentBase: базовый класс Component 3DGS

Базовый класс всех Component LCC, несущий возможности рендеринга, цвета, производительности, коллизий, GIS и другие. От него наследуются ULCCComponent (LCC1) и ULCC2Component (LCC2).

#include "LCCComponentBase.h"

Получение экземпляра через Actor:

ULCCComponentBase* Component = LCCActor->GetLCCComponent();

Эта страница — указатель интерфейсов, описывающий сигнатуру, параметры и замечания по вызову каждого метода. Как настраивать параметр и к каким визуальным и производительным последствиям это приводит, описано в соответствующем тематическом документе:

Различия между двумя конвейерами

Часть свойств и методов объявлена в базовом классе, но реально реализована только в одном конвейере. Перед написанием кода сначала уточни, по какому конвейеру идут целевые данные.

Свойства

У свойств с BlueprintSetter перетаскивание значения в панели Details и вызов сеттера в коде идут по одному и тому же пути. Свойства с Interp можно анимировать ключевыми кадрами в Sequencer.

Путь загрузки

Свойства рендеринга

Свойства производительности

Поле Performance имеет тип FRenderInfo. Каждому значению сопутствует переключатель включения; когда переключатель выключен, используется встроенное значение по умолчанию. Перечень полей см. в Structs, рекомендации по значениям — в Параметрах производительности.

Свойства коррекции цвета

Четыре компонента соответствуют по порядку R, G, B и общему значению. Описание эффекта коррекции цвета см. в Настройке изображения.

Обрати внимание, что указанные диапазоны — это лишь диапазоны ползунков в панели (UIMin / UIMax), ограничения Clamp нет. Если передать сеттеру в коде значение за пределами диапазона, оно не будет усечено, и за результат отвечаешь ты. В отличие от них SplatScale и GlobalAlpha действительно ограничены Clamp.

Свойства окраски облака точек

Свойства коллизий

Подробнее см. Коллизии.

Свойства камеры

Следующие три пункта работают только в конвейере LCC1; в панели Details компонента LCC2 два последних скрыты.

Свойства GIS

Порядок настройки совместной работы с Cesium см. в Интеграции сторонних плагинов и плагинов движка.

Свойства обрезки и секущих плоскостей

Все три массива помечены BlueprintReadOnly; не изменяй их элементы напрямую, управляй ими через методы AddClippingVolume, AddLoadVolume и подобные.

LoadVolumes работает на другом этапе, чем первые два: он фильтрует данные до загрузки, и отсеянные области не читаются; объёмы обрезки и секущие плоскости изменяют только результат рендеринга. См. Объёмы загрузки.

Свойства анимации

Анимация состоит из двух этапов: на первом этапе после задержки FirstStageDelay масштаб растёт от 0 до AnimationMinScale, на втором после задержки SecondStageDelay — от AnimationMinScale до SplatScale.

Эффект параметров и способ настройки см. в Анимации загрузки.

Загрузка и состояние

Load

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool Load(FString LCCPath);

Загружает данные. Именно этот метод в конечном счёте вызывает ALCCActorBase::Load.

Возвращает bool: true, если проверка пути пройдена и процесс загрузки запущен. Передача пустого пути выполняет выгрузку и тоже возвращает true.

Замечания по применению:

• Возврат true означает лишь запуск процесса, а не готовность данных. В текущей версии нужен опрос через CheckIfLoaded, в следующих версиях появится обратный вызов по завершении загрузки.
• Если переданный путь совпадает с уже загруженным, метод сразу возвращается и повторная загрузка не выполняется.
• При успешной загрузке путь записывается в DefaultLoadPath.

ULCCComponentBase* Component = LCCActor->GetLCCComponent();
if (Component && Component->Load(TEXT("D:/Data/Tower/Tower.lcc")))
{
    UE_LOG(LogTemp, Log, TEXT("Load started"));
}

UnLoad

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void UnLoad();

Выгружает данные, освобождает кэши узлов, буферы в видеопамяти и тела коллизий, а также очищает DefaultLoadPath.

Два момента, о которых стоит помнить:

• Поскольку DefaultLoadPath очищается, вызов Refresh() сразу после UnLoad() ничего не загрузит заново.
• Метаинформация не очищается. После выгрузки GetMetaInfo() и GetSplatNumber() по-прежнему возвращают данные последней загрузки, поэтому не используй их для проверки факта выгрузки, используй CheckIfLoaded.

Refresh

UFUNCTION(BlueprintCallable, Category = "XGrids")
void Refresh();

Перезагружает текущие данные. Реализация — это UnLoad() плюс Load(DefaultLoadPath), поэтому стоимость равна полной перезагрузке.

Используй, чтобы перечитать данные с диска после того, как файлы данных были заменены. Если нужно лишь обновить рендеринг на один кадр, используй ForceUpdate.

ForceUpdate

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ForceUpdate();

Помечает, что в следующем кадре сцену нужно принудительно обновить один раз; стоимость очень мала.

Когда ни камера, ни параметры рендеринга не изменились, плагин пропускает обновление узлов. Если что-то, влияющее на видимость, было изменено извне, а изображение за этим не последовало, используй этот метод, чтобы протолкнуть кадр. Не вызывай его каждый кадр — это отключит оптимизацию пропуска.

CheckIfLoaded

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual bool CheckIfLoaded() const;

Построены ли метаинформация и структура индекса. Помечен BlueprintPure, поэтому в Blueprint это чистый узел без пинов выполнения.

Точный смысл: для LCC1 проверяется, создан ли менеджер узлов, для LCC2 — создано ли дерево. Возврат true означает, что разбор метаинформации завершён и метаинформацию можно безопасно читать, а параметры настраивать, но данные splat продолжают подгружаться потоково по текущему ракурсу, и изображение будет постепенно дополняться.

То есть это не означает «изображение полностью готово». Там, где нужно дождаться стабилизации изображения, эта функция ответа не даёт.

if (Component->CheckIfLoaded())
{
    // Safe to read metadata and configure parameters
}

Blueprint в виде текста, опрос каждые 0.2 секунды:

[Event BeginPlay]
        │
        ▼
[Set Timer by Event]
        Time = 0.2
        Looping = true
        Event ──▶ [Custom Event: CheckLoaded]

[Custom Event: CheckLoaded]
        │
        ▼
[Get LCC Component] ──▶ [Check If Loaded]
                              │ Return Value ──┐
                              ▼                │
                        [Branch] ◀─────────────┘
                              │ True
                              ▼
                        [Clear and Invalidate Timer by Handle]
                              │
                              ▼
                        (configuration after loading completes)

GetSplatNumber

UFUNCTION(BlueprintCallable, Category = "XGrids")
int GetSplatNumber() const;

Возвращает общее количество splat в данных, взятое из поля TotalSplats метаинформации.

Замечания по применению:

• Это собственная суммарная величина данных, она не меняется при движении камеры и не является количеством, фактически отображаемым в текущем кадре.
• До первой загрузки возвращает 0. Но поскольку UnLoad() не очищает метаинформацию, после выгрузки метод всё ещё вернёт предыдущее значение.
• Чтобы узнать нагрузку рендеринга в текущем кадре, открой панель статистики методом Stats() у Actor и смотри данные в реальном времени.

if (Component->CheckIfLoaded())
{
    UE_LOG(LogTemp, Log, TEXT("Total splats in dataset: %d"),
        Component->GetSplatNumber());
}

HaveValidSplatData

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool HaveValidSplatData();

Есть ли пригодные для отображения данные splat. При ошибке загрузки или пустых данных возвращает false.

HaveValidCollisionData

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool HaveValidCollisionData();

Содержат ли данные файл коллизий.

Обрати внимание, что проверяется только новый формат collision.lci: ни старый collision.bin, ни коллизии облака точек .ply не проверяются. При фактической загрузке коллизий поддерживаются все три формата, поэтому для набора данных только с collision.bin возможна ситуация, когда эта функция возвращает false, а SetLCCCollisionEnable(true) всё равно загружает коллизии успешно.

Чтобы точно определить все три формата, используй ULCCUtilLibrary::DetermineCollisionType (передав каталог, в котором лежат данные).

if (Component->HaveValidCollisionData())
{
    Component->SetLCCCollisionEnable(true);
}

CanRender

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool CanRender() const;

Выполнены ли условия для рендеринга в данный момент. Основанием служат состояние видимости компонента и то, построена ли структура данных подкласса (для LCC1 — менеджер узлов, для LCC2 — дерево). Достоверность метаинформации не учитывается.

CanSetShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanSetShcoef() const;

Содержат ли данные коэффициенты сферических гармоник. По реализации это равносильно проверке, что тип файла — EFileType::Quality.

Используй перед вызовом SetUseShcoef, а также чтобы решить, показывать ли переключатель сферических гармоник в интерфейсе неактивным.

GetMetaInfo

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual FMetaInfoBase GetMetaInfo() const;

Возвращает метаинформацию данных, включая имя, версию, систему координат, общее число уровней, общее число splat и другое. Подробности полей см. в Structs.

Читай её после завершения загрузки; пока данные не готовы, поля содержат нули. Возвращается срез базового класса; чтобы получить полный набор полей LCC1/LCC2, используй специальные методы подклассов.

if (Component->CheckIfLoaded())
{
    const FMetaInfoBase Meta = Component->GetMetaInfo();
    UE_LOG(LogTemp, Log, TEXT("Name=%s Levels=%d RTK=%s"),
        *Meta.Name, Meta.TotalLevel, Meta.IsRTK() ? TEXT("yes") : TEXT("no"));
}

GetLocalVisibleBounds

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual FBox GetLocalVisibleBounds() const;

Возвращает видимый габаритный бокс модели в локальном пространстве компонента. Если данные недоступны, возвращается недействительный бокс (FBox(ForceInit)), поэтому перед использованием проверь IsValid.

Для мирового пространства преобразуй его самостоятельно через GetComponentTransform(). Типичное применение — автоматически поставить камеру в такое положение, откуда видна вся сцена.

const FBox LocalBounds = Component->GetLocalVisibleBounds();
if (LocalBounds.IsValid)
{
    const FBox WorldBounds =
        LocalBounds.TransformBy(Component->GetComponentTransform());

    const FVector Center = WorldBounds.GetCenter();
    const float Radius = WorldBounds.GetExtent().Size();
    // Use Center and Radius to compute the viewing position
}

GetLccVersion

virtual ELCCVersion GetLccVersion() const;

Возвращает версию данных, ELCCVersion::LCC или ELCCVersion::LCC2. Доступно только в C++.

Рендеринг

Визуальный эффект и компромиссы каждого параметра описаны в Рендеринге и Настройке изображения; здесь речь только об интерфейсах.

SetRenderMode / GetRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetRenderMode(ERenderMode InRenderMode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ERenderMode GetRenderMode() const;

Переключает между 3DGS (ERenderMode::Splatting) и облаком точек (ERenderMode::PointCloud).

В режиме облака точек пункты, специфичные для 3DGS, не действуют, а для прозрачности используется GlobalAlpha_PointCloud.

Соответствующий параметр панели — Режим отображения.

Component->SetRenderMode(ERenderMode::PointCloud);

Blueprint в виде текста:

[Input Action: ToggleView]
        │ Pressed
        ▼
[Get LCC Component]
        Target = LCCActor
        │ Return Value ──┐
        ▼                │
[Set Render Mode] ◀──────┘
        Target = (Return Value)
        In Render Mode = Point Cloud

ToggleRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleRenderMode();

Переключает туда и обратно между 3DGS и облаком точек, без необходимости самому проверять текущее состояние.

SetLoadMode / GetLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLoadMode(ELoadMode Mode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ELoadMode GetLoadMode() const;

Управляет тем, отображать ли основные данные, данные окружения или оба. Значения см. в ELoadMode, описание в панели — в Режиме загрузки.

ELoadMode::None равносильно временному скрытию, но уже загруженные данные остаются в памяти, поэтому восстановление быстрее, чем после UnLoad.

Component->SetLoadMode(ELoadMode::OnlyMain);

SetLightMode / GetLightMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void SetLightMode(ELightMode InLightMode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ELightMode GetLightMode() const;

Управляет участием в освещении сцены, ELightMode::Unlit или ELightMode::Lit.

Реализация в двух конвейерах различается:

• LCC1 реализует это переключением материалов Lit / Unlit.
• LCC2 материал не переключает, освещение обрабатывается внутри шейдера. Поэтому в LCC2 нужно ещё настроить NormalMode, чтобы получить разумное распределение света и тени, подробнее см. ULCC2Component и Нормали и освещение.

В собранных данных освещение съёмки уже запечено, поэтому переключение в Lit легко приводит к пересвету. В LCC2 можно понизить исходную яркость через LightingScale.

В режиме облака точек этот сеттер не действует: внутри присваивание пропускается и выводится предупреждение в журнал. Чтобы изменить режим освещения, сначала вернись к 3DGS.

Соответствующий параметр панели — Режим освещения.

ToggleLightMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleLightMode();

Переключает между Unlit и Lit.

SetUseShcoef / GetUseShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseShcoef(bool InUseShcoef);

UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseShcoef() const;

Включает и выключает сферические гармоники. Гармоники дают изменение цвета в зависимости от ракурса; после отключения цвет становится постоянным.

Замечания по применению:

• Требуется, чтобы данные содержали сферические гармоники, проверяй это через CanSetShcoef. Для данных типа Portable гармоники недоступны, и пункт нельзя изменить в панели.
• В режиме облака точек этот сеттер молча не действует. Внутри требуется, чтобы данные были типа Quality и текущий режим не был облаком точек; при невыполнении любого из двух условий присваивание пропускается.
• В LCC2 можно только понизить число полос, не отключая гармоники полностью, см. SetSHBands.
• Описание в панели см. в Сферических гармониках (SH).

if (Component->CanSetShcoef())
{
    Component->SetUseShcoef(false);
}

ToggleShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleShcoef();

Включает и выключает сферические гармоники, удобно для сравнения результата.

SetSplatScale / GetSplatScale

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSplatScale(float InSplatScale);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetSplatScale() const;

Размер площадки splat, диапазон 0.001~1.0, по умолчанию 1.0.

Замечания по применению:

• Значение по умолчанию 1.0 и есть предел, значение можно только уменьшать.
• Уменьшение снижает Overdraw и повышает частоту кадров, но ценой того, что при меньших площадках в изображении могут появиться дыры.
• Влияет только на режим 3DGS.
• Описание в панели см. в SplatScale.

// Trade Overdraw for frame rate, weigh the holes depending on the case
Component->SetSplatScale(0.8f);

SetGlobalAlpha / GetGlobalAlpha

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha(float InGlobalAlpha);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha() const;

Общая непрозрачность 3DGS, диапазон 0~1. Помечено Interp, поэтому в Sequencer можно расставить ключевые кадры для плавного появления и исчезновения.

Для режима облака точек используй SetGlobalAlpha_PointCloud, два значения независимы. Описание в панели см. в Глобальной прозрачности.

// Fade out frame by frame
const float Next = FMath::FInterpTo(
    Component->GetGlobalAlpha(), 0.0f, DeltaTime, 2.0f);
Component->SetGlobalAlpha(Next);

Blueprint в виде текста, исчезновение через Timeline:

[Timeline: FadeOut]
        Length = 2.0
        Float Track "Alpha" = 1.0 → 0.0
        │ Update
        ▼
[Set Global Alpha]
        Target = (LCC Component)
        In Global Alpha = (Alpha output of the Timeline)

SetGlobalAlpha_PointCloud / GetGlobalAlpha_PointCloud

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha_PointCloud(float InGlobalAlpha);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha_PointCloud() const;

Общая непрозрачность в режиме облака точек, диапазон 0~1, по умолчанию 0.2.

SetUseMipFilter / GetUseMipFilter

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseMipFilter(bool InUseMipFilter);

UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseMipFilter() const;

Включает и выключает фильтр против мерцания, по умолчанию включён. При включении применяется низкочастотный фильтр с компенсацией непрозрачности, что даёт большую стабильность при разных масштабах; при выключении изображение резче, но возможны алиасинг и мерцание. Действует только в режиме 3DGS.

Описание в панели см. в Mip Filter.

EnableReceiveShadows / DisableReceiveShadows

UFUNCTION(BlueprintCallable, Category = "XGrids")
void EnableReceiveShadows();

UFUNCTION(BlueprintCallable, Category = "XGrids")
void DisableReceiveShadows();

Включает и выключает приём теней, экспериментальная возможность.

Замечания по применению:

• Поддерживается только конвейером LCC1; в панели Details компонента LCC2 это свойство скрыто.
• Действует только в режиме 3DGS и заметно влияет на производительность.
• Внутри реализовано переключением на отдельный материал, поэтому настройка материала выполняется заново.
• Описание в панели см. в Приёме теней.

Производительность

У этой группы сеттеров есть общее поведение: при вызове соответствующий переключатель включения автоматически устанавливается в true. Геттеры возвращают действующее значение; когда переключатель выключен, они возвращают встроенное значение по умолчанию, а не то, что ты вводил ранее.

GetPreloadDistance — единственное исключение: он возвращает исходное значение поля, а не действующее.

Рекомендации по значениям см. в Параметрах производительности и Руководстве по производительности.

SetMaxDistance / GetMaxDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxDistance(const int32 InDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxDistance() const;

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

Соответствующий параметр панели — Max Distance.

Component->SetMaxDistance(80);

SetMaxSplatNum / GetMaxSplatNum

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxSplatNum(const int32 InSplatNum);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxSplatNum() const;

Максимальное количество splat на кадр, в единицах по десять тысяч, предел 10000. Значение 1500 означает 15 миллионов.

Значения, превышающие возможности GPU на один кадр, автоматически ограничиваются. Соответствующий параметр панели — Max Splat Num.

Component->SetMaxSplatNum(1500);   // 15 million

SetLevelFactor / GetLevelFactor

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLevelFactor(const float InLevelFactor);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetLevelFactor() const;

Коэффициент масштабирования LOD, диапазон 0.01~20, по умолчанию 1. Увеличение значения означает меньше детализации и лучшую производительность.

Механизм работы в двух конвейерах различается:

• LCC1: поверх RangeForLevel из настроек проекта изменяет соответствие между расстоянием и уровнем.
• LCC2: участвует в выборе узлов как коэффициент масштабирования ошибки в экранном пространстве.

Поэтому одно и то же значение нельзя напрямую сопоставлять по визуальному результату между конвейерами, проверяй каждый на практике.

Соответствующий параметр панели — Level Factor.

Component->SetLevelFactor(1.5f);

SetStartLevel / GetStartLevel

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetStartLevel(const int32 InStartLevel);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetStartLevel() const;

Начальный уровень, диапазон 0~20, по умолчанию 0. Уровень 0 даёт наибольшую детализацию; повышение значения позволяет пропустить самые детальные уровни, что заметно снижает расход видеопамяти и объём загрузки.

Соответствующий параметр панели — Start Level.

SetEndLevel / GetEndLevel

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetEndLevel(const int32 InEndLevel);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetEndLevel() const;

Конечный уровень, диапазон 0~20, по умолчанию 20. Ограничивает уровень с самой грубой стороны, обычно менять не требуется.

Соответствующий параметр панели — End Level.

SetMaxCollisionDistance / GetMaxCollisionDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxCollisionDistance(const int32 InMaxCollisionDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxCollisionDistance() const;

Максимальная дистанция загрузки коллизий в метрах, встроенное значение по умолчанию 300.

Если нужна трассировка луча на большие расстояния, это значение должно покрывать диапазон проверки, иначе попаданий не будет.

Соответствующий параметр панели — Max Load Collision Distance.

SetPreloadDistance / GetPreloadDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPreloadDistance(const int32 InPreloadDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetPreloadDistance() const;

Дистанция предзагрузки в метрах.

Обрати внимание: в текущей версии действующая логика жёстко задана как MaxDistance + 35, значение, заданное сеттером, в расчёте не участвует, и в панели этот пункт не отображается. Интерфейс сохранён для совместимости, в повседневной работе вызывать его не нужно.

Коррекция цвета

Все свойства коррекции цвета имеют тип FVector4, четыре компонента соответствуют по порядку R, G, B и общему значению. Все сеттеры коррекции цвета действуют немедленно. Описание эффекта см. в Настройке изображения.

UFUNCTION(BlueprintCallable, Category = "XGrids|Color")
void SetSaturation(const FVector4 InSaturation);   // saturation, 0~2
void SetContrast(const FVector4 InContrast);       // contrast, 0~2
void SetGamma(const FVector4 InGamma);             // gamma, 0~2
void SetOffset(const FVector4 InOffset);           // additive offset, -1~1
void SetColorTint(const FLinearColor InColor);     // multiplicative tint

// Corresponding getters
FVector4 GetSaturation() const;
FVector4 GetContrast() const;
FVector4 GetGamma() const;
FVector4 GetOffset() const;
FLinearColor GetColorTint() const;

Offset действует аддитивно и поднимает вместе с остальным и тёмные участки; ColorTint действует умножением, поэтому тёмные участки остаются тёмными. Эффект каждого пункта см. в Коррекции цвета.

// Lower saturation + slightly brighten
Component->SetSaturation(FVector4(0.6f, 0.6f, 0.6f, 0.6f));
Component->SetOffset(FVector4(0.05f, 0.05f, 0.05f, 0.f));

Окраска облака точек по высоте

UFUNCTION(BlueprintCallable, Category = "XGrids|PointCloud")
void SetElevationColorBottom(FLinearColor InElevationColorBottom);

UFUNCTION(BlueprintCallable, Category = "XGrids|PointCloud")
void SetElevationColorTop(FLinearColor InElevationColorTop);

UFUNCTION(BlueprintPure, Category = "XGrids|PointCloud")
FLinearColor GetElevationColorBottom() const;

UFUNCTION(BlueprintPure, Category = "XGrids|PointCloud")
FLinearColor GetElevationColorTop() const;

Нижний и верхний цвета градиента по высоте, по умолчанию от синего к красному.

Component->SetRenderMode(ERenderMode::PointCloud);
Component->SetElevationColorBottom(FLinearColor(0.0f, 0.2f, 1.0f, 1.0f));
Component->SetElevationColorTop(FLinearColor(1.0f, 0.1f, 0.0f, 1.0f));

Коллизии

SetLCCCollisionEnable

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLCCCollisionEnable(const bool InEnable);

Включает и выключает загрузку данных коллизий.

Замечания по применению:

• Требуется, чтобы данные содержали файл коллизий; сначала подтверди это через HaveValidCollisionData.
• Коллизии подгружаются потоково в зависимости от расстояния и ограничены значением Performance.CollisionLoadMaxDistance.
• После включения можно напрямую использовать LineTraceByChannel движка, перемещение персонажа и физическое моделирование.
• Первое включение сопряжено с однократными затратами на подготовку, что может вызвать короткое подтормаживание. Старайся включать это уже на этапе загрузки.
• Метод ShowCollision() у Actor позволяет увидеть каркас коллизий и убедиться, что они загрузились.

Полное описание см. в Коллизиях.

if (Component->HaveValidCollisionData())
{
    Component->SetMaxCollisionDistance(50);
    Component->SetLCCCollisionEnable(true);
}

GIS

Географическое размещение часто применяют совместно с Cesium, чтобы поставить сцену LCC в реальные координаты Земли. Порядок настройки, зависимости плагинов и замечания см. в Интеграции сторонних плагинов и плагинов движка.

SetGeoPlacement

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGeoPlacement(bool InEnable);

Включает и выключает размещение сцены по широте и долготе.

После включения сцена автоматически размещается по реальным географическим координатам, а вручную заданное положение Actor перезаписывается; для тонкой подстройки используй GeoLocationOffset. Если включить это для нескольких сцен LCC одновременно, они автоматически выровняются по реальному взаимному расположению.

Замечания по применению:

• Внутри автоматически выполняется один Refresh() (выгрузка и повторная загрузка), поэтому вызов срабатывает в любой момент и Load() заново вызывать не нужно. Ценой этого является стоимость, равная полной перезагрузке, так что не переключай часто.
• Требуется, чтобы данные содержали информацию RTK. Для проверки используй GetMetaInfo().IsRTK(), а не CanUseGeoPlace(): последний требует, чтобы географическое размещение было уже включено, и до включения всегда возвращает false.

if (Component->CheckIfLoaded() && Component->GetMetaInfo().IsRTK())
{
    Component->SetGeoPlacement(true);   // reloads automatically
}

CanUseGeoPlace

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanUseGeoPlace() const;

Доступно ли географическое размещение в данный момент. Одновременно должны быть выполнены три условия: bEnableGeoPlace включено, данные содержат информацию RTK, система географической привязки создана.

Это не признак того, «поддерживают ли данные географическое размещение». Поскольку метод требует, чтобы bEnableGeoPlace уже было true, до включения он всегда возвращает false. Чтобы проверить поддержку данными до включения, используй GetMetaInfo().IsRTK().

Его практическое назначение — подтвердить после включения, что размещение действительно заработало.

GetRTKBaseLocation

UFUNCTION(BlueprintCallable, Category = "XGrids")
FVector GetRTKBaseLocation() const;

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

Примечание: внутри для преобразования координат напрямую используется система географической привязки, без проверки на null. Вызов до создания системы географической привязки приведёт к аварийному завершению. Перед вызовом убедись, что CanUseGeoPlace равно true или что GetGeoReferencingSystem возвращает не null.

GetGeoReferencingSystem

UFUNCTION(BlueprintCallable, Category = "XGrids")
ALCCGeoReferencingSystem* GetGeoReferencingSystem() const;

Возвращает Actor системы географической привязки в сцене, который плагин создаёт автоматически при включении географического размещения.

ALCCGeoReferencingSystem* GeoSystem = Component->GetGeoReferencingSystem();
if (GeoSystem)
{
    // Convert projected coordinates to engine coordinates
    FVector EngineLocation;
    GeoSystem->ProjectedToEngine(ProjectedCoord, EngineLocation);

    // Get the east/north/up directions at that point
    FVector East, North, Up;
    GeoSystem->GetENUVectorsAtEngineLocation(EngineLocation, East, North, Up);
}

Multi-Viewport

Для одних и тех же данных можно задать разные стратегии рендеринга для разных камер. Типичное применение — основной вьюпорт с высоким качеством 3DGS и мини-карта, отображающая вид сверху облаком точек через SceneCapture.

Примечание: эта группа интерфейсов применима только к конвейеру LCC1. Вызов в конвейере LCC2 (ALCC2Actor, а также .sog / .spz / .ply) не приводит к ошибке, но и не даёт ожидаемого результата. Если нужен разный рендеринг по вьюпортам или предзагрузка перед телепортацией, используй данные LCC1.

Принимаются указатели на объекты, а не целочисленные идентификаторы.

Общие решения для нескольких камер и нескольких экранов (nDisplay, Aximmetry, Pixotope и другие) см. в Интеграции сторонних плагинов и плагинов движка.

SetPlayerLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerLoadMode(class APlayerController* PlayerController, ELoadMode InLoadMode);

Задаёт LoadMode отдельно для указанного контроллера игрока; вступает в силу в следующем кадре.

APlayerController* PC2 = UGameplayStatics::GetPlayerController(GetWorld(), 1);
Component->SetPlayerLoadMode(PC2, ELoadMode::OnlyMain);

SetPlayerRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerRenderMode(class APlayerController* PlayerController, ERenderMode InRenderMode);

Задаёт RenderMode отдельно для указанного контроллера игрока; вступает в силу в следующем кадре.

SetSceneCaptureLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureLoadMode(class USceneCaptureComponent2D* InCapture2D, ELoadMode InLoadMode);

Задаёт LoadMode отдельно для указанного SceneCapture.

Сначала нужно включить SceneCaptureComponent Support в настройках проекта, иначе содержимое LCC не будет отображаться в SceneCapture.

SetSceneCaptureRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureRenderMode(class USceneCaptureComponent2D* InCapture2D, ERenderMode InRenderMode);

Задаёт RenderMode отдельно для указанного SceneCapture.

// Minimap uses point cloud + main data only, minimal cost
Component->SetSceneCaptureRenderMode(MinimapCapture, ERenderMode::PointCloud);
Component->SetSceneCaptureLoadMode(MinimapCapture, ELoadMode::OnlyMain);

ModifyPlayerTransform

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ModifyPlayerTransform(class APlayerController* PlayerController, FTransform InTransform);

Переопределяет положение указанного игрока в этой сцене, что используется для предзагрузки данных в точке назначения перед телепортацией.

Решаемая задача: при прямой телепортации в отдалённую точку узлы в точке назначения ещё не загружены, и игрок увидит пустоту вместо основных данных, которая затем постепенно дополнится.

Правильная последовательность:

ModifyPlayerTransform(destination)
        ↓ wait about 0.2 seconds so that the destination nodes start loading
actually teleport the player
        ↓ wait about another 0.2 seconds
CancelModifyPlayerTransform

void AMyTeleporter::TeleportWithPreload(APlayerController* PC, const FTransform& Destination)
{
    Component->ModifyPlayerTransform(PC, Destination);

    FTimerHandle Handle;
    GetWorld()->GetTimerManager().SetTimer(Handle,
        [this, PC, Destination]()
        {
            PC->GetPawn()->SetActorTransform(Destination);

            FTimerHandle CancelHandle;
            GetWorld()->GetTimerManager().SetTimer(CancelHandle,
                [this, PC]()
                {
                    Component->CancelModifyPlayerTransform(PC);
                },
                0.2f, false);
        },
        0.2f, false);
}

Blueprint в виде текста:

[Custom Event: TeleportTo]
        Destination (Transform)
        │
        ▼
[Modify Player Transform]
        Target = (LCC Component)
        Player Controller = Get Player Controller
        In Transform = Destination
        │
        ▼
[Delay]  Duration = 0.2
        │
        ▼
[Set Actor Transform]
        Target = Get Player Pawn
        New Transform = Destination
        │
        ▼
[Delay]  Duration = 0.2
        │
        ▼
[Cancel Modify Player Transform]
        Target = (LCC Component)
        Player Controller = Get Player Controller

CancelModifyPlayerTransform

UFUNCTION(BlueprintCallable, Category = "XGrids")
void CancelModifyPlayerTransform(class APlayerController* PlayerController);

Отменяет переопределение положения и возвращает использование фактического положения игрока.

Вызывать обязательно, иначе планирование узлов для этого игрока навсегда останется привязанным к переопределённому положению и при перемещении новые узлы загружаться не будут.

Обрезка и секущие плоскости

Порядок применения обрезки и секущих плоскостей см. в Редактировании сцены, а также в ALCCClippingVolume и ALCCSectionPlane.

AddClippingVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddClippingVolume(ALCCClippingVolume* InClippingVolume);

Добавляет объём обрезки.

ALCCClippingVolume* Volume = GetWorld()->SpawnActor<ALCCClippingVolume>(
    ALCCClippingVolume::StaticClass(), Location, FRotator::ZeroRotator);

Volume->VolumeType = EClipVolumeType::Box;
Volume->Mode = EClipType::Inside;
Volume->bEnabled = true;

Component->AddClippingVolume(Volume);

RemoveClippingVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveClippingVolume(ALCCClippingVolume* InClippingVolume);

Удаляет объём обрезки. Если нужно лишь временно отключить его, легче изменить bEnabled у самого объёма обрезки.

AddSectionPlane

UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddSectionPlane(ALCCSectionPlane* InSectionPlane);

Добавляет секущую плоскость.

RemoveSectionPlane

UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveSectionPlane(ALCCSectionPlane* InSectionPlane);

Удаляет секущую плоскость.

AddLoadVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddLoadVolume(ALCCLoadVolume* InLoadVolume);

Добавляет объём загрузки, отбирающий загружаемые данные по области.

ALCCLoadVolume* Volume = GetWorld()->SpawnActor<ALCCLoadVolume>(
    ALCCLoadVolume::StaticClass(), Location, FRotator::ZeroRotator);

Volume->VolumeType = ELoadVolumeType::Box;
Volume->Mode = ELoadRegion::Inside;
Volume->bEnabled = true;

Component->AddLoadVolume(Volume);
Component->Load(Path);   // filtering applies at load time, configure first and then load

Фильтрация происходит на этапе загрузки, поэтому её нужно настроить до вызова Load. Если добавлять или удалять объёмы загрузки после того, как данные уже загружены, изменения вступят в силу только после перезагрузки.

Возможность редакции Pro: без лицензии она не действует и данные загружаются в полном объёме.

RemoveLoadVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveLoadVolume(ALCCLoadVolume* InLoadVolume);

Удаляет объём загрузки. Здесь также нужна перезагрузка, чтобы объём уже загруженных данных изменился.

Анимация загрузки

SetEnableAnimation / GetEnableAnimation

UFUNCTION(BlueprintCallable, Category = "XGrids|Animation")
void SetEnableAnimation(bool bInEnableAnimation);

UFUNCTION(BlueprintPure, Category = "XGrids|Animation")
bool GetEnableAnimation() const;

Включает и выключает анимацию, одновременно сбрасывая точку отсчёта времени анимации на текущий момент. Поэтому метод не ограничен этапом загрузки: вызов в любой момент проигрывает анимацию с начала.

Параметры этапов задаются напрямую как свойства, отдельных сеттеров нет. Чтобы параметры действовали на всю анимацию целиком, сначала задай параметры, а затем вызови этот метод. Изменение параметров во время воспроизведения тоже действует и относится к настройке на ходу.

Component->AnimationSpeed = 30.0f;
Component->SecondStageDelay = 1.0f;
Component->SetEnableAnimation(true);

Обратную анимацию (исчезновение), порядок вызовов, значения параметров и практические замечания см. в Анимации загрузки.

Смотрите также

• ALCCActorBase: интерфейсы на стороне Actor
• ULCCComponent: трассировка луча по облаку точек, специфичная для LCC1
• ULCC2Component: сферические гармоники и режимы нормалей, специфичные для LCC2
• Enums: описание значений ERenderMode, ELoadMode, ELightMode и других
• Structs: описание полей FRenderInfo, FMetaInfoBase