Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/tutorials/gaussian-splat-streaming-lod.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: '3D Gaussian Splat Streaming LOD'
description: Stream huge Gaussian splat scenes with spatial LOD and SOG ordering so large environments load progressively.
title: '3D Gaussian Splat Streamed SOG'
description: Stream huge Gaussian splat scenes with Streamed SOG so large environments load progressively.
tags: [gaussiansplatting, tutorial]
thumb: https://s3-eu-west-1.amazonaws.com/images.playcanvas.com/projects/12/1408991/3CA651-image-75.jpg
---

import Link from '@docusaurus/Link';

An example project showing how to use PlayCanvas' streaming LOD format based on [SOG](/user-manual/gaussian-splatting/formats/sog) (Spatially Ordered Gaussians). The environment being streamed is the Church of Saints Peter and Paul.
An example project showing how to use PlayCanvas' [Streamed SOG](/user-manual/gaussian-splatting/formats/streamed-sog) format, based on [SOG](/user-manual/gaussian-splatting/formats/sog) (Spatially Ordered Gaussians). The environment being streamed is the Church of Saints Peter and Paul.

<div className="iframe-container">
<iframe src="https://playcanv.as/p/ZoUBrC6e/" title="3D Gaussian Splat Streaming LOD" allow="camera; microphone; xr-spatial-tracking; fullscreen" allowfullscreen></iframe>
Comment thread
slimbuck marked this conversation as resolved.
Expand Down
61 changes: 31 additions & 30 deletions docs/user-manual/gaussian-splatting/building/lod-streaming.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,49 @@
---
title: LOD Streaming
description: "LOD streaming for large splat scenes: octree layout, generating lod-meta data, examples, and performance guidance."
title: Streamed SOG
description: "Streamed SOG for large splat scenes: spatial tree 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.
Streamed SOG enables efficient rendering of large Gaussian splat scenes by dynamically loading appropriate levels of detail (LOD) based on the camera's distance. This dramatically reduces memory usage and improves rendering performance for large-scale splat scenes.

## How It Works

LOD streaming works by:
Streamed SOG works by:

1. Pre-generating multiple versions of your splat at different detail levels
2. Organizing them into an octree structure for efficient streaming
2. Organizing them into a spatial tree structure for efficient streaming
3. Dynamically loading and unloading detail levels based on camera distance
4. Rendering only the appropriate level of detail for each region of the scene

This approach allows you to render massive splat scenes that would otherwise be impossible due to memory constraints.

## Creating LOD Streaming Data
## Creating Streamed SOG Data

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:
To use Streamed SOG, you need to generate the format — a `lod-meta.json` spatial tree structure that organizes multiple levels of detail for efficient streaming (see the [Streamed SOG Format Specification](/user-manual/gaussian-splatting/formats/streamed-sog)). There are two ways to obtain the LOD levels:

- **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.

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.
Once you have the LOD levels, SplatTransform bundles them into the Streamed SOG format. See the [Generating Streamed SOG](/user-manual/splat-transform#generating-lod-format) section in the SplatTransform documentation for detailed instructions.

## Live Examples

Explore these live examples to see LOD streaming in action:
Explore these live examples to see Streamed SOG in action:

- LOD Streaming (Basic) - Demonstrates basic LOD streaming with different detail levels
- Streamed SOG (Basic) - Demonstrates basic streaming with different detail levels

<EngineExample id="gaussian-splatting/lod-streaming" title="LOD Streaming (Basic)" />
<EngineExample id="gaussian-splatting/lod-streaming" title="Streamed SOG (Basic)" />

- LOD Streaming with Spherical Harmonics - Shows LOD streaming with spherical harmonic data
- Streamed SOG with Spherical Harmonics - Shows streaming with spherical harmonic data

<EngineExample id="gaussian-splatting/lod-streaming-sh" title="LOD Streaming with Spherical Harmonics" />
<EngineExample id="gaussian-splatting/lod-streaming-sh" title="Streamed SOG with Spherical Harmonics" />

## Enabling LOD Streaming
## Enabling Streamed SOG

LOD streaming is enabled simply by loading a streaming LOD format asset (`lod-meta.json`) onto a GSplat component — no additional configuration is required.
Streaming is enabled simply by loading a Streamed SOG asset (`lod-meta.json`) onto a GSplat component — no additional configuration is required.

## Controlling LOD Behavior

You can control and fine-tune LOD streaming using the following APIs:
You can control and fine-tune streaming behavior using the following APIs:

### Component-Level Control

Expand All @@ -54,7 +54,7 @@ entity.gsplat.lodBaseDistance = 10; // distance for the first LOD transition
entity.gsplat.lodMultiplier = 2; // each successive threshold is 2x farther
```

The default multiplier of 2 gives perceptually uniform transitions under perspective projection. The system also compensates for camera FOV automatically.
The multiplier defaults to 3 (and is clamped to a minimum of 1.2) — each LOD transition happens at three times the previous distance. The system also compensates for camera FOV automatically.

### Scene-Level Control

Expand All @@ -73,32 +73,32 @@ 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.
The most important scene-level setting for Streamed SOG 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
## Using Streamed SOG 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.
Native support for Streamed SOG in the PlayCanvas Editor will be added in the near future. In the meantime, you can use the Engine API in scripts to enable Streamed SOG functionality in your Editor projects.

### Sample Project

We've created a sample project that demonstrates how to use streaming LOD with Gaussian splats in the PlayCanvas Editor:
We've created a sample project that demonstrates how to use Streamed SOG with Gaussian splats in the PlayCanvas Editor:

**[Church of Saints Peter and Paul](https://playcanvas.com/project/1408991/overview/church-of-saints-peter-and-paul)**

This project showcases a large-scale Gaussian splat scene with LOD streaming, including custom reveal shader effects.
This project showcases a large-scale Gaussian splat scene with Streamed SOG, including custom reveal shader effects.

### Using the Streamed GSplat Script

The sample project includes a `streamed-gsplat.mjs` script that can be added to any Entity to enable LOD streaming:
The sample project includes a `streamed-gsplat.mjs` script that can be added to any Entity to enable Streamed SOG:

#### Setup Steps

1. Add the script to an Entity in your scene
2. Configure the `splatUrl` property to point to an externally hosted LOD splat format file
2. Configure the `splatUrl` property to point to an externally hosted Streamed SOG file

:::note External Hosting

Currently, the LOD splat data needs to be hosted externally (not as an Editor asset). This limitation will be removed in the future when native Editor support for streaming LOD format is added.
Currently, the Streamed SOG data needs to be hosted externally (not as an Editor asset). This limitation will be removed in the future when native Editor support for Streamed SOG is added.

:::

Expand All @@ -125,15 +125,15 @@ This demonstrates the flexibility of the PlayCanvas Engine's shader system for c

### Future Editor Improvements

As native Editor support for streaming LOD is added, the following improvements are planned:
As native Editor support for Streamed SOG is added, the following improvements are planned:

- **Direct Asset Import**: Upload LOD splat files directly as Editor assets (no external hosting needed)
- **Direct Asset Import**: Upload Streamed SOG files directly as Editor assets (no external hosting needed)
- **Visual Configuration**: Configure LOD settings through the Editor UI instead of script properties
- **Preview in Editor**: View and test streaming LOD behavior directly in the Editor viewport
- **Preview in Editor**: View and test streaming behavior directly in the Editor viewport

## Benefits

- **Better Performance**: LOD streaming reduces memory usage and improves rendering performance for large scenes
- **Better Performance**: Streamed SOG reduces memory usage and improves rendering performance for large scenes
- **Scalability**: Enables rendering of much larger Gaussian splat scenes by dynamically loading appropriate detail levels
- **Flexibility**: Provides fine-grained control over LOD distances and streaming behavior
- **Optimized Loading**: Only loads the data needed for the current view
Expand All @@ -143,6 +143,7 @@ As native Editor support for streaming LOD is added, the following improvements
- [GSplatComponent API](https://api.playcanvas.com/engine/classes/GSplatComponent.html)
- [Scene.gsplat API](https://api.playcanvas.com/engine/classes/Scene.html#gsplat)
- [SplatTransform CLI Tool](/user-manual/splat-transform)
- [Generating LOD Format](/user-manual/splat-transform#generating-lod-format)
- [Generating Streamed SOG](/user-manual/splat-transform#generating-lod-format)
- [Streamed SOG Format Specification](/user-manual/gaussian-splatting/formats/streamed-sog)
- [Splat Rendering Architecture](/user-manual/gaussian-splatting/rendering-architecture)
- [Custom Shaders](/user-manual/gaussian-splatting/building/custom-shaders)
16 changes: 8 additions & 8 deletions docs/user-manual/gaussian-splatting/building/performance.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Performance
description: "Performance tips for splat scenes: splat counts, fill rate, scene settings, LOD streaming budgets, and optimization strategies."
description: "Performance tips for splat scenes: splat counts, fill rate, scene settings, Streamed SOG budgets, and optimization strategies."
---

Rendering splats can be expensive on both the CPU and GPU. Here are some strategies to achieve good performance:
Expand All @@ -9,7 +9,7 @@ Rendering splats can be expensive on both the CPU and GPU. Here are some strateg

Be mindful of the number of Gaussians in your scene since every Gaussian is sorted on camera depth every frame. You can check the number contained within a particular GSplat asset by using the [SPLAT DATA Panel](/user-manual/supersplat/editor/data-panel/) in the [SuperSplat Editor](/user-manual/supersplat/editor/). Use SuperSplat to trim unwanted Gaussians from your PLY files.

For large scenes, consider using [LOD Streaming](/user-manual/gaussian-splatting/building/lod-streaming) which dynamically loads appropriate levels of detail based on camera distance. This significantly reduces the number of active Gaussians at any given time while maintaining visual quality where it matters most.
For large scenes, consider using [Streamed SOG](/user-manual/gaussian-splatting/building/lod-streaming) which dynamically loads appropriate levels of detail based on camera distance. This significantly reduces the number of active Gaussians at any given time while maintaining visual quality where it matters most.

## Fill Rate Considerations

Expand All @@ -30,13 +30,13 @@ Given the fragment-heavy nature of Gaussian splatting, these settings have a sig

Both settings help reduce the fragment processing load, which is the primary bottleneck in 3DGS rendering.

## LOD Streaming Configuration
## Streamed SOG Configuration

When using [LOD Streaming](/user-manual/gaussian-splatting/building/lod-streaming), you have several options to control quality and performance. The recommended approach is to use the **global splat budget** which automatically manages LOD selection across all GSplat assets in your scene.
When using [Streamed SOG](/user-manual/gaussian-splatting/building/lod-streaming), you have several options to control quality and performance. The recommended approach is to use the **global splat budget** which automatically manages LOD selection across all GSplat assets in your scene.

### Global Splat Budget

The global splat budget is the primary way to control rendering performance for LOD streaming. Set it via:
The global splat budget is the primary way to control rendering performance for Streamed SOG. Set it via:

```javascript
app.scene.gsplat.splatBudget = 4000000; // 4 million splats max
Expand All @@ -47,7 +47,7 @@ When a budget is set, the engine automatically adjusts LOD levels across all GSp
- **Budget = 0**: Disables budget enforcement, using only distance-based LOD selection
- **Budget > 0**: Enforces the specified maximum splat count across all GSplat assets

The budget system accounts for all GSplat assets in the scene, including both LOD-streaming assets (with multiple detail levels) and fixed assets (single detail level).
The budget system accounts for all GSplat assets in the scene, including both Streamed SOG assets (with multiple detail levels) and fixed assets (single detail level).

### LOD Distances

Expand Down Expand Up @@ -88,7 +88,7 @@ The approach has two steps:
```javascript
const gsplatSystem = app.systems.gsplat;

// `entity` has a gsplat component using a loaded LOD-streaming asset
// `entity` has a gsplat component using a loaded Streamed SOG asset
const gsplat = entity.gsplat;

// 1. Start with the lowest (coarsest) LOD only, for the fastest first frame
Expand All @@ -113,7 +113,7 @@ const onFrameReady = (camera, layer, ready, loadingCount) => {
gsplatSystem.on('frame:ready', onFrameReady);
```

This technique is demonstrated in the live [LOD Streaming example](/user-manual/gaussian-splatting/building/lod-streaming#live-examples).
This technique is demonstrated in the live [Streamed SOG example](/user-manual/gaussian-splatting/building/lod-streaming#live-examples).

### Recommended Configuration

Expand Down
27 changes: 18 additions & 9 deletions docs/user-manual/gaussian-splatting/formats/index.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
title: Splat File Formats
description: "Compare PLY and SOG splat formats for editing versus web delivery, size and quality trade-offs, and typical conversion workflows."
description: "Compare PLY, SOG and Streamed SOG splat formats for editing versus web delivery, size and quality trade-offs, and typical conversion workflows."
---

PlayCanvas supports two formats for 3D Gaussian Splat data:
PlayCanvas supports three formats for 3D Gaussian Splat data:

## [PLY Format](./ply.md) - Source & Interchange

Expand All @@ -21,17 +21,26 @@ Compressed format optimized for web delivery. 15-20× smaller than PLY with loss
- **File size**: Small (compressed)
- **Quality**: Visually optimized

## [Streamed SOG Format](./streamed-sog.md) - Large-Scene Streaming

SOG chunks organized into a spatial tree with multiple levels of detail. Viewers stream in only the chunks and detail levels needed for the current camera.

- **Use for**: Very large scenes (tens of millions of Gaussians), progressive loading
- **File size**: Small per chunk, loaded on demand
- **Quality**: Visually optimized, view-dependent detail

## Quick Comparison

| | PLY | SOG |
|---|---|---|
| **Size** | Large | Small (15-20× compression) |
| **Quality** | Lossless | Lossy |
| **Use** | Source/editing | Runtime/delivery |
| **Speed** | Slow loading | Fast loading |
| | PLY | SOG | Streamed SOG |
|---|---|---|---|
| **Size** | Large | Small (15-20× compression) | Small (SOG chunks, loaded on demand) |
| **Quality** | Lossless | Lossy | Lossy, view-dependent detail |
| **Use** | Source/editing | Runtime/delivery | Very large scenes |
| **Speed** | Slow loading | Fast loading | Progressive streaming |

## Workflow

1. Train and edit with **PLY**
2. Convert to **SOG** for production using [SplatTransform](/user-manual/splat-transform/)
3. Deploy SOG files for optimal performance
3. For very large scenes, convert to **Streamed SOG** instead
4. Deploy for optimal performance
Loading