ULCCComponentBase:3DGS Component の基底クラス
すべての LCC Component の基底クラスで、レンダリング、カラー、パフォーマンス、コリジョン、GIS などの機能を担う。ULCCComponent(LCC1)と ULCC2Component(LCC2)がこれを継承する。
| モジュール | LCC4UnrealRuntime |
| ヘッダーファイル | LCCComponentBase.h |
| 親クラス | UPrimitiveComponent、IInterface_CollisionDataProvider |
#include "LCCComponentBase.h"
Actor 経由でインスタンスを取得する。
ULCCComponentBase* Component = LCCActor->GetLCCComponent();
このページはインターフェースの索引で、各メソッドのシグネチャ、パラメーター、呼び出しの要点を説明する。パラメーターをどう調整するか、調整した結果どのような見た目とパフォーマンスの影響があるかは、対応する専題のドキュメントを参照する。
| 知りたいこと | 参照先 |
|---|---|
| レンダリングモード、球面調和、アンチエイリアス | レンダリング |
| カラー、不透明度、Splat のサイズ | 画面調節 |
| 法線モード、ライティング | 法線とライティング |
| パフォーマンスパラメーターの値の指針 | パフォーマンスパラメーター、パフォーマンス最適化ガイド |
| クリッピングと断面 | シーン編集 |
| コリジョン | コリジョン |
| 読み込みアニメーション | 読み込みアニメーション |
2つのパイプラインの違い
一部のプロパティとメソッドは基底クラスに宣言されているが、実際に実装しているのは片方のパイプラインだけである。コードを書く前に、対象のデータがどちらのパイプラインを通るかを確認する。
| インターフェース | LCC1(ULCCComponent) | LCC2(ULCC2Component) |
|---|---|---|
bReceiveShadows、EnableReceiveShadows、DisableReceiveShadows | 対応 | 非対応。パネルでは非表示 |
bEnableMultipleLCCActorAutoSort | 対応 | 非対応。パネルでは非表示 |
bUseCustomFOV、OverrideMainCameraFOV | 対応 | 非対応 |
複数ビューポート系(SetPlayerLoadMode、ModifyPlayerTransform など) | 対応 | 非対応 |
SetLightMode のマテリアル切り替え | Lit / Unlit のマテリアルを切り替える | マテリアルは切り替えず、ライティングはシェーダー内部で処理する |
Performance.LevelFactor | 距離と Level のマッピングに影響する | スクリーンスペース誤差のスケール係数として働き、仕組みが異なる |
Performance.bUseFullLoad | 既定でスイッチはオフ、値は true | 構築時にスイッチを有効、値を false に変更する |
Properties
BlueprintSetter が付いたプロパティは、Details パネルで数値をドラッグする場合とコードで Setter を呼ぶ場合が同じ経路を通る。Interp が付いたプロパティは Sequencer でキーフレームを打てる。
読み込みパス
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
DefaultLoadPath | FString | 空 | 読み込みパス。Details パネルで設定しておくとレベルの起動時に自動的に読み込む。絶対パスは D:\lcc\Tower\Tower.lcc のように、相対パスは Content を基準に Tower/Tower.lcc のように書く。Load() が成功するとこの値は実際に読み込んだパスに同期される。Refresh() はこれに依存する。UnLoad() はこれをクリアする |
レンダリングのプロパティ
| プロパティ | 型 | 既定値 | Setter | 説明 |
|---|---|---|---|---|
RenderMode | ERenderMode | Splatting | SetRenderMode | 3DGS としてレンダリングするか点群としてレンダリングするか |
LoadMode | ELoadMode | Both | SetLoadMode | 主体、環境、その両方、あるいはどちらもレンダリングしないか |
LightMode | ELightMode | Unlit | SetLightMode | シーンのライティングに参加するか |
SplatScale | float | 1.0 | SetSplatScale | Splat の面のサイズ。範囲は 0.001~1.0。1.0 がすでに上限である |
GlobalAlpha | float | 1.0 | SetGlobalAlpha | 3DGS 全体の不透明度。範囲は 0~1 |
GlobalAlpha_PointCloud | float | 0.2 | SetGlobalAlpha_PointCloud | 点群全体の不透明度。範囲は 0~1 |
bUseShcoef | bool | true | SetUseShcoef | 球面調和を有効にするか。データに球面調和が含まれない場合この項目は編集できない |
bUseMipFilter | bool | true | SetUseMipFilter | ちらつき防止のフィルター |
bCanSetShcoef | bool | — | — | データに球面調和が含まれるかの判定基準。EditDefaultsOnly で Blueprint からはアクセスできない。実行時の判定には CanSetShcoef() を使う |
bAffectAntiAliasingMethod | bool | true | — | 有効にするとプロジェクト設定に従ってアンチエイリアスの方式を自動で切り替える。アンチエイリアス を参照する |
bReceiveShadows | bool | false | — | 影を受ける。実験的機能。LCC1 のみで、かつ 3DGS モードのみ |
パフォーマンスのプロパティ
Performance フィールドの型は FRenderInfo である。各数値には有効化のスイッチが付いており、スイッチがオフのときは内蔵の既定値が使われる。フィールドの一覧は Structs を、値の指針は パフォーマンスパラメーター を参照する。
調色のプロパティ
| プロパティ | 型 | 既定値 | スライダーの範囲 | Setter |
|---|---|---|---|---|
Saturation | FVector4 | (1,1,1) | 0~2 | SetSaturation |
Contrast | FVector4 | (1,1,1) | 0~2 | SetContrast |
Gamma | FVector4 | (1,1,1) | 0~2 | SetGamma |
Offset | FVector4 | (0,0,0) | -1~1 | SetOffset |
ColorTint | FLinearColor | White | — | SetColorTint |
4 つの成分は順に R、G、B と全体に対応する。調色の効果の説明は 画面調節 を参照する。
これらの範囲はパネルのスライダーの範囲(UIMin / UIMax)にすぎず、Clamp はされない。コードで Setter に範囲外の値を渡しても切り詰められないので、結果は自己責任になる。それに対して SplatScale、GlobalAlpha は実際に Clamp される。
点群の配色のプロパティ
| プロパティ | 型 | 既定値 | Setter |
|---|---|---|---|
ElevationColorBottom | FLinearColor | Blue | SetElevationColorBottom |
ElevationColorTop | FLinearColor | Red | SetElevationColorTop |
コリジョンのプロパティ
| プロパティ | 型 | 既定値 | Setter | 説明 |
|---|---|---|---|---|
bEnableCollision | bool | false | SetLCCCollisionEnable | コリジョンデータを読み込むか。データ自体にコリジョンファイルが必要である |
詳しくは コリジョン を参照する。
カメラのプロパティ
以下の 3 項目はLCC1 パイプラインでのみ有効である。LCC2 コンポーネントの Details パネルでは後の 2 項目が非表示になる。
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
bUseCustomFOV | bool | false | 最初のカメラの FOV を上書きするか |
OverrideMainCameraFOV | float | 90.0 | 上書きに使う FOV の値。範囲は 5~180 |
bEnableMultipleLCCActorAutoSort | bool | true | 複数の LCC Actor が同一シーンにあるとき距離でソートして半透明の優先度を設定する。複数 Actor の半透明ソート を参照する |
GIS のプロパティ
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
bEnableGeoPlace | bool | false | 緯度経度に従ってシーンを配置するか |
GeoLocationOffset | FVector | (0,0,0) | 位置のオフセット |
GeoMultiply | FVector | (1,1,1) | スケールの乗数。上級者向けの項目 |
Cesium と組み合わせる構築手順は サードパーティおよびエンジンプラグインとの連携 を参照する。
クリッピングと断面のプロパティ
| プロパティ | 型 | 説明 |
|---|---|---|
ClippingVolumes | TArray<TObjectPtr<ALCCClippingVolume>> | クリッピングボリュームの配列 |
SectionPlanes | TArray<TObjectPtr<ALCCSectionPlane>> | 断面プレーンの配列 |
2 つの配列は BlueprintReadOnly である。要素を直接変更せず、AddClippingVolume などのメソッドで管理する。
アニメーションのプロパティ
アニメーションは 2 段階に分かれる。第 1 段階は FirstStageDelay の遅延後に 0 から AnimationMinScale までスケールし、第 2 段階は SecondStageDelay の遅延後に AnimationMinScale から SplatScale までスケールする。
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
bEnableAnimation | bool | false | アニメーションを有効にする。Setter の SetEnableAnimation は同時にタイムラインもリセットする |
bInverseAnimation | bool | false | 逆再生する。遠くから中心へ収縮する、つまり消失の効果になる |
InverseMaxRangeTime | float | 30.0 | 逆再生アニメーションの初期の可視半径に対応する時間。単位は秒。AnimationSpeed を掛けると実際の半径になる |
AnimationSpeed | float | 100.0 | アニメーションの速度 |
AnimationMinScale | float | 0.2 | 第 1 段階の目標スケール。範囲は 0.0001~1.0 |
FirstStageDelay | float | 0.0 | 第 1 段階の遅延。単位は秒 |
SecondStageDelay | float | 5.0 | 第 2 段階の遅延。単位は秒 |
EnvironmentDelay | float | 10.0 | 環境データの遅延。単位は秒 |
AnimationOriginOffset | FVector3f | (0,0,0) | アニメーションの開始点のオフセット |
FirstStageColor | FLinearColor | ゴールド | 第 1 段階の走査線のカラー。bUseFirstStageColor(既定でオン)が必要 |
SecondStageColor | FLinearColor | ゴールド | 第 2 段階の走査線のカラー。bUseSecondStageColor(既定でオン)が必要 |
ScanLineThickness | float | 5.0 | 走査線の幅 |
パラメーターの効果と調整方法は 読み込みアニメーション を参照する。
Loading and State
Load
UFUNCTION(BlueprintCallable, Category = "XGrids")
bool Load(FString LCCPath);
データを読み込む。ALCCActorBase::Load が最終的に呼ぶのはこれである。
| パラメーター | 型 | 説明 |
|---|---|---|
LCCPath | FString | データファイルのパス。絶対パス、または Content ディレクトリからの相対パス |
戻り値 bool:パスの検証を通り読み込みの処理が始まった場合に true を返す。空のパスを渡した場合はアンロードを実行し、同様に true を返す。
使い方の要点:
trueを返すのは処理が始まったことを意味するだけで、データが準備できたことは意味しない。現在のバージョンでは CheckIfLoaded でポーリングする必要があり、今後のバージョンで読み込み完了のコールバックを提供する予定である。- 渡したパスが現在読み込まれているパスと同じ場合はそのまま戻り、重複して読み込まない。
- 読み込みが成功するとパスが
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();
データをアンロードし、ノードのキャッシュ、GPU のバッファ、コリジョンボディを解放して、DefaultLoadPath をクリアする。
注意点が 2 つある。
DefaultLoadPathをクリアするため、UnLoad()の後に直接Refresh()を呼んでも何も再読み込みされない。- メタ情報はクリアされない。アンロード後も
GetMetaInfo()とGetSplatNumber()は前回読み込んだデータを返すので、これらでアンロード済みかを判定しない。判定には CheckIfLoaded を使う。
Refresh
UFUNCTION(BlueprintCallable, Category = "XGrids")
void Refresh();
現在のデータを再読み込みする。実装は UnLoad() と Load(DefaultLoadPath) であり、コストは完全な再読み込みと同等である。
ディスク上のデータファイルが差し替えられた後、これでディスクから読み直す。レンダリングを 1 フレーム更新したいだけの場合は ForceUpdate を使う。
ForceUpdate
UFUNCTION(BlueprintCallable, Category = "XGrids")
void ForceUpdate();
次のフレームでシーンを 1 回強制的に更新するようマークする。コストはとても小さい。
カメラとレンダリングのパラメーターがどちらも変わっていない場合、プラグインはノードの更新をスキップする。外部から可視性に影響するものを変更したのに画面が追いついていない場合は、これで 1 フレーム押す。毎フレーム呼ぶとスキップの最適化が効かなくなるので、そうしない。
CheckIfLoaded
UFUNCTION(BlueprintPure, Category = "XGrids")
virtual bool CheckIfLoaded() const;
メタ情報とインデックスの構造が構築済みかを返す。BlueprintPure なので Blueprint では実行ピンのない純粋なノードになる。
正確な意味:LCC1 ではノードマネージャーが作成済みかを判定し、LCC2 ではツリーが作成済みかを判定する。true を返すのはメタ情報の解析が完了し、メタ情報の読み取りとパラメーターの設定を安全に行えることを意味するが、Splat のデータは引き続き視点に応じてストリーミング読み込みされ、画面は徐々に補完されていく。
つまり「画面が完全になった」ことは意味しない。画面が安定するのを待ちたい場面では、この関数は答えを与えられない。
if (Component->CheckIfLoaded())
{
// 安全にメタ情報を読み取り、パラメーターを設定できる
}
テキスト形式の Blueprint。0.2 秒ごとにポーリングする。
[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]
│
▼
(読み込み完了後の設定)
GetSplatNumber
UFUNCTION(BlueprintCallable, Category = "XGrids")
int GetSplatNumber() const;
データの Splat の総数を返す。メタ情報の TotalSplats から取得する。
使い方の要点:
- これはデータ固有の総量であり、カメラの移動によって変化しない。現在のフレームで実際にレンダリングしている数ではない。
- 初回の読み込み前は 0 を返す。ただし
UnLoad()はメタ情報をクリアしないため、アンロード後も前回の値を返す。 - 現在のフレームのレンダリングの負荷を知りたい場合は、Actor の
Stats()で統計パネルを開いてリアルタイムのデータを見る。
if (Component->CheckIfLoaded())
{
UE_LOG(LogTemp, Log, TEXT("Total splats in dataset: %d"),
Component->GetSplatNumber());
}
HaveValidSplatData
UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool HaveValidSplatData();
レンダリングできる有効な Splat のデータがあるかを返す。読み込みに失敗した場合やデータが空の場合は false を返す。
HaveValidCollisionData
UFUNCTION(BlueprintCallable, Category = "XGrids")
bool HaveValidCollisionData();
データにコリジョンファイルが付属しているかを返す。
注意すべき点として、これは新しい形式の collision.lci のみを確認する。旧形式の collision.bin は確認せず、点群の .ply のコリジョンも確認しない。一方で実際にコリジョンを読み込むときは 3 つの形式すべてに対応するため、collision.bin しか持たないデータセットでは、この関数が false を返すのに SetLCCCollisionEnable(true) では正常に読み込めるという状況が起きる。
3 つの形式を正確に判定するには ULCCUtilLibrary::DetermineCollisionType を使う(データのあるディレクトリを渡す)。
if (Component->HaveValidCollisionData())
{
Component->SetLCCCollisionEnable(true);
}
CanRender
UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool CanRender() const;
現在レンダリングの条件を満たしているかを返す。判定の基準はコンポーネントの可視性の状態と、サブクラスのデータ構造が構築済みかどうか(LCC1 はノードマネージャー、LCC2 はツリーを見る)である。メタ情報の有効性には関与しない。
CanSetShcoef
UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanSetShcoef() const;
データに球面調和の係数が含まれるかを返す。実装上はファイルタイプが EFileType::Quality かを判定するのと等価である。
SetUseShcoef を呼ぶ前にこれで判定する。UI 上で球面調和のスイッチをグレーアウトするかを決めるのにも使える。
GetMetaInfo
UFUNCTION(BlueprintPure, Category = "XGrids")
virtual FMetaInfoBase GetMetaInfo() const;
データのメタ情報を返す。名前、バージョン、座標系、Level の総数、Splat の総数などを含む。フィールドの詳細は Structs を参照する。
読み込みが完了してから読み取る。準備できていない場合はフィールドがゼロ値になる。返るのは基底クラスのスライスなので、LCC1/LCC2 の完全なフィールドが必要な場合はサブクラスの専用メソッドを使う。
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;
モデルのコンポーネントのローカル空間における可視のバウンディングボックスを返す。データが使えない場合は無効なボックス(FBox(ForceInit))を返すので、使う前に IsValid を確認する。
ワールド空間が必要な場合は GetComponentTransform() で自分で変換する。よくある用途は、シーン全体が収まる位置にカメラを自動で配置することである。
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();
// Center と Radius から観察位置を計算する
}
GetLccVersion
virtual ELCCVersion GetLccVersion() const;
データのバージョンを返す。ELCCVersion::LCC または ELCCVersion::LCC2 である。C++ からのみ利用できる。
Rendering
各パラメーターの見た目の効果とトレードオフは レンダリング と 画面調節 を参照する。ここではインターフェースのみを説明する。
SetRenderMode / GetRenderMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetRenderMode(ERenderMode InRenderMode);
UFUNCTION(BlueprintPure, Category = "XGrids")
ERenderMode GetRenderMode() const;
3DGS(ERenderMode::Splatting)と点群(ERenderMode::PointCloud)を切り替える。
点群モードでは 3DGS 専用の項目が効かず、不透明度は GlobalAlpha_PointCloud を使う。
対応するパネルのパラメーターは レンダリングモード である。
Component->SetRenderMode(ERenderMode::PointCloud);
テキスト形式の Blueprint:
[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();
3DGS と点群を交互に切り替える。現在の状態を自分で判定する必要がない。
SetLoadMode / GetLoadMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLoadMode(ELoadMode Mode);
UFUNCTION(BlueprintPure, Category = "XGrids")
ELoadMode GetLoadMode() const;
主体のデータ、環境のデータ、またはその両方のどれをレンダリングするかを制御する。値は ELoadMode を、パネルの説明は 読み込みモード を参照する。
ELoadMode::None は一時的に隠すのに相当するが、読み込み済みのデータはメモリに保持されるため、UnLoad よりも復帰が速い。
Component->SetLoadMode(ELoadMode::OnlyMain);
SetLightMode / GetLightMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void SetLightMode(ELightMode InLightMode);
UFUNCTION(BlueprintPure, Category = "XGrids")
ELightMode GetLightMode() const;
シーンのライティングに参加するかを制御する。ELightMode::Unlit または ELightMode::Lit である。
2 つのパイプラインで実装の方法が異なる。
- LCC1 は Lit / Unlit のマテリアルを切り替えることで実現する。
- LCC2 はマテリアルを切り替えず、ライティングをシェーダー内部で処理する。そのため LCC2 では妥当な明暗を得るために
NormalModeも設定する必要がある。詳しくは ULCC2Component と 法線とライティング を参照する。
撮影したデータには現場のライティングがすでにベイクされているため、Lit に切り替えると露出オーバーになりやすい。LCC2 では LightingScale で元の明るさを下げられる。
点群モードではこの Setter は無効になり、内部で代入をスキップして警告ログを 1 行出力する。ライティングモードを変更するには、まず 3DGS に戻す。
対応するパネルのパラメーターは ライティングモード である。
ToggleLightMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleLightMode();
Unlit と Lit を切り替える。
SetUseShcoef / GetUseShcoef
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseShcoef(bool InUseShcoef);
UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseShcoef() const;
球面調和を切り替える。球面調和は視点に依存したカラーの変化を与え、オフにするとカラーが固定される。
使い方の要点:
- 前提としてデータに球面調和が含まれている必要がある。CanSetShcoef で判定する。 データが
Portableタイプの場合は使える球面調和がなく、この項目はパネルで編集できない。 - 点群モードではこの Setter は黙って無効になる。 内部ではデータが
Qualityタイプであり、かつ現在が点群モードでないことを要求しており、2 つの条件が満たされない場合は代入が直接スキップされる。 - LCC2 では完全にオフにせず次数だけ下げることもできる。SetSHBands を参照する。
- パネルの説明は 球面調和係数(SH) を参照する。
if (Component->CanSetShcoef())
{
Component->SetUseShcoef(false);
}
ToggleShcoef
UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleShcoef();
球面調和を切り替える。効果を比較するのに使う。
SetSplatScale / GetSplatScale
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSplatScale(float InSplatScale);
UFUNCTION(BlueprintPure, Category = "XGrids")
float GetSplatScale() const;
Splat の面のサイズ。範囲は 0.001~1.0、既定値は 1.0 である。
使い方の要点:
- 既定値 1.0 が上限なので、小さくする方向にしか調整できない。
- 小さくすると Overdraw が減ってフレームレートが上がるが、面が小さくなって画面に穴が空くことがある。
- 3DGS モードにのみ影響する。
- パネルの説明は SplatScale を参照する。
// Overdraw を抑えてフレームレートを取る。穴とのバランスを状況に応じて判断する
Component->SetSplatScale(0.8f);
SetGlobalAlpha / GetGlobalAlpha
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha(float InGlobalAlpha);
UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha() const;
3DGS 全体の不透明度。範囲は 0~1 である。Interp が付いているため、Sequencer でキーフレームを打ってフェードイン / フェードアウトを作れる。
点群モードでは SetGlobalAlpha_PointCloud を使う。2 つの値は独立している。パネルの説明は グローバル不透明度 を参照する。
// フレームごとにフェードアウトする
const float Next = FMath::FInterpTo(
Component->GetGlobalAlpha(), 0.0f, DeltaTime, 2.0f);
Component->SetGlobalAlpha(Next);
テキスト形式の Blueprint。Timeline でフェードアウトする。
[Timeline: FadeOut]
Length = 2.0
Float Track "Alpha" = 1.0 → 0.0
│ Update
▼
[Set Global Alpha]
Target = (LCC Component)
In Global Alpha = (Timeline の Alpha 出力)
SetGlobalAlpha_PointCloud / GetGlobalAlpha_PointCloud
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha_PointCloud(float InGlobalAlpha);
UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha_PointCloud() const;
点群モードの全体の不透明度。範囲は 0~1、既定値は 0.2 である。
SetUseMipFilter / GetUseMipFilter
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseMipFilter(bool InUseMipFilter);
UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseMipFilter() const;
ちらつき防止のフィルターを切り替える。既定でオンである。オンのときは不透明度の補正を伴うローパスフィルターを使うため、スケールが変わっても安定する。オフのときはよりシャープになるが、エイリアシングによるちらつきが出ることがある。3DGS モードでのみ有効である。
パネルの説明は Mip Filter を参照する。
EnableReceiveShadows / DisableReceiveShadows
UFUNCTION(BlueprintCallable, Category = "XGrids")
void EnableReceiveShadows();
UFUNCTION(BlueprintCallable, Category = "XGrids")
void DisableReceiveShadows();
影の受光を切り替える。実験的な機能である。
使い方の要点:
- LCC1 パイプラインのみ対応する。 LCC2 コンポーネントの Details パネルではこのプロパティが非表示になる。
- 3DGS モードでのみ有効で、パフォーマンスへの影響が大きい。
- 内部では専用のマテリアルに切り替えることで実現するため、マテリアルの設定を再度通ることになる。
- パネルの説明は 影の受光 を参照する。
Performance
このグループの Setter には共通の挙動がある。呼び出すと対応する有効化のスイッチを自動的に true にする。 Getter は実効値を返し、スイッチがオフのときは以前に入力した値ではなく内蔵の既定値を返す。
GetPreloadDistance は唯一の例外で、実効値ではなく元のフィールドの値を返す。
値の指針は パフォーマンスパラメーター と パフォーマンス最適化ガイド を参照する。
SetMaxDistance / GetMaxDistance
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxDistance(const int32 InDistance);
UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxDistance() const;
最大レンダリング距離。単位はメートルで、内蔵の既定値は 300 である。この距離を超えたノードはレンダリングしない。
対応するパネルのパラメーターは Max Distance である。
Component->SetMaxDistance(80);
SetMaxSplatNum / GetMaxSplatNum
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxSplatNum(const int32 InSplatNum);
UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxSplatNum() const;
1 フレームあたりの最大 Splat 数。単位は万で、上限は 10000 である。1500 を渡すと 1500 万を意味する。
GPU の 1 フレームの能力を超える値は自動的に制限される。対応するパネルのパラメーターは Max Splat Num である。
Component->SetMaxSplatNum(1500); // 1500 万
SetLevelFactor / GetLevelFactor
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLevelFactor(const float InLevelFactor);
UFUNCTION(BlueprintPure, Category = "XGrids")
float GetLevelFactor() const;
LOD のスケール係数。範囲は 0.01~20、既定値は 1 である。値が大きくなるとディテールが減ってパフォーマンスが良くなる。
2 つのパイプラインで働く仕組みが異なる。
- LCC1:プロジェクト設定の
RangeForLevelを割ることで、距離と Level のマッピング関係を変える。 - LCC2:スクリーンスペース誤差のスケール係数としてノードの選択に関与する。
そのため同じ数値でも 2 つのパイプラインでの見た目の効果を直接類推することはできず、それぞれ実測する。
対応するパネルのパラメーターは 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。範囲は 0~20、既定値は 0 である。Level 0 がディテールが最も高い。上げると最も細かい階層をスキップでき、ビデオメモリの使用量と読み込み量を大きく下げられる。
対応するパネルのパラメーターは Start Level である。
SetEndLevel / GetEndLevel
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetEndLevel(const int32 InEndLevel);
UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetEndLevel() const;
終了 Level。範囲は 0~20、既定値は 20 である。最も粗い側の Level を制限する。通常は変更する必要はない。
対応するパネルのパラメーターは End Level である。
SetMaxCollisionDistance / GetMaxCollisionDistance
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxCollisionDistance(const int32 InMaxCollisionDistance);
UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxCollisionDistance() const;
コリジョンの読み込みの最大距離。単位はメートルで、内蔵の既定値は 300 である。
遠距離のレイキャストが必要な場合、この値が検出範囲を覆っている必要がある。そうでないと当たらない。
対応するパネルのパラメーターは Max Load Collision Distance である。
SetPreloadDistance / GetPreloadDistance
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPreloadDistance(const int32 InPreloadDistance);
UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetPreloadDistance() const;
プリロードの距離。単位はメートルである。
注意:現在のバージョンでは実効のロジックが MaxDistance + 35 に固定されており、Setter で設定した値は計算に使われない。この項目はパネルにも露出していない。インターフェースを残しているのは互換性のためであり、日常的に呼び出す必要はない。
Color Adjustment
調色のプロパティはいずれも FVector4 で、4 つの成分は順に R、G、B と全体に対応する。すべての調色の Setter は即座に反映される。効果の説明は 画面調節 を参照する。
UFUNCTION(BlueprintCallable, Category = "XGrids|Color")
void SetSaturation(const FVector4 InSaturation); // 彩度、0~2
void SetContrast(const FVector4 InContrast); // コントラスト、0~2
void SetGamma(const FVector4 InGamma); // ガンマ、0~2
void SetOffset(const FVector4 InOffset); // 加算的なオフセット、-1~1
void SetColorTint(const FLinearColor InColor); // 色味の乗算
// 対応する Getter
FVector4 GetSaturation() const;
FVector4 GetContrast() const;
FVector4 GetGamma() const;
FVector4 GetOffset() const;
FLinearColor GetColorTint() const;
Offset は加算なので暗部も一緒に持ち上がる。ColorTint は乗算なので暗部は暗いままである。各項目の効果は カラー調整 を参照する。
// 彩度を下げてわずかに明るくする
Component->SetSaturation(FVector4(0.6f, 0.6f, 0.6f, 0.6f));
Component->SetOffset(FVector4(0.05f, 0.05f, 0.05f, 0.f));
点群の標高着色
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;
標高のグラデーションの下端と上端のカラー。既定は青から赤である。
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);
コリジョンデータの読み込みを切り替える。
| パラメーター | 型 | 説明 |
|---|---|---|
InEnable | bool | true でコリジョンを読み込み、false で読み込み済みのコリジョンボディをアンロードする |
使い方の要点:
- 前提としてデータにコリジョンファイルが付属している必要がある。先に HaveValidCollisionData で確認する。
- コリジョンは距離に応じたストリーミング読み込みで、
Performance.CollisionLoadMaxDistanceの制限を受ける。 - 有効にするとエンジンの
LineTraceByChannel、キャラクターの移動、物理シミュレーションを直接使える。 - 初めて有効にするときに 1 回ベイクのコストが発生し、短いカクつきが起きることがある。できるだけ読み込みの段階で有効にしておく。
- Actor の
ShowCollision()でコリジョンのワイヤーフレームを見て、読み込まれているかを確認できる。
完全な説明は コリジョン を参照する。
if (Component->HaveValidCollisionData())
{
Component->SetMaxCollisionDistance(50);
Component->SetLCCCollisionEnable(true);
}
GIS
地理配置は Cesium と組み合わせて使うことが多く、LCC のシーンを実際の地球座標に配置する。構築手順、プラグインの依存関係、注意事項は サードパーティおよびエンジンプラグインとの連携 を参照する。
SetGeoPlacement
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGeoPlacement(bool InEnable);
緯度経度に従ってシーンを配置するかを切り替える。
有効にするとシーンが実際の地理座標に従って自動的に配置され、手動で設定した Actor の位置は上書きされる。微調整には GeoLocationOffset を使う。複数の LCC シーンで同時に有効にすると、実際の相対位置に従って自動的に整列する。
使い方の要点:
- 内部で
Refresh()が 1 回自動的に実行される(アンロードと再読み込み)ため、いつ呼んでも反映される。自分でLoad()をやり直す必要はない。引き換えにコストは完全な再読み込みと同等なので、頻繁に切り替えない。 - 前提としてデータに RTK の情報が含まれている必要がある。判定には
GetMetaInfo().IsRTK()を使い、CanUseGeoPlace()は使わない。 後者は地理配置がすでに有効であることを要求するため、有効にする前は常にfalseになる。
if (Component->CheckIfLoaded() && Component->GetMetaInfo().IsRTK())
{
Component->SetGeoPlacement(true); // 自動的に再読み込みされる
}
CanUseGeoPlace
UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanUseGeoPlace() const;
地理配置が現在使用可能な状態かを返す。3 つの条件を同時に満たす必要がある。bEnableGeoPlace が有効であること、データに RTK の情報が含まれること、地理参照系が作成済みであること。
これは「データが地理配置に対応しているか」の判定基準ではない。 bEnableGeoPlace がすでに true であることを要求するため、有効にする前に呼ぶと常に false を返す。有効にする前にデータが対応しているかを判定したい場合は GetMetaInfo().IsRTK() を使う。
実際の用途は、有効にした後に本当に反映されたかを確認することである。
GetRTKBaseLocation
UFUNCTION(BlueprintCallable, Category = "XGrids")
FVector GetRTKBaseLocation() const;
RTK の基準局の位置をエンジン空間に換算した座標、つまりデータの地理原点を返す。外部の地理座標をエンジン座標に換算する必要があるとき、これが基準点になる。
注意:内部で地理参照系を直接使って座標変換を行い、null チェックをしない。地理参照系がまだ作成されていない状態で呼ぶとクラッシュする。呼ぶ前に CanUseGeoPlace が
trueであること、または GetGeoReferencingSystem が非 null を返すことを確認する。
GetGeoReferencingSystem
UFUNCTION(BlueprintCallable, Category = "XGrids")
ALCCGeoReferencingSystem* GetGeoReferencingSystem() const;
シーン内の地理参照系の Actor を返す。地理配置を有効にするとプラグインが自動的に作成する。
ALCCGeoReferencingSystem* GeoSystem = Component->GetGeoReferencingSystem();
if (GeoSystem)
{
// 投影座標をエンジン座標に変換する
FVector EngineLocation;
GeoSystem->ProjectedToEngine(ProjectedCoord, EngineLocation);
// その地点の東 / 北 / 天の方向を取得する
FVector East, North, Up;
GeoSystem->GetENUVectorsAtEngineLocation(EngineLocation, East, North, Up);
}
Multi-Viewport
同じデータに対してカメラごとに異なるレンダリングの方針を設定できる。典型的な用途は、メインビューポートで 3DGS の高画質を走らせ、ミニマップでは SceneCapture で点群のトップビューをレンダリングすることである。
注:このインターフェース群はLCC1 パイプラインにのみ適用される。LCC2 パイプライン(
ALCC2Actorおよび.sog/.spz/.ply)で呼んでもエラーにはならないが、期待した結果にはならない。複数ビューポートで差をつけたレンダリングやテレポートのプリロードが必要な場合は LCC1 のデータを使う。
受け取るのはオブジェクトのポインターであり、整数の ID ではない。
複数カメラや複数画面出力の全体的な方式(nDisplay、Aximmetry、Pixotope など)は サードパーティおよびエンジンプラグインとの連携 を参照する。
SetPlayerLoadMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerLoadMode(class APlayerController* PlayerController, ELoadMode InLoadMode);
指定したプレイヤーコントローラーに対して個別に LoadMode を設定する。次のフレームで反映される。
APlayerController* PC2 = UGameplayStatics::GetPlayerController(GetWorld(), 1);
Component->SetPlayerLoadMode(PC2, ELoadMode::OnlyMain);
SetPlayerRenderMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerRenderMode(class APlayerController* PlayerController, ERenderMode InRenderMode);
指定したプレイヤーコントローラーに対して個別に RenderMode を設定する。次のフレームで反映される。
SetSceneCaptureLoadMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureLoadMode(class USceneCaptureComponent2D* InCapture2D, ELoadMode InLoadMode);
指定した SceneCapture に対して個別に LoadMode を設定する。
先にプロジェクト設定で SceneCaptureComponent Support をオンにする必要がある。そうしないと SceneCapture 内で LCC の内容がレンダリングされない。
SetSceneCaptureRenderMode
UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureRenderMode(class USceneCaptureComponent2D* InCapture2D, ERenderMode InRenderMode);
指定した SceneCapture に対して個別に RenderMode を設定する。
// ミニマップは点群 + 主体のみにしてコストを最小にする
Component->SetSceneCaptureRenderMode(MinimapCapture, ERenderMode::PointCloud);
Component->SetSceneCaptureLoadMode(MinimapCapture, ELoadMode::OnlyMain);
ModifyPlayerTransform
UFUNCTION(BlueprintCallable, Category = "XGrids")
void ModifyPlayerTransform(class APlayerController* PlayerController, FTransform InTransform);
このシーンにおける指定したプレイヤーの位置を上書きする。テレポート前に目的地のデータをプリロードするために使う。
解決したい問題:遠くへ直接テレポートすると目的地のノードがまだ読み込まれておらず、プレイヤーには主体が一面空白で、その後徐々に補完される様子が見えてしまう。
正しい順序:
ModifyPlayerTransform(目的地)
↓ 0.2 秒ほど待って目的地のノードの読み込みを始めさせる
実際にプレイヤーをテレポートする
↓ さらに 0.2 秒ほど待つ
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:
[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);
位置の上書きを取り消し、プレイヤーのリアルタイムの位置を使う状態に戻す。
必ず呼ぶ必要がある。呼ばないとそのプレイヤーのノードのスケジューリングが上書きした位置に留まり続け、移動しても新しいノードが読み込まれなくなる。
Clipping and Section
クリッピングと断面の使い方は シーン編集、および ALCCClippingVolume、ALCCSectionPlane を参照する。
AddClippingVolume
UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddClippingVolume(ALCCClippingVolume* InClippingVolume);
クリッピングボリュームを追加する。
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);
クリッピングボリュームを削除する。一時的に無効にするだけなら、クリッピングボリュームの bEnabled を変更するほうが軽い。
AddSectionPlane
UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddSectionPlane(ALCCSectionPlane* InSectionPlane);
断面プレーンを追加する。
RemoveSectionPlane
UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveSectionPlane(ALCCSectionPlane* InSectionPlane);
断面プレーンを削除する。
Loading Animation
SetEnableAnimation / GetEnableAnimation
UFUNCTION(BlueprintCallable, Category = "XGrids|Animation")
void SetEnableAnimation(bool bInEnableAnimation);
UFUNCTION(BlueprintPure, Category = "XGrids|Animation")
bool GetEnableAnimation() const;
アニメーションを切り替え、同時にアニメーションの計時の起点を現在の時刻にリセットする。したがって読み込みの段階に限らず、どのタイミングで呼んでもアニメーションが最初から再生される。
各段階のパラメーターはプロパティを直接設定する。個別の Setter はない。パラメーターをアニメーション全体に完全に効かせたい場合は、先にパラメーターを設定してからこの関数を呼ぶ。再生中にパラメーターを変更しても反映されるが、それは途中での調整にあたる。
Component->AnimationSpeed = 30.0f;
Component->SecondStageDelay = 1.0f;
Component->SetEnableAnimation(true);
逆再生(消失)アニメーション、呼び出しの順序、パラメーターの値、実践のポイントは 読み込みアニメーション を参照する。
See Also
- ALCCActorBase:Actor 側のインターフェース
- ULCCComponent:LCC1 専用の点群のレイキャスト
- ULCC2Component:LCC2 専用の球面調和と法線モード
- Enums:
ERenderMode、ELoadMode、ELightModeなどの値の説明 - Structs:
FRenderInfo、FMetaInfoBaseのフィールドの説明