ULCCUtilLibrary: libreria di funzioni di utilità Blueprint

Libreria di funzioni statiche di utilità che fornisce validazione dei percorsi, rilevamento del formato, operazioni sugli appunti, query di versione e altri strumenti di supporto.

#include "Tools/LCCUtilLibrary.h"

Sono tutte funzioni statiche, chiamate attraverso il nome della classe senza un'istanza:

const bool bValid = ULCCUtilLibrary::CheckPathValid(Path);

Questi nodi non richiedono un pin Target in Blueprint; cercare direttamente il nome della funzione.

Validazione dei percorsi e dei formati

Validare prima del caricamento distingue «il percorso è errato» da «i dati stessi hanno un problema» e risparmia molto tempo di analisi.

CheckPathValid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckPathValid(FString Path);

Verifica se un file esiste.

Restituisce bool: true quando il file esiste.

Note d'uso:

• Verifica solo i file, e passare il percorso di una directory restituisce false. Internamente usa una verifica di esistenza del file.
• Verifica solo l'esistenza, non se il contenuto siano dati LCC validi.
• È la prima verifica del processo di caricamento, che esclude un percorso digitato male o un file spostato.

if (!ULCCUtilLibrary::CheckPathValid(Path))
{
    UE_LOG(LogTemp, Error, TEXT("Path does not exist: %s"), *Path);
    return;
}

CheckLCCValid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckLCCValid(FString Path, FString& OutWorkPath);

Verifica se i dati siano dati LCC1 validi.

Restituisce bool: true quando è valido.

Note d'uso:

• LCC1 richiede il file .lcc stesso più data.bin e index.bin nella stessa directory, e se ne manca uno restituisce false. Il nome del file .lcc non è fisso.
• L'output OutWorkPath è la directory con il nome del file rimosso, utile quando servono altri file della stessa directory.
• I percorsi relativi sono supportati: quando il percorso passato non esiste, viene tentato ancora una volta Content/<percorso indicato>, in linea con la regola di Load().

FString WorkPath;
if (ULCCUtilLibrary::CheckLCCValid(Path, WorkPath))
{
    UE_LOG(LogTemp, Log, TEXT("Valid LCC1 data, work path: %s"), *WorkPath);
}

CheckLCC2Valid

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool CheckLCC2Valid(FString Path, FString& OutWorkPath);

Verifica un percorso LCC2 ed estrae la directory di lavoro. I parametri hanno lo stesso significato di sopra.

Note d'uso:

• LCC2 non richiede data.bin e index.bin, quindi questa funzione conferma solo che il percorso esista e prende poi la directory padre come OutWorkPath; non valida l'integrità del contenuto dei dati. La validazione reale del contenuto avviene durante il caricamento.
• Quando non è chiaro se un percorso sia LCC1 o LCC2, verificare l'estensione (.lcc o .lcc2) è l'approccio più diretto. Funziona anche provare entrambe le funzioni di validazione:

FString WorkPath;

if (Path.EndsWith(TEXT(".lcc2"), ESearchCase::IgnoreCase))
{
    if (ULCCUtilLibrary::CheckLCC2Valid(Path, WorkPath))
    {
        // usare ALCC2Actor
    }
}
else if (Path.EndsWith(TEXT(".lcc"), ESearchCase::IgnoreCase))
{
    if (ULCCUtilLibrary::CheckLCCValid(Path, WorkPath))
    {
        // usare ALCCActor
    }
}
else
{
    UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
}

Nota: non considerare «CheckLCC2Valid ha restituito true» come prova che si tratti di LCC2. La sua validazione è molto permissiva e anche un percorso .lcc restituisce true, cosa che porterebbe a confondere dati LCC1 con LCC2. Verificare prima l'estensione.

DetermineFileFormat

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static EFileFormat DetermineFileFormat(const FString& Path);

Determina il formato del file.

Restituisce EFileFormat. In realtà valuta in base all'estensione e richiede che il percorso esista:

Note d'uso:

• Questa funzione non riconosce .lcc2, .sog né .spz; tutti restituiscono None. Verificare l'estensione manualmente quando questi formati vanno coperti.
• Anche un percorso che non esiste restituisce None, quindi None ha due possibili significati: il formato non è supportato, oppure il file semplicemente non c'è. Per distinguerli, chiamare prima CheckPathValid.

Poiché la copertura è incompleta, verificare direttamente l'estensione è un approccio più solido per un loader generico:

UClass* PickActorClass(const FString& Path)
{
    const FString Ext = FPaths::GetExtension(Path).ToLower();

    if (Ext == TEXT("lcc"))  return ALCCActor::StaticClass();
    if (Ext == TEXT("lcc2")) return ALCC2Actor::StaticClass();
    if (Ext == TEXT("sog"))  return ASogActor::StaticClass();
    if (Ext == TEXT("spz"))  return ASpzActor::StaticClass();
    if (Ext == TEXT("ply"))  return APlyActor::StaticClass();

    return nullptr;
}

Per l'esempio completo vedere Actor SOG / SPZ / PLY.

DetermineSourceType

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ELCCSourceType DetermineSourceType(const FString& Path);

Determina il tipo di sorgente dei dati.

Restituisce ELCCSourceType: Local per un file locale, Http per un indirizzo di rete.

Usarla per ramificare la logica di gestione, per esempio quando i dati di rete devono prima essere scaricati oppure trasmessi in streaming.

DetermineCollisionType

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ECollisionType DetermineCollisionType(const FString& Path);

Determina il formato dei dati di collisione.

Restituisce ECollisionType:

Note d'uso:

• Passare una directory, non il percorso di un file. Passare il percorso di un file .lcc restituisce sempre None. La directory è disponibile da OutWorkPath di CheckLCCValid.
• None significa che i dati non contengono collisioni, e in tal caso abilitare bEnableCollision non ha effetto.
• Una volta caricati i dati, HaveValidCollisionData() sul Component è più semplice ed evita di comporre la directory manualmente.

Versione e ambiente

GetLCC4UnrealVersion

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCC4UnrealVersion();

Restituisce la stringa della versione del plugin.

Usi: mostrarla in una schermata delle informazioni, scriverla in un log, allegarla a una segnalazione di problema.

UE_LOG(LogTemp, Log, TEXT("LCC4Unreal version: %s"),
    *ULCCUtilLibrary::GetLCC4UnrealVersion());

GetProjectId

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetProjectId();

Restituisce l'identificatore del progetto corrente. Necessario quando si richiede una licenza o si analizza un problema di licenza.

GetLCCConfigPath

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCCConfigPath();

Restituisce il percorso del file di configurazione del plugin.

GetLCC4UnrealRootPath

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetLCC4UnrealRootPath();

Restituisce il percorso della directory radice del plugin. Usarla per comporre i percorsi quando servono le risorse distribuite con il plugin.

GetLocale

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static ELocale GetLocale();

Restituisce il locale corrente, ELocale::EN_US oppure ELocale::ZH_CN.

Ordine della decisione: la voce Language nelle impostazioni del progetto viene per prima, e quando è Always English viene restituito direttamente EN_US; altrimenti decide la lingua corrente dell'editor, e il cinese restituisce ZH_CN.

Usi: far seguire al testo della propria interfaccia l'impostazione della lingua del plugin, oppure scegliere il dominio del sito in base alla regione.

const FString DownloadUrl = (ULCCUtilLibrary::GetLocale() == ELocale::ZH_CN)
    ? TEXT("https://xgrids.cn/support/download")
    : TEXT("https://xgrids.com/intl/support/download");

Identificatori dei viewport

GetPlayerUniqueID

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool GetPlayerUniqueID(class APlayerController* PlayerController, int32& OutUniqueID);

Ottiene l'identificatore univoco di un player controller.

Restituisce bool: true in caso di successo.

Note d'uso:

• Usarlo come chiave quando si mantiene in autonomia una tabella di associazione «una configurazione per viewport».
• La normale configurazione di rendering per più viewport richiede solo il puntatore al controller passato a SetPlayerLoadMode e SetPlayerRenderMode, senza ottenere l'ID manualmente.

GetSceneCaptureUniqueID

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool GetSceneCaptureUniqueID(class USceneCaptureComponent2D* SceneCaptureComponent2D,
                                    int32& OutUniqueID);

Ottiene l'identificatore univoco di un componente SceneCapture. Parametri e valore di ritorno hanno lo stesso significato di sopra.

Appunti

CopyToClipboard

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static void CopyToClipboard(FString CopyString);

Scrive una stringa negli appunti di sistema.

Uso tipico: un pulsante «copia le informazioni di diagnostica» che agevola la segnalazione dei problemi da parte degli utenti.

void AMyDebugUI::CopyDiagnostics()
{
    const FString Info = FString::Printf(
        TEXT("Plugin: %s\nProject: %s\nSplats: %d"),
        *ULCCUtilLibrary::GetLCC4UnrealVersion(),
        *ULCCUtilLibrary::GetProjectId(),
        Component->GetSplatNumber());

    ULCCUtilLibrary::CopyToClipboard(Info);
}

GetClipboardString

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static FString GetClipboardString();

Legge il contenuto degli appunti di sistema.

Uso tipico: un pulsante «incolla il percorso dagli appunti» che evita di digitare un percorso lungo.

void AMyLoader::LoadFromClipboard()
{
    const FString Path = ULCCUtilLibrary::GetClipboardString();
    if (ULCCUtilLibrary::CheckPathValid(Path))
    {
        LCCActor->Load(Path);
    }
}

Blueprint come testo:

[Button Clicked: PasteAndLoad]
        │
        ▼
[Get Clipboard String]
        │ Return Value ──┐
        ▼                │
[Check Path Valid] ◀─────┘
        Path = (Return Value)
        │ Return Value ──┐
        ▼                │
[Branch] ◀───────────────┘
        │ True
        ▼
[Load]
        Target = LCCActor
        String = (contenuto degli appunti)

Texture

GetTextureFromBase64

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static UTexture2D* GetTextureFromBase64(const FString& Base64String);

Converte dati immagine codificati in Base64 in una texture a runtime.

Restituisce UTexture2D*: nullptr quando la conversione fallisce.

Uso: trasformare direttamente in una texture per l'interfaccia un'immagine Base64 ottenuta da un'interfaccia di rete o da un file di configurazione, senza scriverla su disco e importarla.

UTexture2D* Texture = ULCCUtilLibrary::GetTextureFromBase64(Base64Data);
if (Texture)
{
    MyImageWidget->SetBrushFromTexture(Texture);
}

Analisi delle metainformazioni SOG

Queste funzioni leggono le metainformazioni di un file .sog senza caricare i dati di rendering, cosa adatta alle anteprime dei dati e alle pagine di elenco.

ParseSogMetaFromFile

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool ParseSogMetaFromFile(const FString& FilePath, FLCC2SogMeta& OutMeta);

Analizza le metainformazioni SOG da un file.

Restituisce bool: true quando l'analisi riesce.

Note d'uso:

• Legge solo le metainformazioni e non carica i dati splat, a costo molto basso.
• Rivela il numero di punti e la presenza di armoniche sferiche di ordine superiore prima del caricamento, cosa che aiuta a decidere se serva una configurazione ridotta.

FLCC2SogMeta Meta;
if (ULCCUtilLibrary::ParseSogMetaFromFile(TEXT("D:/Data/scene.sog"), Meta))
{
    UE_LOG(LogTemp, Log, TEXT("Splat count: %d, has high-order SH: %s"),
        Meta.Count, Meta.HasShN() ? TEXT("yes") : TEXT("no"));

    // ridurre in anticipo la configurazione quando il numero di punti è troppo elevato
    if (Meta.Count > 5000000)
    {
        Component->SetMaxSplatNum(1000);
    }
}

ParseSogMetaFromData

UFUNCTION(BlueprintCallable, Category = "XGrids|Util")
static bool ParseSogMetaFromData(const TArray<uint8>& Data, FLCC2SogMeta& OutMeta);

Analizza le metainformazioni SOG da un array di byte in memoria.

Usare questa versione quando i dati provengono da un download di rete e non sono ancora stati scritti su disco.

Per i campi di FLCC2SogMeta vedere Struct.

Solo C++

Le funzioni seguenti non hanno markup UFUNCTION e possono essere chiamate solo da C++.

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

Converte il contenuto JSON di un file .lcc in uno struct FLCCMetaInfo.

Usarla per leggere e analizzare i file di metainformazioni in autonomia, per esempio per scansionare dataset in blocco durante la realizzazione di uno strumento di gestione dei dati.

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

Converte il contenuto JSON di un file .lcc2 in uno struct FLCC2MetaInfo.

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

Apre la finestra di dialogo dei file con l'estensione filtrata in base alla versione. Restituisce il percorso selezionato, oppure una stringa vuota in caso di annullamento.

Solo nell'editor. SelectFile() sull'Actor chiama questa funzione internamente.

Nota: ULCCUtilLibrary contiene anche diverse funzioni statiche destinate solo all'uso interno del plugin (calcolo del frustum, implementazione interna dell'analisi SOG, verifica delle estensioni delle sottodirectory e altre). Sono visibili al compilatore ma non fanno parte dell'API pubblica, il loro comportamento può cambiare tra le versioni e non ci si deve basare su di esse.

Esempio completo: validare prima di caricare

#include "Tools/LCCUtilLibrary.h"
#include "LCCActor.h"
#include "LCC2Actor.h"

bool AMyLoader::ValidateAndLoad(const FString& Path)
{
    // 1. esistenza del percorso
    if (!ULCCUtilLibrary::CheckPathValid(Path))
    {
        UE_LOG(LogTemp, Error, TEXT("Path does not exist: %s"), *Path);
        return false;
    }

    // 2. distinguere il formato in base all'estensione
    const FString Ext = FPaths::GetExtension(Path).ToLower();
    const bool bIsLCC1 = (Ext == TEXT("lcc"));
    const bool bIsLCC2 = (Ext == TEXT("lcc2"));

    if (!bIsLCC1 && !bIsLCC2)
    {
        // per lo smistamento di .sog / .spz / .ply vedere la pagina Actor SOG / SPZ / PLY
        UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
        return false;
    }

    // 3. validare l'integrità dei dati e ottenere allo stesso tempo la directory di lavoro
    FString WorkPath;
    const bool bValid = bIsLCC2
        ? ULCCUtilLibrary::CheckLCC2Valid(Path, WorkPath)
        : ULCCUtilLibrary::CheckLCCValid(Path, WorkPath);

    if (!bValid)
    {
        UE_LOG(LogTemp, Error, TEXT("Incomplete LCC dataset: %s"), *Path);
        return false;
    }

    // 4. istanziare l'Actor corrispondente e caricare
    UClass* ActorClass = bIsLCC2 ? ALCC2Actor::StaticClass() : ALCCActor::StaticClass();
    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(ActorClass);
    if (!Actor)
    {
        return false;
    }
    Actor->Load(Path);

    // 5. verificare nel frattempo se esistano dati di collisione. Notare che viene passata la directory di lavoro, non il percorso del file
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}

Vedere anche

• Actor SOG / SPZ / PLY: l'esempio completo di smistamento per formato
• Enum: valori di EFileFormat, ECollisionType, ELocale e altri
• Struct: campi di FLCCMetaInfo e FLCC2SogMeta