diff --git a/docs/user-manual/gaussian-splatting/building/lod-streaming.md b/docs/user-manual/gaussian-splatting/building/lod-streaming.md index 492de1ca256..2114a6748f0 100644 --- a/docs/user-manual/gaussian-splatting/building/lod-streaming.md +++ b/docs/user-manual/gaussian-splatting/building/lod-streaming.md @@ -1,16 +1,10 @@ --- title: LOD Streaming -description: "LOD streaming for large splat scenes: octree layout, generating lod-meta data, examples, and beta performance guidance." +description: "LOD streaming for large splat scenes: octree layout, generating lod-meta data, examples, and performance guidance." --- LOD (Level of Detail) Streaming enables efficient rendering of large Gaussian splat scenes by dynamically loading appropriate levels of detail based on the camera's distance. This feature dramatically reduces memory usage and improves rendering performance for large-scale splat scenes. -:::info Beta Feature - -LOD Streaming is currently in beta. If you encounter any issues, please report them on the [PlayCanvas Engine GitHub repository](https://github.com/playcanvas/engine/issues). - -::: - ## How It Works LOD streaming works by: @@ -24,15 +18,12 @@ This approach allows you to render massive splat scenes that would otherwise be ## Creating LOD Streaming Data -To use LOD streaming, you need to generate the streaming format from multiple splat files with different levels of detail. The tool takes your pre-generated LOD files and creates an optimized streaming format. - -See the [Generating LOD Format](/user-manual/splat-transform#generating-lod-format) section in the SplatTransform documentation for detailed instructions on how to create the required `lod-meta.json` format. +To use LOD streaming, you need to generate the streaming format — an octree-based `lod-meta.json` structure that organizes multiple levels of detail for efficient streaming. There are two ways to obtain the LOD levels: -:::tip +- **Provide your own LOD levels** — supply multiple splat files at progressively lower detail (LOD 0 = highest detail, higher numbers = lower detail), for example produced during training or exported separately. +- **Generate them with SplatTransform** — use [SplatTransform](/user-manual/splat-transform) to decimate a single high-quality splat into lower-detail levels, so you don't have to author them yourself. -You must create the different LOD levels yourself (LOD 0 = highest detail, higher numbers = lower detail). The tool organizes these into a streaming-optimized format but doesn't create the simplified versions. - -::: +Once you have the LOD levels, SplatTransform bundles them into the streaming-optimized format. See the [Generating LOD Format](/user-manual/splat-transform#generating-lod-format) section in the SplatTransform documentation for detailed instructions. ## Live Examples @@ -48,11 +39,7 @@ Explore these live examples to see LOD streaming in action: ## Enabling LOD Streaming -To enable LOD streaming, set the [`unified`](https://api.playcanvas.com/engine/classes/GSplatComponent.html#unified) property to `true` on your GSplat component and load a streaming LOD format asset: - -```javascript -entity.gsplat.unified = true; -``` +LOD streaming is enabled simply by loading a streaming LOD format asset (`lod-meta.json`) onto a GSplat component — no additional configuration is required. ## Controlling LOD Behavior @@ -71,7 +58,7 @@ The default multiplier of 2 gives perceptually uniform transitions under perspec ### Scene-Level Control -The [`Scene.gsplat`](https://api.playcanvas.com/engine/classes/Scene.html#gsplat) property provides access to scene-wide settings for unified gsplat rendering. This includes options for: +The [`Scene.gsplat`](https://api.playcanvas.com/engine/classes/Scene.html#gsplat) property provides access to scene-wide settings for gsplat rendering. This includes options for: - Performance tuning parameters - Debug visualization settings @@ -86,6 +73,8 @@ const gsplatSettings = app.scene.gsplat; // (See API documentation for available properties) ``` +The most important scene-level setting for LOD streaming is the global splat budget, which automatically balances detail across all GSplat assets to hit a target splat count. See [Global Splat Budget](/user-manual/gaussian-splatting/building/performance#global-splat-budget) in the Performance section for details. + ## Using LOD Streaming in the Editor Native support for LOD streaming in the PlayCanvas Editor will be added in the near future. In the meantime, you can use the Engine API in scripts to enable streaming LOD functionality in your Editor projects. diff --git a/docs/user-manual/gaussian-splatting/building/performance.md b/docs/user-manual/gaussian-splatting/building/performance.md index bcbb1cc7888..109471ebe85 100644 --- a/docs/user-manual/gaussian-splatting/building/performance.md +++ b/docs/user-manual/gaussian-splatting/building/performance.md @@ -76,6 +76,45 @@ These settings are useful for: However, for typical rendering performance management, the global splat budget is more effective than LOD range limits. The budget automatically finds the right balance across all assets, while LOD range limits apply uniformly regardless of camera position or scene composition. +### Fast Time to First Frame + +For large streamed scenes, you can display a rendered frame almost immediately by loading only the **lowest** (coarsest) level of detail first, then letting higher-detail levels stream in afterwards. This avoids waiting for high-quality data before anything appears on screen. + +The approach has two steps: + +1. When the GSplat asset is created, clamp the LOD range to the coarsest level only, so just the smallest amount of data loads first. +2. Listen for the GSplat system's `frame:ready` event. Once the coarse data has loaded and rendered — and nothing is still loading — restore the full LOD range so higher-detail levels stream in based on camera distance. + +```javascript +const gsplatSystem = app.systems.gsplat; + +// `entity` has a gsplat component using a loaded LOD-streaming asset +const gsplat = entity.gsplat; + +// 1. Start with the lowest (coarsest) LOD only, for the fastest first frame +const lodLevels = gsplat.resource?.octree?.lodLevels; +if (lodLevels) { + const worstLod = lodLevels - 1; + app.scene.gsplat.lodRangeMin = worstLod; + app.scene.gsplat.lodRangeMax = worstLod; +} + +// 2. Once the coarse data is loaded and rendered, open the LOD range back up +// so higher-detail levels stream in +const onFrameReady = (camera, layer, ready, loadingCount) => { + if (ready && loadingCount === 0) { + gsplatSystem.off('frame:ready', onFrameReady); + + // restore the full LOD range (0 = highest detail) + app.scene.gsplat.lodRangeMin = 0; + app.scene.gsplat.lodRangeMax = lodLevels - 1; + } +}; +gsplatSystem.on('frame:ready', onFrameReady); +``` + +This technique is demonstrated in the live [LOD Streaming example](/user-manual/gaussian-splatting/building/lod-streaming#live-examples). + ### Recommended Configuration For most applications: diff --git a/docs/user-manual/splat-transform/index.md b/docs/user-manual/splat-transform/index.md index beebbd82b91..eae1b675402 100644 --- a/docs/user-manual/splat-transform/index.md +++ b/docs/user-manual/splat-transform/index.md @@ -454,9 +454,12 @@ splat-transform \ ### Generating LOD Format {#generating-lod-format} -The LOD (Level of Detail) format enables efficient streaming and rendering of large Gaussian splat scenes. The tool takes multiple pre-generated LOD files as input and generates an optimized streaming format with an octree structure for progressive download. +The LOD (Level of Detail) format enables efficient streaming and rendering of large Gaussian splat scenes. SplatTransform builds an optimized streaming format with an octree structure for progressive download from a set of LOD levels, where each level has progressively fewer Gaussians (LOD 0 = highest detail, higher numbers = lower detail). -**Note:** The tool does NOT create the LOD levels themselves — you must supply multiple LOD files with progressively fewer Gaussians (LOD 0 = highest detail, higher numbers = lower detail). +You can obtain those LOD levels in two ways: + +- **Supply your own LOD files** — provide a separate splat file for each level, for example produced during training or exported from another tool. +- **Generate them by decimating a single source** — use [`--decimate`](#actions) to create the lower-detail levels from one high-quality input, so you don't have to author each level separately. :::warning Output Filename Requirements @@ -481,6 +484,20 @@ splat-transform \ --filter-nan \ --filter-harmonics 0 +# Generate the lower-detail levels by decimating a single high-quality source +# Step 1: create progressively smaller versions of the source splat +splat-transform source.ply -F 50% lod1.ply +splat-transform source.ply -F 25% lod2.ply +splat-transform source.ply -F 10% lod3.ply +# Step 2: bundle the full-detail source and the decimated levels into a streaming LOD format +splat-transform \ + source.ply -l 0 \ + lod1.ply -l 1 \ + lod2.ply -l 2 \ + lod3.ply -l 3 \ + output/lod-meta.json \ + --filter-nan + # Generate LOD with custom chunk settings for better performance splat-transform \ -C 1024 \ @@ -508,6 +525,7 @@ splat-transform scene.lcc output/lod-meta.json **Tips:** +- Use `--decimate` (`-F`) to generate lower LOD levels from a single high-quality source, instead of authoring each level separately - Use `--filter-nan` to remove invalid Gaussians before processing - Use `--filter-harmonics 0` to reduce file size if colour detail is less critical - Use `-C` to control the number of generated SOG files containing splats diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/lod-streaming.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/lod-streaming.md index f2b6d258f36..6e77f4edd22 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/lod-streaming.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/lod-streaming.md @@ -1,16 +1,10 @@ --- title: LODストリーミング -description: "大規模スプラットシーン向けLODストリーミング：オクツリー構成、lod-metaデータの生成、例、ベータ時のパフォーマンス指針です。" +description: "大規模スプラットシーン向けLODストリーミング：オクツリー構成、lod-metaデータの生成、例、パフォーマンス指針です。" --- LOD（Level of Detail）ストリーミングは、カメラの距離に基づいて適切な詳細レベルを動的にロードすることで、大規模なGaussian splatシーンの効率的なレンダリングを可能にします。この機能により、大規模なスプラットシーンのメモリ使用量を大幅に削減し、レンダリングパフォーマンスを向上させます。 -:::info ベータ機能 - -LODストリーミングは現在ベータ版です。問題が発生した場合は、[PlayCanvas Engine GitHubリポジトリ](https://github.com/playcanvas/engine/issues)で報告してください。 - -::: - ## 仕組み LODストリーミングは以下のように動作します： @@ -24,15 +18,12 @@ LODストリーミングは以下のように動作します： ## LODストリーミングデータの作成 -LODストリーミングを使用するには、異なる詳細レベルを持つ複数のスプラットファイルからストリーミング形式を生成する必要があります。ツールは事前生成されたLODファイルを受け取り、最適化されたストリーミング形式を作成します。 - -必要な`lod-meta.json`形式の作成方法の詳細については、SplatTransformドキュメントの[LOD形式の生成](/user-manual/splat-transform#generating-lod-format)セクションを参照してください。 +LODストリーミングを使用するには、ストリーミング形式（複数の詳細レベルを効率的なストリーミングのためにオクツリー構造で整理した`lod-meta.json`）を生成する必要があります。LODレベルを用意する方法は2つあります： -:::tip +- **独自のLODレベルを用意する** — 詳細度を段階的に下げた複数のスプラットファイル（LOD 0 = 最高詳細、数字が大きいほど詳細が低い）を、例えばトレーニング時に生成したものや個別にエクスポートしたものとして用意します。 +- **SplatTransformで生成する** — [SplatTransform](/user-manual/splat-transform)を使用して、1つの高品質スプラットをデシメート（簡略化）し、詳細度の低いレベルを生成できます。自分で用意する必要はありません。 -異なるLODレベルは自分で作成する必要があります（LOD 0 = 最高詳細、数字が大きいほど詳細が低い）。ツールはこれらをストリーミング最適化形式に整理しますが、簡略化バージョンは作成しません。 - -::: +LODレベルが揃ったら、SplatTransformがそれらをストリーミング最適化形式にまとめます。詳細については、SplatTransformドキュメントの[LOD形式の生成](/user-manual/splat-transform#generating-lod-format)セクションを参照してください。 ## ライブサンプル @@ -48,11 +39,7 @@ LODストリーミングの動作を確認するには、以下のライブサ ## LODストリーミングの有効化 -LODストリーミングを有効にするには、GSplatコンポーネントの[`unified`](https://api.playcanvas.com/engine/classes/GSplatComponent.html#unified)プロパティを`true`に設定し、ストリーミングLOD形式アセットをロードします： - -```javascript -entity.gsplat.unified = true; -``` +LODストリーミングは、ストリーミングLOD形式アセット（`lod-meta.json`）をGSplatコンポーネントにロードするだけで有効になります。追加の設定は必要ありません。 ## LOD動作の制御 @@ -69,7 +56,7 @@ entity.gsplat.lodDistances = [10, 20, 40, 80]; ### シーンレベルの制御 -[`Scene.gsplat`](https://api.playcanvas.com/engine/classes/Scene.html#gsplat)プロパティは、統合gsplatレンダリングのシーン全体の設定へのアクセスを提供します。これには以下のオプションが含まれます： +[`Scene.gsplat`](https://api.playcanvas.com/engine/classes/Scene.html#gsplat)プロパティは、gsplatレンダリングのシーン全体の設定へのアクセスを提供します。これには以下のオプションが含まれます： - パフォーマンスチューニングパラメータ - デバッグ可視化設定 @@ -84,6 +71,8 @@ const gsplatSettings = app.scene.gsplat; // （利用可能なプロパティについてはAPIドキュメントを参照） ``` +LODストリーミングで最も重要なシーンレベルの設定はグローバルスプラット予算で、すべてのGSplatアセット全体で目標スプラット数に収まるよう詳細度を自動的に調整します。詳細については、パフォーマンスセクションの[グローバルスプラット予算](/user-manual/gaussian-splatting/building/performance#global-splat-budget)を参照してください。 + ## エディターでのLODストリーミングの使用 PlayCanvas EditorでのLODストリーミングのネイティブサポートは近い将来追加される予定です。それまでの間、Editorプロジェクトでストリーミングロード機能を有効にするには、スクリプト内でEngine APIを使用できます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/performance.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/performance.md index 09af9cc1f47..df915436dfb 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/performance.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/gaussian-splatting/building/performance.md @@ -75,6 +75,45 @@ app.scene.gsplat.lodRangeMax = 3; // LOD 3より低くはしない ただし、一般的なレンダリングパフォーマンス管理には、LOD範囲制限よりもグローバルスプラットバジェットの方が効果的です。バジェットはすべてのアセット間で適切なバランスを自動的に見つけますが、LOD範囲制限はカメラ位置やシーン構成に関係なく一律に適用されます。 +### 最初のフレームを高速に表示する + +大規模なストリーミングシーンでは、最初に**最も低い**（最も粗い）詳細レベルだけをロードし、その後により高い詳細レベルをストリーミングで読み込むことで、ほぼ即座にレンダリング結果を表示できます。これにより、何かが画面に表示される前に高品質データの読み込みを待つ必要がなくなります。 + +この手法は2つのステップで構成されます： + +1. GSplatアセットの作成時に、LOD範囲を最も粗いレベルのみに制限し、最小限のデータだけが先にロードされるようにします。 +2. GSplatシステムの`frame:ready`イベントをリッスンします。粗いデータがロードされてレンダリングされ、かつ読み込み中のものがなくなったら、LOD範囲を元に戻し、カメラ距離に基づいてより高い詳細レベルがストリーミングされるようにします。 + +```javascript +const gsplatSystem = app.systems.gsplat; + +// `entity` は、ロード済みのLODストリーミングアセットを使用する gsplat コンポーネントを持ちます +const gsplat = entity.gsplat; + +// 1. 最初のフレームを最速にするため、最も低い（最も粗い）LODのみで開始 +const lodLevels = gsplat.resource?.octree?.lodLevels; +if (lodLevels) { + const worstLod = lodLevels - 1; + app.scene.gsplat.lodRangeMin = worstLod; + app.scene.gsplat.lodRangeMax = worstLod; +} + +// 2. 粗いデータがロードされてレンダリングされたら、LOD範囲を元に戻して +// より高い詳細レベルをストリーミングする +const onFrameReady = (camera, layer, ready, loadingCount) => { + if (ready && loadingCount === 0) { + gsplatSystem.off('frame:ready', onFrameReady); + + // 完全なLOD範囲を復元（0 = 最高詳細） + app.scene.gsplat.lodRangeMin = 0; + app.scene.gsplat.lodRangeMax = lodLevels - 1; + } +}; +gsplatSystem.on('frame:ready', onFrameReady); +``` + +この手法は、ライブの[LODストリーミングサンプル](/user-manual/gaussian-splatting/building/lod-streaming)で実演されています。 + ### 推奨設定 ほとんどのアプリケーションでは： diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/splat-transform/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/splat-transform/index.md index 4655162d2fd..3ad9f6c41d0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/splat-transform/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/splat-transform/index.md @@ -454,9 +454,12 @@ splat-transform \ ### LOD形式の生成 {#generating-lod-format} -LOD (Level of Detail) 形式は、大きなガウシアンスプラットシーンの効率的なストリーミングとレンダリングを可能にします。このツールは、事前に生成された複数のLODファイルを入力として受け取り、プログレッシブダウンロードのためにオクツリー構造を持つ最適化されたストリーミング形式を生成します。 +LOD (Level of Detail) 形式は、大きなガウシアンスプラットシーンの効率的なストリーミングとレンダリングを可能にします。SplatTransformは、段階的にガウシアンが少なくなる一連のLODレベル（LOD 0 = 最高詳細、数字が大きいほど詳細度が低い）から、プログレッシブダウンロードのためにオクツリー構造を持つ最適化されたストリーミング形式を構築します。 -**注:** このツールはLODレベル自体を作成しません — 段階的にガウシアンが少なくなる複数のLODファイルを提供する必要があります（LOD 0 = 最高詳細、数字が大きいほど詳細度が低い）。 +LODレベルは次の2つの方法で用意できます： + +- **独自のLODファイルを用意する** — 各レベルごとに個別のスプラットファイルを提供します（例：トレーニング時に生成したものや、別のツールからエクスポートしたもの）。 +- **単一のソースをデシメートして生成する** — `--decimate`を使用して、1つの高品質な入力から詳細度の低いレベルを作成できます。各レベルを個別に用意する必要はありません。 :::warning 出力ファイル名の要件 @@ -481,6 +484,20 @@ splat-transform \ --filter-nan \ --filter-harmonics 0 +# 単一の高品質ソースをデシメートして詳細度の低いレベルを生成 +# ステップ1: ソーススプラットの段階的に小さいバージョンを作成 +splat-transform source.ply -F 50% lod1.ply +splat-transform source.ply -F 25% lod2.ply +splat-transform source.ply -F 10% lod3.ply +# ステップ2: フル詳細のソースとデシメートしたレベルをストリーミングLOD形式にまとめる +splat-transform \ + source.ply -l 0 \ + lod1.ply -l 1 \ + lod2.ply -l 2 \ + lod3.ply -l 3 \ + output/lod-meta.json \ + --filter-nan + # より良いパフォーマンスのためにカスタムチャンク設定でLODを生成 splat-transform \ -C 1024 \ @@ -508,6 +525,7 @@ splat-transform scene.lcc output/lod-meta.json **ヒント:** +- `--decimate`（`-F`）を使用して、各レベルを個別に用意する代わりに、1つの高品質ソースから詳細度の低いLODレベルを生成 - `--filter-nan`を使用して、処理前に無効なガウシアンを削除 - 色の詳細がそれほど重要でない場合は、`--filter-harmonics 0`を使用してファイルサイズを削減 - `-C`を使用して、スプラットを含む生成されるSOGファイルの数を制御