Skip to content
Open
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
3 changes: 2 additions & 1 deletion .agents/skills/splat-studio-workflows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ the job LOG, no file).
(+ a `build-meta.json` recipe — read via `inspect(target:"lod_recipe")`; pre-feature
bundles return `not-found`); deleting that entry deletes the folder. Add
`decimateAlgorithm:"uniform"` to decimate every derived level at a flat rate instead of
the adaptive default.
the adaptive default. If a bake dies with "non-finite position", re-run with
`filterNaN:true` — the LOD writer aborts on the first bad gaussian.

**Environment-shell LOD (combine):** lighter levels first (`convert(decimate:"50%")` per level),
then `build_lod(mode:"combine", lodFiles:[...], lodEnvFlags:[...])` — env flag = always-visible
Expand Down
3 changes: 2 additions & 1 deletion .claude/skills/splat-studio-workflows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ the job LOG, no file).
(+ a `build-meta.json` recipe — read via `inspect(target:"lod_recipe")`; pre-feature
bundles return `not-found`); deleting that entry deletes the folder. Add
`decimateAlgorithm:"uniform"` to decimate every derived level at a flat rate instead of
the adaptive default.
the adaptive default. If a bake dies with "non-finite position", re-run with
`filterNaN:true` — the LOD writer aborts on the first bad gaussian.

**Environment-shell LOD (combine):** lighter levels first (`convert(decimate:"50%")` per level),
then `build_lod(mode:"combine", lodFiles:[...], lodEnvFlags:[...])` — env flag = always-visible
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ all in a dockable, Unity/Unreal-style tab editor you can rearrange and save per
workspace.

<!-- versions: the "Built with" line below is kept in sync by the weekly dependency-update routine -->
**Built with [PlayCanvas](https://github.com/playcanvas/engine) `2.21.3` · [@playcanvas/splat-transform](https://github.com/playcanvas/splat-transform) `3.2.0`**
**Built with [PlayCanvas](https://github.com/playcanvas/engine) `2.21.4` · [@playcanvas/splat-transform](https://github.com/playcanvas/splat-transform) `3.3.0`**

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
![Platform: Windows](https://img.shields.io/badge/platform-Windows-blue.svg)
Expand Down
9 changes: 5 additions & 4 deletions client/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -129,11 +129,11 @@ <h2 title="Export a splat to another format using splat-transform">Export</h2>
</select>
</label>
<div class="field-row" id="row-decimate">
<label class="field half" title="Reduce the gaussian count before writing (--decimate / --decimate-uniform). A number keeps that many gaussians, a percentage like 50% keeps that fraction. Leave empty to keep all">
<label class="field half" title="Reduce the gaussian count before writing (--decimate / --decimate-adaptive). A number keeps that many gaussians, a percentage like 50% keeps that fraction. Leave empty to keep all">
<span>Decimate to (count or %)</span>
<input type="text" id="convert-decimate" placeholder="e.g. 500000 or 50% — empty keeps all" />
</label>
<label class="field half" title="Adaptive (--decimate) allocates removal by local error — much better on mixed-scale scenes like skies. Uniform (--decimate-uniform) removes at a flat rate everywhere — lower memory, and better at depth on uniformly-sized gaussians: an even texture, a single object, snow. Adaptive needs a GPU on large scenes; Uniform runs on CPU at any size">
<label class="field half" title="Adaptive (--decimate-adaptive) allocates removal by local error — much better on mixed-scale scenes like skies. Uniform (--decimate) removes at a flat rate everywhere — lower memory, and better at depth on uniformly-sized gaussians: an even texture, a single object, snow. Adaptive needs a GPU on large scenes; Uniform runs on CPU at any size">
<span>Decimation</span>
<select id="convert-decimate-algo">
<option value="adaptive" selected>Adaptive</option>
Expand Down Expand Up @@ -261,12 +261,12 @@ <h2 title="Bake a streamed multi-LOD SOG (lod-meta.json + per-LOD chunk folders)
<span>LOD levels</span>
<input type="number" id="lod-levels" value="3" min="1" max="8" required />
</label>
<label class="field half" title="Each successive level keeps this percentage of the previous one (--decimate / --decimate-uniform). Adaptive needs a GPU on large scenes; Uniform never does">
<label class="field half" title="Each successive level keeps this percentage of the previous one (--decimate / --decimate-adaptive). Adaptive needs a GPU on large scenes; Uniform never does">
<span>Keep per level (%)</span>
<input type="number" id="lod-keep" value="50" min="5" max="95" required />
</label>
</div>
<label class="field" id="row-lod-decimate-algo" title="Adaptive (--decimate) allocates removal by local error — much better on mixed-scale scenes like skies. Uniform (--decimate-uniform) removes at a flat rate everywhere — lower memory, and better at depth on uniformly-sized gaussians: an even texture, a single object, snow. Applies to every decimated level. Adaptive needs a GPU on large scenes; Uniform runs on CPU at any size">
<label class="field" id="row-lod-decimate-algo" title="Adaptive (--decimate-adaptive) allocates removal by local error — much better on mixed-scale scenes like skies. Uniform (--decimate) removes at a flat rate everywhere — lower memory, and better at depth on uniformly-sized gaussians: an even texture, a single object, snow. Applies to every decimated level. Adaptive needs a GPU on large scenes; Uniform runs on CPU at any size">
<span>Decimation</span>
<select id="lod-decimate-algo">
<option value="adaptive" selected>Adaptive</option>
Expand All @@ -292,6 +292,7 @@ <h2 title="Bake a streamed multi-LOD SOG (lod-meta.json + per-LOD chunk folders)
<span>Device</span>
<select id="lod-device"><option value="auto" selected>Auto</option><option value="cpu">CPU</option></select>
</label>
<label class="check" title="Drop gaussians containing NaN/Infinity values before tagging levels (-N/--filter-nan). The LOD writer refuses a source with a non-finite gaussian and aborts the bake — tick this to drop them instead. Applies to every level, including combine rows"><input type="checkbox" id="lod-filter-nan" /> Filter NaN</label>
<label class="check" title="When the bake finishes, load the streamed LOD into the 3D viewport"><input type="checkbox" id="lod-autoload" checked /> Load result into viewport</label>
<button id="lod-run" class="primary" title="Run the streamed-LOD bake as a background job — the exact CLI command appears in the Jobs panel">Generate streamed LOD</button>
</section>
Expand Down
2 changes: 1 addition & 1 deletion client/src/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ export interface ConvertRequest {
maxWorkers?: number;
spzVersion?: number;
decimate?: string;
/** decimation strategy (--decimate vs --decimate-uniform); 'adaptive' or omitted = plain --decimate */
/** decimation strategy (--decimate-adaptive vs --decimate); 'adaptive' or omitted = --decimate-adaptive */
decimateAlgorithm?: 'adaptive' | 'uniform';
/** absolute dir for decimation spill files (--scratch-dir); blank = alongside the output */
scratchDir?: string;
Expand Down
1 change: 1 addition & 0 deletions client/src/lod-panel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ lodRun.onclick = () => {
lodChunkCount: Number($<HTMLInputElement>('lod-chunk-count').value),
lodChunkExtent: Number($<HTMLInputElement>('lod-chunk-extent').value),
scratchDir: $<HTMLInputElement>('scratch-dir').value.trim(),
filterNaN: $<HTMLInputElement>('lod-filter-nan').checked,
lodFiles,
lodEnvFlags
}
Expand Down
5 changes: 5 additions & 0 deletions docs/MCP_WORKFLOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,11 @@ mixed-scale content such as skies. The effective choice lands in `build-meta.jso
split into multiple blocks (roughly 2M+ gaussians) — adaptive with `device: "cpu"` there
fails as `gpu-required`.

Pass `filterNaN: true` when a source may contain non-finite gaussians. The LOD writer
aborts the whole bake on the first one (`has a non-finite position; run --filter-nan …`),
so this is the remedy — it applies to every level in both modes, and the choice lands in
`build-meta.json`.

### 4. Collision mesh for a game engine

Voxelize the splat into `*.collision.glb` (plus voxel debug files). **GPU required.**
Expand Down
10 changes: 8 additions & 2 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -221,9 +221,9 @@ They run in a fixed pipeline order (and don't apply to streamed-LOD bakes):
voxel size / opacity / min-contribution overrides.
- **Reorder (Morton / Z-order)** — spatially sort for better compression (`--morton-order`).
- **Decimate to (count or %)** — reduce the gaussian count to a number or percentage.
The paired **Decimation** dropdown picks the algorithm: **Adaptive** (`--decimate`,
The paired **Decimation** dropdown picks the algorithm: **Adaptive** (`--decimate-adaptive`,
default) allocates removal by local error — much better on mixed-scale scenes like
skies; **Uniform** (`--decimate-uniform`) removes at a flat rate everywhere — lower
skies; **Uniform** (`--decimate`) removes at a flat rate everywhere — lower
memory, and better at depth on uniformly-sized content (an even texture, a single
object, snow).
> **Adaptive needs a GPU on large scenes.** Once a scene is big enough to split into
Expand Down Expand Up @@ -261,6 +261,12 @@ folders that the engine streams by camera distance, for scenes too big to load a
5. Set the **Chunk size (K splats)** and **Chunk extent (m)**, pick a **Device**, then
**Generate streamed LOD**.

> **Filter NaN.** The LOD writer refuses a source containing a non-finite gaussian and
> aborts the bake (`LOD 0 gaussian N has a non-finite position; run --filter-nan …`).
> Tick **Filter NaN** to drop those gaussians instead (`-N`); it applies to every level,
> including Combine rows. Sources exported from Splat Studio are already clean — reach
> for this when a bake fails on third-party or scanner-produced input.

Every bake also writes a `build-meta.json` next to the bundle's `lod-meta.json` — the
recipe it was built from: the source file per level, the environment selection, the
effective settings, and per-level gaussian counts. Expand the bundle's row in the Files
Expand Down
Binary file modified docs/screenshots/group-region.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshots/linked-group.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshots/lod-autotune.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshots/lod-decimate.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshots/settings-panel.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/screenshots/settings-updates.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 3 additions & 2 deletions mcp-server/tools/convert.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ export function register(server) {
filterSphere: filterSphere.optional(),
filterNaN: z.boolean().optional().describe('Drop NaN/Inf gaussians (-N).'),
decimate: z.string().regex(/^\d+%?$/).optional().describe('Decimate to a count or percentage like "50%" (-F).'),
decimateAlgorithm: z.enum(['adaptive', 'uniform']).optional().describe('Decimation algorithm (default adaptive). "adaptive" (--decimate) allocates removal by local error — better on mixed-scale content such as skies; "uniform" (--decimate-uniform) removes at a flat rate — lower memory. Only used with decimate. "uniform" is the only algorithm that runs on CPU once a scene is large enough to split into multiple blocks; adaptive with device "cpu" there fails as gpu-required.'),
decimateAlgorithm: z.enum(['adaptive', 'uniform']).optional().describe('Decimation algorithm (default adaptive). "adaptive" (--decimate-adaptive) allocates removal by local error — better on mixed-scale content such as skies; "uniform" (--decimate) removes at a flat rate — lower memory. Only used with decimate. "uniform" is the only algorithm that runs on CPU once a scene is large enough to split into multiple blocks; adaptive with device "cpu" there fails as gpu-required.'),
scratchDir: z.string().optional().describe('Absolute path to an existing directory for decimation spill files (--scratch-dir); may be off-workspace (another volume). Only used with decimate; omitted/blank = alongside the output.'),
mortonOrder: z.boolean().optional().describe('Morton-reorder (-M).'),
verbose: z.boolean().optional(),
Expand All @@ -82,8 +82,9 @@ export function register(server) {
mode: z.enum(['decimate', 'combine']),
lodLevels: z.number().int().min(1).max(8).optional().describe('decimate: number of levels incl. LOD 0 (default 3).'),
lodKeepPercent: z.number().min(5).max(95).optional().describe('decimate: percent kept per level (default 50).'),
decimateAlgorithm: z.enum(['adaptive', 'uniform']).optional().describe('decimate: algorithm for every derived level — "adaptive" (--decimate, default) allocates removal by local error; "uniform" (--decimate-uniform) removes at a flat rate. Ignored in combine mode. "uniform" is the only algorithm that runs on CPU once a scene is large enough to split into multiple blocks; adaptive with device "cpu" there fails as gpu-required.'),
decimateAlgorithm: z.enum(['adaptive', 'uniform']).optional().describe('decimate: algorithm for every derived level — "adaptive" (--decimate-adaptive, default) allocates removal by local error; "uniform" (--decimate) removes at a flat rate. Ignored in combine mode. "uniform" is the only algorithm that runs on CPU once a scene is large enough to split into multiple blocks; adaptive with device "cpu" there fails as gpu-required.'),
scratchDir: z.string().optional().describe('decimate: absolute path to an existing directory for decimation spill files (--scratch-dir); may be off-workspace. Omitted/blank = alongside each temp output.'),
filterNaN: z.boolean().optional().describe('Drop NaN/Inf gaussians before tagging levels (-N). The LOD writer aborts the bake on a non-finite gaussian ("has a non-finite position; run --filter-nan..."), so set this to bake a source that may contain them. Applies to every level in both modes.'),
lodFiles: z.array(z.string()).optional().describe('combine: additional level files in detail order (each lighter than the last).'),
lodEnvFlags: z.array(z.boolean()).optional().describe('combine: per lodFiles entry, true = always-visible backdrop (LOD -1). Needs >=1 non-env level.'),
lodChunkCount: z.number().int().min(16).max(8192).optional().describe('approx gaussians per chunk in K (-C, default 512).'),
Expand Down
46 changes: 8 additions & 38 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
"dist:win": "npm run prepack:win && electron-builder --win"
},
"dependencies": {
"@playcanvas/splat-transform": "^3.2.0",
"@playcanvas/splat-transform": "^3.3.0",
"dockview-core": "^7.0.4",
"electron-updater": "^6.8.9",
"express": "^5.2.1",
Expand All @@ -48,7 +48,7 @@
"concurrently": "^10.0.4",
"electron": "^43.3.0",
"electron-builder": "^26.15.7",
"playcanvas": "^2.21.3",
"playcanvas": "^2.21.4",
"png-to-ico": "^3.0.1",
"pngjs": "^7.0.0",
"rcedit": "^5.0.2",
Expand Down
Loading
Loading