ULCCUtilLibrary：Blueprint ユーティリティ関数ライブラリ

静的なユーティリティ関数のライブラリで、パスの検証、形式の識別、クリップボードの操作、バージョンの取得などの補助機能を提供する。


モジュール	`LCC4UnrealRuntime`
ヘッダーファイル	`Tools/LCCUtilLibrary.h`
親クラス	`UBlueprintFunctionLibrary`

#include "Tools/LCCUtilLibrary.h"

すべて静的関数なので、クラス名で直接呼び出し、インスタンスは不要である。

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

Blueprint ではこれらのノードに Target ピンがなく、関数名で直接検索すればよい。

Path and Format Validation

データを読み込む前に検証すると、「パスが誤っている」と「データ自体に問題がある」を切り分けられ、調査の時間を大きく節約できる。

CheckPathValid

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

ファイルが存在するかを確認する。

パラメーター	型	説明
`Path`	`FString`	確認するファイルのパス

戻り値 bool：ファイルが存在する場合に true を返す。

使い方の要点：

ファイルのみを判定するので、ディレクトリのパスを渡すと false を返す。 内部ではファイルの存在確認を使っている。
存在確認のみを行い、内容が正しい LCC データかは確認しない。
読み込みの流れの最初の確認として、パスの打ち間違いやファイルが移動されたといった問題を先に排除する。

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

有効な LCC1 のデータかを確認する。

パラメーター	型	説明
`Path`	`FString`	`.lcc` ファイルのパス。ファイル名は固定ではない
`OutWorkPath`	`FString&`	作業ディレクトリ、つまりデータファイルがあるディレクトリを出力する

戻り値 bool：有効な場合に true を返す。

使い方の要点：

LCC1 には .lcc ファイル自体と、同じディレクトリの data.bin と index.bin が必要で、1 つ欠けても false を返す。.lcc のファイル名は固定ではない。
出力される OutWorkPath はファイル名を除いたディレクトリで、同じディレクトリの他のファイルのパスを組み立てるときに使える。
相対パスに対応する。渡したパスが存在しない場合、Content/<渡したパス> を自動的にもう一度試す。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);

LCC2 のパスを確認して作業ディレクトリを取り出す。パラメーターの意味は上と同じである。

使い方の要点：

LCC2 には data.bin と index.bin が不要なので、この関数はパスの存在を確認して親ディレクトリを OutWorkPath として取るだけで、データ内容の整合性は検証しない。実際の内容の検証は読み込みの段階で行われる。
あるパスが LCC1 か LCC2 か分からない場合は、拡張子（.lcc か .lcc2 か）を見るのがもっとも直接的である。2 つの検証関数を両方試してもよい。

FString WorkPath;

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

注：「CheckLCC2Valid が true を返したから LCC2 だ」という判定で区別しない。この関数の検証はとても緩く、.lcc のパスでも true を返すため、LCC1 のデータを LCC2 と誤判定してしまう。まず拡張子を見る。

DetermineFileFormat

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

ファイルの形式を判定する。

戻り値 EFileFormat。実際には拡張子で判定し、パスが存在することも要求する。

拡張子	戻り値
`.lcc`	`LCC`
`.splats`	`Splats`
`.las`	`LAS`
`.ply`	`PLY`
その他、またはパスが存在しない	`None`

使い方の要点：

この関数は .lcc2、.sog、.spz を識別せず、いずれも None を返す。 これらの形式を扱う必要がある場合は自分で拡張子を判定する。
パスが存在しない場合も None を返すため、None が返る理由は 2 通りある。形式が非対応か、ファイルがそもそも存在しないかである。切り分けたい場合は先に CheckPathValid を呼ぶ。

網羅していないため、汎用のローダーを作るときは拡張子を直接見るほうが確実である。

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

完全な例は SOG / SPZ / PLY Actors を参照する。

DetermineSourceType

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

データのソースの種類を判定する。

戻り値 ELCCSourceType：Local はローカルのファイル、Http はネットワークのアドレスである。

処理のロジックを分けるのに使う。たとえばネットワークのデータは先にダウンロードするか、ストリーミング読み込みを使う必要がある。

DetermineCollisionType

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

コリジョンデータの形式を判定する。

パラメーター	型	説明
`Path`	`const FString&`	データがあるディレクトリであり、`.lcc` ファイルのパスではない。関数はそのディレクトリ内で `collision.lci`、`collision.bin` などのファイルを探す

戻り値 ECollisionType：

値	意味
`None`	コリジョンデータがない
`Bin`	旧形式の `.bin`
`Lci`	新形式の `.lci`
`Ply`	点群の `.ply` のコリジョン

使い方の要点：

ディレクトリを渡し、ファイルのパスを渡さない。 .lcc ファイルのパスを渡すと常に None を返す。ディレクトリは CheckLCCValid の OutWorkPath から取得できる。
None が返る場合はデータにコリジョンがないので、bEnableCollision を有効にしても効果がない。
データの読み込みが完了している場合は、Component の HaveValidCollisionData() を使うほうが手間が少なく、ディレクトリを自分で組み立てる必要がない。

Version and Environment

GetLCC4UnrealVersion

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

プラグインのバージョン番号の文字列を返す。

用途：About 画面に表示する、ログに書き込む、問題を報告するときに添付する。

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

GetProjectId

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

現在のプロジェクトの識別子を返す。ライセンスの申請やライセンスの問題の調査で提供する必要がある。

GetLCCConfigPath

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

プラグインの設定ファイルのパスを返す。

GetLCC4UnrealRootPath

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

プラグインのルートディレクトリのパスを返す。プラグイン付属のリソースにアクセスするときにパスを組み立てるのに使う。

GetLocale

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

現在のロケールを返す。ELocale::EN_US または ELocale::ZH_CN である。

判定の順序：まずプロジェクト設定の Language の項目を見て、Always English であれば直接 EN_US を返す。そうでなければエディターの現在の言語で判定し、中国語なら ZH_CN を返す。

用途：自分の UI の文言をプラグインの言語設定に合わせて切り替える、または地域に応じて公式サイトのドメインを選ぶ。

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

Viewport Identifiers

GetPlayerUniqueID

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

プレイヤーコントローラーの一意な識別子を取得する。

パラメーター	型	説明
`PlayerController`	`APlayerController*`	対象のプレイヤーコントローラー
`OutUniqueID`	`int32&`	一意な識別子を出力する

戻り値 bool：取得に成功した場合に true を返す。

使い方の要点：

「ビューポートごとに 1 組の設定」というマッピングを自分で管理する必要があるとき、これをキーとして使う。
通常の複数ビューポートのレンダリング設定は SetPlayerLoadMode、SetPlayerRenderMode にコントローラーのポインターを渡せばよく、手動で ID を取得する必要はない。

GetSceneCaptureUniqueID

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

SceneCapture コンポーネントの一意な識別子を取得する。パラメーターと戻り値の意味は上と同じである。

Clipboard

CopyToClipboard

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

文字列をシステムのクリップボードに書き込む。

パラメーター	型	説明
`CopyString`	`FString`	コピーする内容

典型的な用途：「診断情報をコピーする」ボタンを作り、ユーザーが問題を報告しやすくする。

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

システムのクリップボードの内容を読み取る。

典型的な用途：「クリップボードからパスを貼り付ける」ボタンを作り、長いパスを手入力する手間を省く。

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

テキスト形式の Blueprint：

[Button Clicked: PasteAndLoad]
        │
        ▼
[Get Clipboard String]
        │ Return Value ──┐
        ▼                │
[Check Path Valid] ◀─────┘
        Path = (Return Value)
        │ Return Value ──┐
        ▼                │
[Branch] ◀───────────────┘
        │ True
        ▼
[Load]
        Target = LCCActor
        String = (クリップボードの内容)

Texture

GetTextureFromBase64

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

Base64 でエンコードされた画像データを実行時のテクスチャに変換する。

パラメーター	型	説明
`Base64String`	`const FString&`	Base64 でエンコードされた画像データ

戻り値 UTexture2D*：変換に失敗した場合は nullptr を返す。

用途：ネットワークのインターフェースや設定ファイルから Base64 の画像を取得し、そのままテクスチャを生成して UI に使う。ディスクに保存してインポートする必要がない。

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

SOG Metadata Parsing

これらの関数は、レンダリングのデータを読み込まずに .sog ファイルのメタ情報を読み取るために使う。データのプレビューや一覧ページの表示に適する。

ParseSogMetaFromFile

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

ファイルから SOG のメタ情報を解析する。

パラメーター	型	説明
`FilePath`	`const FString&`	`.sog` ファイルのパス
`OutMeta`	`FLCC2SogMeta&`	メタ情報を出力する

戻り値 bool：解析に成功した場合に true を返す。

使い方の要点：

メタ情報のみを読み取り、Splat のデータは読み込まないので、コストはとても小さい。
これによって読み込む前に点数や高次の球面調和を含むかが分かるので、設定を下げる必要があるかの判断に使える。

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

    // 点数が大きすぎる場合は事前に設定を下げる
    if (Meta.Count > 5000000)
    {
        Component->SetMaxSplatNum(1000);
    }
}

ParseSogMetaFromData

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

メモリ上のバイト配列から SOG のメタ情報を解析する。

データがネットワークからのダウンロードで、まだディスクに保存していない場合はこちらを使う。

FLCC2SogMeta のフィールドの説明は Structs を参照する。

C++ Only

以下の関数には UFUNCTION のマークがなく、C++ からのみ呼び出せる。

ConvertStrToMetaInfo

static FLCCMetaInfo ConvertStrToMetaInfo(const FString& JsonStr);

.lcc ファイルの JSON の内容を FLCCMetaInfo 構造体に変換する。

メタ情報ファイルを自分で読み取って解析する場合に使う。たとえばデータ管理のツールを作ってデータセットを一括でスキャンするときである。

ConvertStrToLCC2MetaInfo

static FLCC2MetaInfo ConvertStrToLCC2MetaInfo(const FString& JsonStr);

.lcc2 ファイルの JSON の内容を FLCC2MetaInfo 構造体に変換する。

SelectFile

static FString SelectFile(ELCCVersion LCCVersion);

ファイル選択ダイアログを表示し、バージョンに応じて拡張子でフィルターする。選択したパスを返し、キャンセルした場合は空の文字列を返す。

エディターでのみ利用できる。Actor の SelectFile() が内部で呼んでいるのはこれである。

注：ULCCUtilLibrary にはプラグイン内部でのみ使う静的関数もいくつかある（視錐台の計算、SOG 解析の内部実装、サブディレクトリの拡張子の確認など）。コンパイル上は見えるが公開 API ではなく、挙動がバージョンによって変わる可能性があるので、依存しないようにする。

Complete Example: Validate Before Load

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

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

    // 2. 拡張子で形式を見分ける
    const FString Ext = FPaths::GetExtension(Path).ToLower();
    const bool bIsLCC1 = (Ext == TEXT("lcc"));
    const bool bIsLCC2 = (Ext == TEXT("lcc2"));

    if (!bIsLCC1 && !bIsLCC2)
    {
        // .sog / .spz / .ply の振り分けは SOG / SPZ / PLY Actors のページを参照する
        UE_LOG(LogTemp, Error, TEXT("Not an LCC dataset: %s"), *Path);
        return false;
    }

    // 3. データの整合性を検証し、同時に作業ディレクトリを取り出す
    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. 対応する Actor を生成して読み込む
    UClass* ActorClass = bIsLCC2 ? ALCC2Actor::StaticClass() : ALCCActor::StaticClass();
    ALCCActorBase* Actor = GetWorld()->SpawnActor<ALCCActorBase>(ActorClass);
    if (!Actor)
    {
        return false;
    }
    Actor->Load(Path);

    // 5. あわせてコリジョンデータの有無を確認する。渡すのは作業ディレクトリであり、ファイルのパスではない
    const ECollisionType CollisionType =
        ULCCUtilLibrary::DetermineCollisionType(WorkPath);
    UE_LOG(LogTemp, Log, TEXT("Collision type: %d"),
        static_cast<int32>(CollisionType));

    return true;
}