ULCCComponentBase : classe de base des Components 3DGS

Classe de base de tous les Components LCC, qui porte les capacités de rendu, de couleur, de performance, de collision, de GIS et autres. ULCCComponent (LCC1) et ULCC2Component (LCC2) en héritent.

#include "LCCComponentBase.h"

Obtenir l'instance via l'Actor :

ULCCComponentBase* Component = LCCActor->GetLCCComponent();

Cette page est l'index des interfaces : elle donne la signature, les paramètres et les points d'appel de chaque méthode. La manière d'ajuster un paramètre et ses conséquences visuelles et de performance sont décrites dans le document thématique correspondant :

Différences entre les deux pipelines

Certaines propriétés et méthodes sont déclarées sur la classe de base, mais une seule pipeline les implémente réellement. Avant d'écrire du code, vérifier quelle pipeline emprunte la donnée visée.

Propriétés

Pour les propriétés portant BlueprintSetter, faire glisser la valeur dans le panneau Details et appeler le setter dans le code empruntent le même chemin. Les propriétés portant Interp peuvent recevoir des clés dans Sequencer.

Chemin de chargement

Propriétés de rendu

Propriétés de performance

Le champ Performance est de type FRenderInfo. Chaque valeur est associée à un interrupteur d'activation ; lorsque l'interrupteur est désactivé, la valeur par défaut intégrée est utilisée. La liste des champs figure dans Structs, et les recommandations de valeurs dans Paramètres de performance.

Propriétés d'étalonnage des couleurs

Les quatre composantes correspondent successivement à R, G, B et à l'ensemble. L'effet de l'étalonnage est décrit dans Réglages visuels.

Noter que ces plages ne sont que celles des curseurs du panneau (UIMin / UIMax) : il n'y a pas de Clamp. Passer au setter dans le code une valeur hors plage ne sera pas tronqué, l'effet est à vos risques. En comparaison, SplatScale et GlobalAlpha sont réellement bornés.

Propriétés de coloration du nuage de points

Propriétés de collision

Voir Collision pour le détail.

Propriétés de caméra

Les trois éléments suivants ne sont effectifs que sur la pipeline LCC1 ; le panneau Details d'un Component LCC2 masque les deux derniers.

Propriétés GIS

Les étapes de mise en place avec Cesium figurent dans Intégration avec les plugins tiers et moteur.

Propriétés de découpe et de coupe

Les trois tableaux sont BlueprintReadOnly : ne pas modifier les éléments directement, les gérer avec des méthodes comme AddClippingVolume et AddLoadVolume.

LoadVolumes n'intervient pas à la même étape que les deux autres : il filtre les données avant le chargement, et les zones écartées ne sont pas lues ; les volumes de découpe et les plans de coupe ne modifient que le résultat du rendu. Voir Volumes de chargement.

Propriétés d'animation

L'animation comporte deux étapes : à la première, après un délai de FirstStageDelay, l'échelle passe de 0 à AnimationMinScale ; à la seconde, après un délai de SecondStageDelay, elle passe de AnimationMinScale à SplatScale.

L'effet des paramètres et la manière de les régler sont décrits dans Animation de chargement.

Chargement et état

Load

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

Charge les données. C'est ce que ALCCActorBase::Load appelle en fin de compte.

Renvoie un bool : true si la validation du chemin a réussi et que la procédure de chargement a démarré. Passer un chemin vide effectue un déchargement et renvoie également true.

Points d'utilisation :

• Un retour true signifie seulement que la procédure a démarré, pas que les données sont prêtes. La version actuelle exige une interrogation avec CheckIfLoaded ; une version ultérieure fournira un callback de fin de chargement.
• Si le chemin passé est identique au chemin actuellement chargé, l'appel retourne immédiatement sans recharger.
• Un chargement réussi écrit le chemin dans 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();

Décharge les données, libère les caches de nœuds, les tampons GPU et les corps de collision, et vide DefaultLoadPath.

Deux points d'attention :

• Comme DefaultLoadPath est vidé, appeler Refresh() directement après UnLoad() ne recharge rien.
• Les métadonnées ne sont pas effacées. Après le déchargement, GetMetaInfo() et GetSplatNumber() renvoient encore les données du chargement précédent ; ne pas s'en servir pour savoir si le déchargement a eu lieu, utiliser CheckIfLoaded.

Refresh

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

Recharge les données actuelles. L'implémentation est UnLoad() suivi de Load(DefaultLoadPath), le coût équivaut donc à un rechargement complet.

L'utiliser pour relire le disque après que les fichiers de données y ont été remplacés. Pour simplement rafraîchir le rendu d'une image, utiliser ForceUpdate.

ForceUpdate

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

Marque la scène pour une mise à jour forcée à l'image suivante, le coût est très faible.

Lorsque ni la caméra ni les paramètres de rendu n'ont changé, le plugin saute la mise à jour des nœuds. Si quelque chose influant sur la visibilité a été modifié de l'extérieur et que l'image ne suit pas, l'utiliser pour pousser une image. Ne pas l'appeler à chaque image, cela annulerait l'optimisation.

CheckIfLoaded

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

Indique si les métadonnées et la structure d'index sont construites. BlueprintPure, donc un node pur sans broches d'exécution dans Blueprint.

Sens exact : LCC1 vérifie si le gestionnaire de nœuds est créé, LCC2 si l'arbre est créé. Un retour true signifie que l'analyse des métadonnées est terminée et que les métadonnées peuvent être lues et les paramètres configurés sans risque, mais les données de splats continuent d'être diffusées selon le point de vue et l'image se complète progressivement.

Autrement dit, il ne signifie pas que « l'image est complète ». Lorsqu'il faut attendre que l'image se stabilise, cette fonction ne donne pas la réponse.

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

Blueprint sous forme de texte, interrogation toutes les 0,2 seconde :

[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;

Renvoie le nombre total de splats des données, pris dans le champ TotalSplats des métadonnées.

Points d'utilisation :

• C'est le total intrinsèque des données ; il ne varie pas avec le déplacement de la caméra et ce n'est pas le nombre réellement rendu à l'image courante.
• Avant le premier chargement, il renvoie 0. Mais comme UnLoad() n'efface pas les métadonnées, il renvoie encore la valeur précédente après un déchargement.
• Pour connaître la charge de rendu de l'image courante, ouvrir le panneau de statistiques avec Stats() sur l'Actor et regarder les données en temps réel.

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

HaveValidSplatData

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

Indique s'il existe des données de splats valides à rendre. Renvoie false en cas d'échec du chargement ou de données vides.

HaveValidCollisionData

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

Indique si les données comportent un fichier de collision.

Noter qu'elle ne vérifie que le nouveau format collision.lci : elle ne vérifie ni l'ancien collision.bin, ni la collision de nuage de points .ply. Or les trois formats sont pris en charge lors du chargement effectif de la collision, un jeu de données ne comportant que collision.bin peut donc faire renvoyer false à cette fonction alors que SetLCCCollisionEnable(true) réussit tout de même à charger.

Pour tester correctement les trois formats, utiliser ULCCUtilLibrary::DetermineCollisionType (en passant le répertoire des données).

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

CanRender

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

Indique si les conditions de rendu sont actuellement réunies. Le critère est l'état de visibilité du Component, plus le fait que la structure de données de la sous-classe soit construite (gestionnaire de nœuds pour LCC1, arbre pour LCC2). La validité des métadonnées n'intervient pas.

CanSetShcoef

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

Indique si les données contiennent des coefficients d'harmoniques sphériques. En pratique, cela équivaut à tester si le type de fichier est EFileType::Quality.

L'utiliser avant d'appeler SetUseShcoef, ou pour décider de griser ou non l'interrupteur des harmoniques sphériques dans l'interface.

GetMetaInfo

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

Renvoie les métadonnées des données : nom, version, système de coordonnées, nombre total de Levels, nombre total de splats, etc. Le détail des champs figure dans Structs.

Les lire après la fin du chargement ; les champs sont à zéro tant que les données ne sont pas prêtes. La valeur renvoyée est une tranche de la classe de base ; pour les champs complets de LCC1/LCC2, utiliser les méthodes dédiées des sous-classes.

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;

Renvoie la boîte englobante visible du modèle dans l'espace local du Component. Lorsque les données ne sont pas disponibles, renvoie une boîte invalide (FBox(ForceInit)) ; vérifier IsValid avant utilisation.

Pour l'espace monde, appliquer soi-même GetComponentTransform(). L'usage courant est de placer automatiquement la caméra à une position permettant de voir toute la scène.

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();
    // Compute the viewing position from Center and Radius
}

GetLccVersion

virtual ELCCVersion GetLccVersion() const;

Renvoie la version des données, ELCCVersion::LCC ou ELCCVersion::LCC2. Disponible en C++ uniquement.

Rendu

L'effet visuel et les compromis de chaque paramètre sont décrits dans Rendu et Réglages visuels ; il n'est question ici que des interfaces.

SetRenderMode / GetRenderMode

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

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

Bascule entre 3DGS (ERenderMode::Splatting) et nuage de points (ERenderMode::PointCloud).

En mode nuage de points, les éléments propres au 3DGS sont sans effet et l'opacité passe par GlobalAlpha_PointCloud.

Paramètre correspondant du panneau : Render Mode.

Component->SetRenderMode(ERenderMode::PointCloud);

Blueprint sous forme de texte :

[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();

Bascule d'avant en arrière entre 3DGS et nuage de points, sans avoir à tester l'état courant.

SetLoadMode / GetLoadMode

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

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

Contrôle le rendu des données du corps principal, des données d'environnement, ou des deux. Les valeurs figurent dans ELoadMode, et la description du panneau dans Load Mode.

ELoadMode::None équivaut à un masquage temporaire, mais conserve les données déjà chargées en mémoire, ce qui rend la reprise plus rapide qu'après un UnLoad.

Component->SetLoadMode(ELoadMode::OnlyMain);

SetLightMode / GetLightMode

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

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

Contrôle la participation à l'éclairage de la scène, ELightMode::Unlit ou ELightMode::Lit.

Les deux pipelines l'implémentent différemment :

• LCC1 procède en basculant entre les matériaux Lit / Unlit.
• LCC2 ne change pas de matériau, l'éclairage est traité à l'intérieur du shader. LCC2 exige donc aussi de configurer NormalMode pour obtenir un contraste lumineux cohérent, voir ULCC2Component et Normales et éclairage.

Les données acquises ont déjà l'éclairage du site cuit dedans, passer en Lit provoque facilement une surexposition. Sur LCC2, LightingScale permet d'abaisser la luminosité d'origine.

Ce setter est sans effet en mode nuage de points : l'affectation est ignorée en interne et un avertissement est écrit dans le journal. Pour changer le mode d'éclairage, revenir d'abord en 3DGS.

Paramètre correspondant du panneau : Light Mode.

ToggleLightMode

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

Bascule entre Unlit et Lit.

SetUseShcoef / GetUseShcoef

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

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

Active ou désactive les harmoniques sphériques. Elles apportent une variation de couleur dépendante du point de vue ; désactivées, la couleur est fixe.

Points d'utilisation :

• Cela suppose que les données contiennent des harmoniques sphériques, à tester avec CanSetShcoef. Lorsque les données sont de type Portable, aucune harmonique sphérique n'est disponible et l'élément n'est pas modifiable dans le panneau.
• Ce setter est silencieusement sans effet en mode nuage de points. En interne, il exige que les données soient de type Quality et que le mode courant ne soit pas le nuage de points ; si l'une des deux conditions manque, l'affectation est simplement ignorée.
• Sur LCC2, il est possible de baisser seulement le nombre de bandes sans désactiver complètement, voir SetSHBands.
• Description du panneau : Harmoniques sphériques (SH).

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

ToggleShcoef

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

Active ou désactive les harmoniques sphériques, utile pour comparer le résultat.

SetSplatScale / GetSplatScale

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

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

Taille des facettes de splat, plage 0,001~1,0, valeur par défaut 1,0.

Points d'utilisation :

• La valeur par défaut 1,0 est la limite supérieure, elle ne peut qu'être réduite.
• La réduire diminue l'overdraw et augmente la fréquence d'images, au prix de trous possibles dans l'image lorsque les facettes rétrécissent.
• N'affecte que le mode 3DGS.
• Description du panneau : SplatScale.

// Trade overdraw for frame rate, weigh the holes case by case
Component->SetSplatScale(0.8f);

SetGlobalAlpha / GetGlobalAlpha

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

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

Opacité globale du 3DGS, plage 0~1. Portant Interp, elle accepte des clés dans Sequencer pour des fondus.

En mode nuage de points, utiliser SetGlobalAlpha_PointCloud ; les deux valeurs sont indépendantes. Description du panneau : Alpha global.

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

Blueprint sous forme de texte, fondu sortant avec une 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;

Opacité globale du mode nuage de points, plage 0~1, valeur par défaut 0,2.

SetUseMipFilter / GetUseMipFilter

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

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

Active ou désactive le filtrage anti-scintillement, activé par défaut. Activé, il applique un filtre passe-bas avec compensation d'opacité, plus stable à différentes échelles ; désactivé, l'image est plus nette mais peut présenter de l'aliasing et du scintillement. Effectif en mode 3DGS uniquement.

Description du panneau : Mip Filter.

EnableReceiveShadows / DisableReceiveShadows

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

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

Active ou désactive la réception des ombres, fonctionnalité expérimentale.

Points d'utilisation :

• Prise en charge par la pipeline LCC1 uniquement ; le panneau Details d'un Component LCC2 masque cette propriété.
• Effective en mode 3DGS uniquement, avec un impact notable sur la performance.
• Implémentée en interne par un basculement vers un matériau dédié, la configuration du matériau est donc refaite.
• Description du panneau : Réception des ombres.

Performance

Ce groupe de setters a un comportement commun : l'appel met automatiquement l'interrupteur d'activation correspondant à true. Les getters renvoient la valeur effective ; lorsque l'interrupteur est désactivé, ils renvoient la valeur par défaut intégrée et non celle que vous avez saisie auparavant.

GetPreloadDistance est la seule exception : il renvoie la valeur brute du champ, et non la valeur effective.

Les recommandations de valeurs figurent dans Paramètres de performance et Guide d'optimisation des performances.

SetMaxDistance / GetMaxDistance

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

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

Distance de rendu maximale, en mètres, valeur par défaut intégrée 300. Les nœuds au-delà de cette distance ne sont pas rendus.

Paramètre correspondant du panneau : Max Distance.

Component->SetMaxDistance(80);

SetMaxSplatNum / GetMaxSplatNum

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

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

Nombre maximal de splats par image, exprimé en dizaines de milliers, plafond 10000. Passer 1500 signifie 15 millions.

Une valeur dépassant la capacité du GPU pour une image est automatiquement limitée. Paramètre correspondant du panneau : 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;

Facteur d'échelle du LOD, plage 0,01~20, valeur par défaut 1. Une valeur plus grande signifie moins de détail et de meilleures performances.

Le mécanisme diffère entre les deux pipelines :

• LCC1 : en plus de RangeForLevel défini dans les réglages du projet, il modifie la correspondance entre la distance et le Level.
• LCC2 : il intervient dans la sélection des nœuds comme facteur d'échelle de l'erreur en espace écran.

Une même valeur n'a donc pas un effet visuel directement comparable entre les deux pipelines ; mesurer sur chacune.

Paramètre correspondant du panneau : Level Factor.

Component->SetLevelFactor(1.5f);

SetStartLevel / GetStartLevel

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

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

Level de départ, plage 0~20, valeur par défaut 0. Le Level 0 a le détail le plus élevé ; l'augmenter permet de sauter les niveaux les plus fins et réduit nettement l'occupation mémoire vidéo et le volume chargé.

Paramètre correspondant du panneau : Start Level.

SetEndLevel / GetEndLevel

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

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

Level de fin, plage 0~20, valeur par défaut 20. Il limite le Level de l'extrémité la plus grossière et n'a généralement pas besoin d'être modifié.

Paramètre correspondant du panneau : End Level.

SetMaxCollisionDistance / GetMaxCollisionDistance

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

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

Distance maximale de chargement de la collision, en mètres, valeur par défaut intégrée 300.

Lorsqu'un test de rayon à longue distance est nécessaire, cette valeur doit couvrir la portée du test, sinon rien n'est touché.

Paramètre correspondant du panneau : Max Load Collision Distance.

SetPreloadDistance / GetPreloadDistance

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

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

Distance de préchargement, en mètres.

Attention : dans la version actuelle, la logique effective est figée à MaxDistance + 35, la valeur définie par le setter n'entre pas dans le calcul, et l'élément n'est pas exposé dans le panneau. L'interface est conservée pour la compatibilité et n'a pas à être appelée au quotidien.

Réglage des couleurs

Les propriétés d'étalonnage sont toutes des FVector4, dont les quatre composantes correspondent successivement à R, G, B et à l'ensemble. Tous les setters d'étalonnage prennent effet immédiatement. La description des effets figure dans Réglages visuels.

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

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

Offset est additif et relève aussi les zones sombres ; ColorTint est multiplicatif et laisse les zones sombres sombres. L'effet de chaque élément est décrit dans Réglage des couleurs.

// Desaturate and brighten slightly
Component->SetSaturation(FVector4(0.6f, 0.6f, 0.6f, 0.6f));
Component->SetOffset(FVector4(0.05f, 0.05f, 0.05f, 0.f));

Coloration par altitude du nuage de points

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;

Couleurs du bas et du haut du dégradé d'altitude, du bleu au rouge par défaut.

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));

Collision

SetLCCCollisionEnable

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

Active ou désactive le chargement des données de collision.

Points d'utilisation :

• Cela suppose que les données comportent un fichier de collision, à confirmer d'abord avec HaveValidCollisionData.
• La collision est diffusée en fonction de la distance, dans la limite de Performance.CollisionLoadMaxDistance.
• Une fois activée, LineTraceByChannel, le déplacement des personnages et la simulation physique du moteur sont directement utilisables.
• La première activation entraîne un coût de cuisson unique, qui peut provoquer une brève saccade. L'activer autant que possible dès la phase de chargement.
• ShowCollision() sur l'Actor permet de voir le filaire de collision et de confirmer qu'elle est bien chargée.

Description complète dans Collision.

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

GIS

Le placement géographique s'utilise souvent avec Cesium, pour poser la scène LCC sur les coordonnées réelles du globe. Les étapes de mise en place, les dépendances de plugin et les points d'attention figurent dans Intégration avec les plugins tiers et moteur.

SetGeoPlacement

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

Active ou désactive le placement de la scène selon la latitude et la longitude.

Une fois activé, la scène est positionnée automatiquement d'après les coordonnées géographiques réelles ; la position de l'Actor définie manuellement est écrasée, et l'ajustement fin se fait avec GeoLocationOffset. Lorsque plusieurs scènes LCC l'activent simultanément, elles s'alignent automatiquement d'après leurs positions relatives réelles.

Points d'utilisation :

• Un Refresh() est exécuté automatiquement en interne (déchargement puis rechargement), l'appel prend donc effet à tout moment et il n'est pas nécessaire de refaire un Load() soi-même. Le coût équivaut en revanche à un rechargement complet : ne pas basculer fréquemment.
• Cela suppose que les données contiennent des informations RTK. Le test se fait avec GetMetaInfo().IsRTK(), pas avec CanUseGeoPlace() : cette dernière exige que le placement géographique soit déjà activé et vaut donc toujours false avant l'activation.

if (Component->CheckIfLoaded() && Component->GetMetaInfo().IsRTK())
{
    Component->SetGeoPlacement(true);   // triggers an automatic reload
}

CanUseGeoPlace

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

Indique si le placement géographique est actuellement dans un état utilisable. Trois conditions doivent être réunies simultanément : bEnableGeoPlace activé, données contenant des informations RTK, et système de référencement géographique créé.

Ce n'est pas un critère indiquant « si les données prennent en charge le placement géographique ». Comme il exige que bEnableGeoPlace soit déjà true, un appel avant l'activation renvoie toujours false. Pour tester la prise en charge par les données avant l'activation, utiliser GetMetaInfo().IsRTK().

Son usage réel est de confirmer, après l'activation, que celle-ci a bien pris effet.

GetRTKBaseLocation

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

Renvoie la position de la station de base RTK convertie dans l'espace du moteur, c'est-à-dire l'origine géographique des données. C'est le point de référence lorsqu'il faut convertir des coordonnées géographiques externes en coordonnées moteur.

Note : le système de référencement géographique est utilisé directement en interne pour la conversion de coordonnées, sans contrôle de nullité. Un appel alors que le système de référencement géographique n'est pas encore créé provoque un plantage. Avant l'appel, confirmer que CanUseGeoPlace vaut true, ou que GetGeoReferencingSystem renvoie une valeur non nulle.

GetGeoReferencingSystem

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

Renvoie l'Actor du système de référencement géographique de la scène, créé automatiquement par le plugin lorsque le placement géographique est activé.

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);
}

Viewports multiples

Un même jeu de données peut recevoir des stratégies de rendu différentes selon la caméra ; l'usage typique est un viewport principal en 3DGS haute qualité et une mini-carte rendue en nuage de points vu de dessus via un SceneCapture.

Note : ce groupe d'interfaces ne s'applique qu'à la pipeline LCC1. Les appeler sur la pipeline LCC2 (ALCC2Actor ainsi que .sog / .spz / .ply) ne provoque pas d'erreur, mais ne donne pas le résultat attendu. Pour un rendu différencié par viewport ou un préchargement lors d'une téléportation, utiliser des données LCC1.

Ce sont des pointeurs d'objet qui sont acceptés, pas des identifiants entiers.

La solution d'ensemble pour les configurations multi-caméras et multi-écrans (nDisplay, Aximmetry, Pixotope, etc.) figure dans Intégration avec les plugins tiers et moteur.

SetPlayerLoadMode

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

Définit un LoadMode propre au contrôleur de joueur indiqué, effectif à l'image suivante.

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

SetPlayerRenderMode

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

Définit un RenderMode propre au contrôleur de joueur indiqué, effectif à l'image suivante.

SetSceneCaptureLoadMode

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

Définit un LoadMode propre au SceneCapture indiqué.

Il faut d'abord activer SceneCaptureComponent Support dans les réglages du projet, sinon le contenu LCC n'est pas rendu dans le SceneCapture.

SetSceneCaptureRenderMode

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

Définit un RenderMode propre au SceneCapture indiqué.

// Minimap: point cloud plus main body 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);

Remplace la position du joueur indiqué dans cette scène, afin de précharger les données du point d'arrivée avant une téléportation.

Le problème à résoudre : en se téléportant directement au loin, les nœuds du point d'arrivée ne sont pas encore chargés et le joueur voit d'abord un corps principal vide qui se complète ensuite progressivement.

Chronologie correcte :

ModifyPlayerTransform(destination)
        ↓ wait about 0.2 s so that the destination nodes start loading
actually teleport the player
        ↓ wait about another 0.2 s
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 sous forme de texte :

[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);

Annule le remplacement de position et rétablit l'usage de la position réelle du joueur.

L'appel est obligatoire, sinon l'ordonnancement des nœuds de ce joueur reste bloqué sur la position de remplacement et aucun nouveau nœud n'est chargé lors des déplacements.

Découpe et coupe

L'utilisation de la découpe et de la coupe est décrite dans Édition de scène, ainsi que dans ALCCClippingVolume et ALCCSectionPlane.

AddClippingVolume

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

Ajoute un volume de découpe.

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);

Retire un volume de découpe. Pour une simple désactivation temporaire, modifier le bEnabled du volume est plus léger.

AddSectionPlane

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

Ajoute un plan de coupe.

RemoveSectionPlane

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

Retire un plan de coupe.

AddLoadVolume

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

Ajoute un volume de chargement, qui filtre par zone les données à charger.

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 then load

Le filtrage a lieu pendant la phase de chargement, il faut donc le configurer avant Load. Ajouter ou retirer des volumes de chargement après la fin du chargement des données exige un rechargement pour prendre effet.

Fonctionnalité de l'édition Pro : sans licence, elle est sans effet et les données sont chargées sur toute leur étendue.

RemoveLoadVolume

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

Retire un volume de chargement. Un rechargement est là aussi nécessaire pour modifier l'étendue des données déjà chargées.

Animation de chargement

SetEnableAnimation / GetEnableAnimation

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

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

Active ou désactive l'animation, et réinitialise en même temps l'origine du chronométrage de l'animation à l'instant courant. Elle ne se limite donc pas à la phase de chargement : appelée à n'importe quel moment, elle rejoue l'animation depuis le début.

Les paramètres de chaque étape se définissent directement sur les propriétés, il n'y a pas de setter dédié. Pour que les paramètres agissent sur toute l'animation, les définir avant d'appeler cette fonction. Les modifier en cours de lecture prend aussi effet, il s'agit alors d'un ajustement en cours de route.

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

L'animation inverse (de disparition), l'ordre des appels, les valeurs des paramètres et les points pratiques figurent dans Animation de chargement.

Voir aussi

• ALCCActorBase : interfaces du côté Actor
• ULCCComponent : test de rayon sur le nuage de points, propre à LCC1
• ULCC2Component : harmoniques sphériques et modes de normales, propres à LCC2
• Enums : description des valeurs de ERenderMode, ELoadMode, ELightMode, etc.
• Structs : description des champs de FRenderInfo, FMetaInfoBase