Actors SOG / SPZ / PLY : chargement d'un 3DGS à fichier unique

Les trois Actors ASogActor, ASpzActor et APlyActor correspondent respectivement aux formats .sog, .spz et .ply ; ils servent à charger un fichier 3DGS unique, sans structure de répertoire LCC. Ils héritent tous de ALCCActorBase.

#include "SogActor.h"
#include "SpzActor.h"
#include "PlyActor.h"

Les trois réutilisent en interne la pipeline de rendu LCC2 complète en construisant un FLCC2MetaInfo virtuel. Autrement dit, les capacités de LCC2 sont également disponibles pour ces trois formats : contrôle du nombre de bandes d'harmoniques sphériques, modes de normales d'éclairage, découpe et coupe, réglage des couleurs. De la même manière, les limites de la pipeline LCC2 sont héritées elles aussi, comme l'inefficacité des interfaces de viewports multiples.

Formats pris en charge

L'étendue de la prise en charge de chaque format figure dans Introduction - Formats pris en charge.

Comparaison avec les formats à répertoire LCC

Critère de choix : utiliser ces trois formats quand le volume de données est modeste, qu'il s'agit de valider rapidement un résultat ou qu'une distribution en un seul fichier est nécessaire. Pour une grande scène dont la performance repose sur le LOD, le format à répertoire LCC / LCC2 est obligatoire.

Méthodes

Les interfaces publiques des trois Actors sont toutes héritées de ALCCActorBase ; seules les méthodes suivantes sont redéfinies.

SelectFile

// ASogActor
virtual void SelectFile() override;   // the dialog lists only .sog

// ASpzActor
virtual void SelectFile() override;   // the dialog lists only .spz

// APlyActor
virtual void SelectFile() override;   // the dialog lists only .ply

Ouvre la boîte de dialogue de sélection de fichier, chacune filtrant l'extension correspondante. Elle s'affiche comme un bouton Load dans le panneau Details.

Disponible dans l'éditeur uniquement ; dans une build packagée, utiliser Load.

Load (redéfini par APlyActor uniquement)

// APlyActor
virtual void Load(const FString& String) const override;

Charge un fichier .ply. Un chemin dont l'extension n'est pas .ply est rejeté immédiatement, sans tentative d'analyse.

ASogActor et ASpzActor ne redéfinissent pas Load et utilisent l'implémentation de la classe de base.

Exemples

Charger un fichier .sog unique

#include "SogActor.h"
#include "LCC2Component.h"

void AMyLoader::LoadSogFile()
{
    ASogActor* SogActor = GetWorld()->SpawnActor<ASogActor>(
        ASogActor::StaticClass(), FVector::ZeroVector, FRotator::ZeroRotator);
    if (!SogActor)
    {
        return;
    }

    SogActor->Load(TEXT("D:/Data/scene.sog"));

    // Internally a ULCC2Component, so all LCC2 capabilities are available
    ULCC2Component* Comp = Cast<ULCC2Component>(SogActor->GetLCCComponent());
    if (Comp)
    {
        Comp->SetSHBands(2);
        Comp->SetSplatScale(0.9f);
    }
}

Choisir l'Actor automatiquement d'après l'extension

Chaque format a son Actor dédié ; dans un projet réel, une répartition d'après l'extension est généralement nécessaire.

Attention, ne pas s'appuyer sur DetermineFileFormat pour cela : elle ne reconnaît que .lcc, .splats, .las et .ply, et renvoie systématiquement None pour .lcc2, .sog et .spz. Tester directement l'extension est plus fiable :

#include "Tools/LCCUtilLibrary.h"
#include "LCCActor.h"
#include "LCC2Actor.h"
#include "SogActor.h"
#include "SpzActor.h"
#include "PlyActor.h"

ALCCActorBase* AMyLoader::LoadAnyFormat(const FString& Path)
{
    if (!ULCCUtilLibrary::CheckPathValid(Path))
    {
        UE_LOG(LogTemp, Error, TEXT("Path does not exist: %s"), *Path);
        return nullptr;
    }

    const FString Ext = FPaths::GetExtension(Path).ToLower();

    UClass* ActorClass = nullptr;
    if (Ext == TEXT("lcc"))       ActorClass = ALCCActor::StaticClass();
    else if (Ext == TEXT("lcc2")) ActorClass = ALCC2Actor::StaticClass();
    else if (Ext == TEXT("sog"))  ActorClass = ASogActor::StaticClass();
    else if (Ext == TEXT("spz"))  ActorClass = ASpzActor::StaticClass();
    else if (Ext == TEXT("ply"))  ActorClass = APlyActor::StaticClass();

    if (!ActorClass)
    {
        UE_LOG(LogTemp, Error, TEXT("Unsupported format: %s"), *Path);
        return nullptr;
    }

    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(
        ActorClass, FVector::ZeroVector, FRotator::ZeroRotator);
    if (Actor)
    {
        Actor->Load(Path);
    }
    return Actor;
}

Blueprint n'a pas de node récupérant directement l'extension ; un test de chaîne fait l'affaire :

[Custom Event: LoadAnyFormat]
        Path (String)
        │
        ▼
[Check Path Valid]
        Path = Path
        │ Return Value ──┐
        ▼                │
[Branch] ◀───────────────┘
        │ True
        ▼
[Ends With]
        Source String = Path
        In Suffix = ".sog"
        Search Case = Ignore Case
        │ Return Value ──┐
        ▼                │
[Branch] ◀───────────────┘
        │ True
        ▼
[Spawn Actor from Class]
        Class = SogActor
        │ Return Value ──┐
        ▼                │
[Load] ◀─────────────────┘
        Target = (Return Value)
        String = Path

(the False branch keeps testing ".spz", ".ply", ".lcc2", ".lcc" with Ends With)

Remarques

• Ces trois formats n'ont pas de niveaux de LOD. Le chargement construit un arbre à un seul niveau et un seul nœud (nombre total de niveaux égal à 1, nœud racine sans enfants) ; les paramètres de LOD StartLevel, EndLevel et LevelFactor sont donc toujours lus, mais faute de niveau à sélectionner, ils n'ont aucun effet réel. La performance se contrôle surtout avec MaxSplatNum et SplatScale.
• Ces trois formats ne comportent pas de données de collision ; les solutions de remplacement figurent dans Collision - Solutions de remplacement pour les formats à fichier unique.
• Un fichier volumineux est chargé intégralement en une fois, l'occupation mémoire vidéo est constante et ne varie pas avec le point de vue. La limite de chargement et son mode de calcul figurent dans Rendu - Limites de chargement des formats à fichier unique.
• Le panneau Details des trois affiche bSyncLoadAtRuntime (activé par défaut), qui contrôle si le chargement dans une build packagée est synchrone pendant BeginPlay, voir ULCC2Component.
• Comme ils empruntent la pipeline de rendu LCC2, les interfaces de viewports multiples de la classe de base ne s'appliquent pas.
• Les trois mettent bUseMipFilter du Component à false à la construction (la classe de base a true par défaut) et fixent la rotation de l'Actor à (0, 0, 90).
• Le format .ply a plusieurs sous-formats ; le plugin prend en charge la variante contenant des attributs 3DGS. Le chargement d'un .ply de maillage géométrique ordinaire échoue.

Voir aussi

• ALCCActorBase : toutes les interfaces héritées
• ULCC2Component : le Component utilisé en interne par ces trois Actors
• ULCCUtilLibrary : détection du format et validation du chemin