ULCC2Component：LCC2 パイプラインのコンポーネント

LCC2 パイプライン専用の Component で、ULCCComponentBase を継承する。加えて球面調和の次数の制御、ライティングの法線のシステム、深度しきい値の制御を提供する。


モジュール	`LCC4UnrealRuntime`
ヘッダーファイル	`LCC2Component.h`
親クラス	`ULCCComponentBase`
保持するもの	`ALCC2Actor`、`ASogActor`、`ASpzActor`、`APlyActor`

#include "LCC2Component.h"

インスタンスを取得する。

ULCC2Component* Comp = Cast<ULCC2Component>(LCC2Actor->GetLCCComponent());

このコンポーネントは 4 種類のデータ形式に同時に対応する。LCC2 のディレクトリ、.sog、.spz、.ply である。後の 3 つは仮想のメタ情報を構築して同じレンダリングパイプラインを再利用するため、取得できるのはいずれも ULCC2Component になる。

注：基底クラスの複数ビューポートのインターフェース（SetPlayerLoadMode、SetPlayerRenderMode、SetSceneCaptureLoadMode、SetSceneCaptureRenderMode、ModifyPlayerTransform、CancelModifyPlayerTransform）はLCC2 パイプラインには適用されない。呼んでもエラーにはならないが、期待した結果にはならない。詳しくは ULCCComponent を参照する。

Properties

プロパティ	型	既定値	範囲	説明
`SHBands`	`int32`	3	1~3	球面調和の次数。既定ではデータに格納されている次数を取り、それが上限にもなる
`LightingScale`	`float`	0.0	0~1	シーンのライティングが介入する前の 3DGS の元のカラーの明るさ
`AlphaThreshold`	`float`	0.5	0.01~0.99	中間深度の判定に使う累積不透明度のしきい値。上級者向けの項目
`NormalMode`	`ELCC2NormalGenerationMode`	`Fixed`	—	法線生成モード。3DGS がシーンのライトにどう応答するかを決める
`FixedNormal`	`FVector`	(0, 0, 1)	—	`Fixed` モードで 3DGS 全体が共有するワールド法線
`NormalPole`	`FVector`	(1, 0, 1)	—	`Hemispherical` モードでの表面の向き
`NormalHemiSpread`	`float`	0.5	0~4	`Hemispherical` モードでの明暗の変化の強さ

法線関連のプロパティには EditConditionHides が付いており、Details パネルには現在の NormalMode で使う項目だけが表示される。

基底クラスと異なる点がもう 2 つある。

MetaInfo（型は FLCC2MetaInfo）は private メンバーで、C++ 側から外部からアクセスできず、Blueprint に対してのみ見える（Details パネルでは読み取り専用）。C++ では GetMetaInfo2 で完全なフィールドを取得する。
構築時に Performance の全量読み込みの設定を「スイッチ有効、値は false」に書き換える。これは FRenderInfo の既定値とは逆である。つまり LCC2 は既定で全量読み込みを使わないので、必要なときに明示的にオンにする。

Spherical Harmonics

SetSHBands / GetSHBands

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSHBands(int32 InSHBands);

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

計算に参加する球面調和の次数を設定する。範囲は 1~3 である。このコンポーネントがレンダリングするすべての形式に効き、LCC2、SOG、SPZ、PLY を含む。

パラメーター	型	説明
`InSHBands`	`int32`	次数。1 が最も軽く、3 が最も完全である。データが実際に格納している次数を超える値は効かない

使い方の要点：

既定値は読み込んだデータから取得され、それが上限にもなる。データが 2 次までしか格納していない場合に 3 を設定しても追加の効果はない。
SetUseShcoef(false) で球面調和を完全にオフにするのに比べて、次数を下げるのはより細かいトレードオフになる。
有効になる前提は bUseShcoef がオンでレンダリングモードが 3DGS であることで、そうでない場合この値は計算に参加しない。
画質とコストのバランスは画面調節 - SH の次数を参照する。

ULCC2Component* Comp = Cast<ULCC2Component>(Actor->GetLCCComponent());
if (Comp)
{
    // 中スペックの端末では 2 次に下げる
    Comp->SetSHBands(2);
}

段階ごとに設定する書き方：

void ConfigureSH(ULCC2Component* Comp, EQualityTier Tier)
{
    if (!Comp || !Comp->CanSetShcoef())
    {
        return;   // データ自体に球面調和がないので何もしない
    }

    switch (Tier)
    {
    case EQualityTier::High:
        Comp->SetUseShcoef(true);
        Comp->SetSHBands(3);
        break;
    case EQualityTier::Medium:
        Comp->SetUseShcoef(true);
        Comp->SetSHBands(2);
        break;
    case EQualityTier::Low:
        Comp->SetUseShcoef(false);   // 直接オフにする
        break;
    }
}

Lighting

LightingScale

UPROPERTY(Interp, EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (UIMin = "0.0", UIMax = "1.0", ClampMin = "0.0", ClampMax = "1.0"))
float LightingScale = 0.0f;

シーンのライティングが介入する前の 3DGS の基本のカラーの明るさ。範囲は 0~1、既定値は 0 である。0 は完全にシーンのライティングで駆動することを、1 は元の明るさを完全に保持することを意味する。

値の影響と調整方法は法線とライティング - LCC2 のライティング輝度を参照する。

使い方の要点：

LightMode が Lit のときにのみ意味を持ち、Unlit では効かない。
BlueprintReadWrite のプロパティなので直接代入すればよく、Setter 関数はない。
Interp が付いているため、Sequencer で昼夜の変化のキーフレームを作れる。

Comp->SetLightMode(ELightMode::Lit);
Comp->LightingScale = 0.3f;    // 元の明るさの 3 割を残し、残りはシーンのライトに任せる

NormalMode

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting")
ELCC2NormalGenerationMode NormalMode = ELCC2NormalGenerationMode::Fixed;

3DGS の表面がシーンのライティングにどう応答するかを制御する。3DGS のデータ自体はジオメトリ法線を持たないため、最初の 3 つのモードはいずれも近似的な手段で法線を作り、ProxyMesh だけが実際の法線を提供する。

4 つのモードの効果の比較、適する場面、パラメーターの調整方法は法線とライティングを、値の定義は Enums を参照する。

// Fixed モード。法線を上向きに指定する
Comp->NormalMode = ELCC2NormalGenerationMode::Fixed;
Comp->FixedNormal = FVector(0.0, 0.0, 1.0);

// Hemispherical モード。ライティングが動く方向とコントラストを調整する
Comp->NormalMode = ELCC2NormalGenerationMode::Hemispherical;
Comp->NormalPole = FVector(1.0, 0.0, 1.0);
Comp->NormalHemiSpread = 1.2f;

FixedNormal

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (EditCondition = "NormalMode == ELCC2NormalGenerationMode::Fixed", EditConditionHides))
FVector FixedNormal = FVector(0.0, 0.0, 1.0);

Fixed モード専用。3DGS 全体が共有するワールド空間の法線で、既定は上向きである。正規化は不要である。

使い方の要点：

全体で 1 つの法線を共有するということは、全体の明るさが同じ値になるということで、dot(法線, ライティングの方向) に等しい。
光が法線の裏側から当たると全体が暗くなり、真っ黒になることもある。屋外のシーンで法線が上向き、光源が上方にある場合は通常問題ない。
シーンの主体が 1 枚の壁である場合は、法線を壁の向きに変更するほうが妥当である。

NormalPole

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (EditCondition = "NormalMode == ELCC2NormalGenerationMode::Hemispherical", EditConditionHides))
FVector NormalPole = FVector(1.0, 0.0, 1.0);

Hemispherical モード専用。表面がどの方向を向いているものとして扱うかを決め、ディレクショナルライトを回したときに明暗の境界が 3DGS 上をどう移動するかを決める。正規化は不要である。

調整方法：まずディレクショナルライトを配置し、そのうえでこのベクトルを調整して、明暗の境界線の走り方が期待どおりかを観察する。

NormalHemiSpread

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "XGrids|Lighting",
    meta = (UIMin = "0.0", UIMax = "4.0", ClampMin = "0.0",
        EditCondition = "NormalMode == ELCC2NormalGenerationMode::Hemispherical", EditConditionHides))
float NormalHemiSpread = 0.5f;

Hemispherical モード専用。明暗の表面上での変化の強さで、範囲は 0~4、既定値は 0.5 である。

値が小さいほど明暗が平坦で均一になり、値が大きいほど受光部と影の部分のコントラストが強くなる。

AlphaThreshold

UPROPERTY(Interp, EditAnywhere, BlueprintReadWrite, Category = "XGrids", AdvancedDisplay,
    meta = (UIMin = "0.01", UIMax = "0.99", ClampMin = "0.01", ClampMax = "0.99"))
float AlphaThreshold = 0.5f;

中間深度の判定に使う累積不透明度のしきい値。範囲は 0.01~0.99、既定値は 0.5 である。上級者向けの項目に当たる。

近い側から遠い側へ不透明度を累積し、累積値がこのしきい値に達した時点の深度をそのピクセルの代表深度として記録する。値が小さいと深度がカメラ側に寄り、大きいと遠い側に寄る。

3DGS と従来のメッシュのオクルージョンの関係、影の投影、後処理に影響する。既定値がほとんどの場合に適する。値の説明は画面調節 - 深度しきい値を参照する。

GetEffectiveNormalGenerationMode

UFUNCTION(BlueprintPure, Category = "XGrids")
ELCC2NormalGenerationMode GetEffectiveNormalGenerationMode() const;

ライセンスの検証を経て実際に有効になっている法線モードを返す。

戻り値：ライセンス済みの場合は NormalMode の元の値を返す。ライセンスの制限を受ける ProxyMesh を選んだが未ライセンスの場合は Fixed を返す。

使い方の要点：

保存されている NormalMode プロパティは変更されず、レンダリング時にフォールバック後のモードで動くだけである。したがって NormalMode を読んだ結果とこの関数の結果は一致しないことがある。
UI で通知するときにこれを使う。ユーザーが ProxyMesh を選んだのに実際には Fixed で動いている場合は、画面上で説明を出すべきである。

const ELCC2NormalGenerationMode Requested = Comp->NormalMode;
const ELCC2NormalGenerationMode Effective = Comp->GetEffectiveNormalGenerationMode();

if (Requested != Effective)
{
    UE_LOG(LogTemp, Warning,
        TEXT("ProxyMesh mode requires a license, fell back to Fixed"));
}

テキスト形式の Blueprint：

[Get Effective Normal Generation Mode]
        Target = (LCC2 Component)
        │ Return Value ──┐
        ▼                │
[Equal (Enum)] ◀─────────┘
        A = (Return Value)
        B = Proxy Mesh
        │
        ▼
[Branch]
        │ False
        ▼
[Print String]  In String = "ProxyMesh にはライセンスが必要なので Fixed にフォールバックした"

Other Methods

GetMetaInfo2

FLCC2MetaInfo GetMetaInfo2();

LCC2 の完全なメタ情報を返す。C++ からのみ利用できる。

基底クラスの GetMetaInfo() より、作業パス、データソースの種類、球面調和の次数、八分木のルートノード、ファイルの一覧などのフィールドが多い。フィールドの説明は Structs を参照する。

GetLccVersion

virtual ELCCVersion GetLccVersion() const override;

常に ELCCVersion::LCC2 を返す。