Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

refactor(splat): put both splat surfaces on one engine and retire the old library

nirholas14712cc00f16
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 270420f6e..5490c0f19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Point an AI agent at the Blender on your own machine**: A new MCP server drives the Blender you already have installed, with no GUI open and no add-on to install first. An assistant can now read a 3D file and tell you what is actually in it (objects, triangle counts, materials, bones, animations, real-world size), convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend in either direction, render a preview image of a bare asset file that arrives with no camera or lighting of its own, and run a Blender Python script to do the things no single tool covers, like halving a mesh's triangle count and exporting the result in one step. It also reaches back into three.ws: describe something in a sentence and the free text-to-3D lane generates it and opens it in Blender. Blender runs in the background, one process per request, so it works the same on a laptop, a server, or in CI. `[feature, sdk]`
- **Reference-image upload now tells you to paste a URL instead of failing with a network error**: When the image storage credentials are rejected, /forge used to hand the browser an upload address that the storage service refused. The refusal arrives without the header a browser needs to read it, so the page could only say "Network error during upload" and the reference image was lost. The upload endpoint now checks storage the same way the rest of the site does, so it says up front that direct upload is unavailable and points you at the paste-a-URL field, which keeps working through the outage. (`/forge`) `[fix]`
- **Shared avatar and agent links now show a real page to Google, not a loading spinner**: Search engines were shown a different version of every /avatars/... and /agents/... page than people were, and that version had nothing on it: the name and description were hidden in a fallback block that a crawler removes before reading, the rest was a spinner, and the last line of the page sent the crawler straight back to the URL it was already on. Tens of thousands of avatar and agent pages therefore looked identical to Google and were filed as duplicates instead of being listed. Crawlers now get the same content a visitor sees: the name, the description, the rendered card, the creator, the tags, the skills, the on-chain identity, and links onward into the gallery and the directory. A link to an avatar or agent that no longer exists now says so honestly instead of quietly bouncing to a listing page, an id that belongs to the other side of the platform redirects to where it actually lives, and a private agent is no longer readable by anything sending a crawler's name. Signed-in surfaces were also unblocked in robots.txt so their existing no-index instruction can finally be read and obeyed. `[fix, infra]`
+- **Studio Lab reads the same splat formats as the viewer**: The Lab's Gaussian-splat tools ran on a different rendering engine from the Splat Viewer, so the two disagreed about which files they would open: the viewer had just gained .spz and .sog and the Lab had not. Both now share one engine, so anything one of them opens the other opens too, the Lab works out a dropped file's format from its contents instead of its name, and its camera frames the scene it loaded. (`/forge-studio`) `[improvement]`
- **The AgenC task embed now loads even when it is inlined or served from a blob**: The <three-ws-agent> element that shows a 3D avatar reacting to an on-chain AgenC task resolves its mesh decoder relative to its own script address. A copy that had been pasted inline, bundled, or loaded from a blob: or data: URL has no address to resolve against, and the element failed to register before it drew anything. It now falls back to the decoder on three.ws in that case and keeps the same-origin path everywhere else, so the embed works wherever the snippet ends up. (`/agenc/embodied`) `[fix]`
- **The Blender tools now show you the render instead of describing it**: Asking an assistant to render a 3D model used to hand back a file path, which is useless if the assistant cannot open files on your disk. The rendered image now comes back with the answer, scaled to fit, while the full-resolution PNG still lands on disk. That turns a look at this model into one step, so an assistant can render, spot the problem, fix it and render again. Reading a file also reports its texture budget now: every image with its resolution and byte size, plus the total, which is usually what actually decides whether a model is small enough to ship, and it was previously reported as nothing more than a count. Two reliability fixes came out of real use: several requests at once now queue instead of all starting Blender at the same moment and exhausting the machine, and when Blender is installed but momentarily will not start you get a message saying exactly that, with the details, rather than being told to install software you already have. `[improvement, feature]`
- **The featured agent is one you can actually open**: The agent we spotlight is picked automatically from real activity, but the pick only checked whether an agent was public, not whether its owner had published it. That let a brand new starter agent, the draft every account is given on signup, take the spot, and every panel that tried to read it came back empty with a live feed error. The pick now requires a published agent, so the spotlight lands on one that every part of the site can open. `[fix]`
diff --git a/data/changelog.json b/data/changelog.json
index 1cf7b0b2b..b035f25db 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -26939,6 +26939,15 @@
"feature"
],
"link": "/splat"
+ },
+ {
+ "date": "2026-09-07",
+ "title": "Studio Lab reads the same splat formats as the viewer",
+ "summary": "The Lab's Gaussian-splat tools ran on a different rendering engine from the Splat Viewer, so the two disagreed about which files they would open: the viewer had just gained .spz and .sog and the Lab had not. Both now share one engine, so anything one of them opens the other opens too, the Lab works out a dropped file's format from its contents instead of its name, and its camera frames the scene it loaded.",
+ "tags": [
+ "improvement"
+ ],
+ "link": "/forge-studio"
}
]
}
diff --git a/docs/oss-adoption-2026-09.md b/docs/oss-adoption-2026-09.md
index 46248472e..3151b6cc7 100644
--- a/docs/oss-adoption-2026-09.md
+++ b/docs/oss-adoption-2026-09.md
@@ -72,8 +72,10 @@ Verified in a real browser against `butterfly.spz` (177,132 splats) and both
procedural samples: correct framing, correct orientation, live splat counts in
the HUD, no console errors.
-`@mkkellogg/gaussian-splats-3d` stays a dependency: the Forge Studio Lab still
-uses it, and moving that surface is separate work.
+Both splat surfaces now share one engine, [src/splat-stage.js](../src/splat-stage.js):
+the viewer and the Forge Studio Lab need the same scene and the same three
+gotchas above, and having them in one module is what stops one copy from
+rotting. `@mkkellogg/gaussian-splats-3d` was removed from the dependency tree.
### 2. BiRefNet as an optional background-removal model
diff --git a/docs/splat.md b/docs/splat.md
index a05d2cbb2..292f4ed46 100644
--- a/docs/splat.md
+++ b/docs/splat.md
@@ -10,7 +10,7 @@ Mesh avatars (GLB) are lightweight, riggable, and universal, and that is what mo
## How it works
-The viewer (`src/splat-viewer.js`) is entirely client-side. It runs on [Spark](https://github.com/sparkjsdev/spark) (`@sparkjsdev/spark`, MIT, by World Labs), lazy-loaded on first render so the page shell paints instantly.
+The viewer (`src/splat-viewer.js`) is entirely client-side. Rendering lives in `src/splat-stage.js`, a shared module on top of [Spark](https://github.com/sparkjsdev/spark) (`@sparkjsdev/spark`, MIT, by World Labs), lazy-loaded on first render so the page shell paints instantly. The Forge Studio Lab's splat tools render through the same module, so both surfaces read the same formats and behave the same way.
Spark renders splats as ordinary objects inside a normal three.js scene rather than inside a viewer of its own, which is what makes the rest of this page's behaviour possible:
diff --git a/package-lock.json b/package-lock.json
index 62b32929b..737f6b920 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -112,7 +112,6 @@
"@metaplex-foundation/umi": "^1.5.1",
"@metaplex-foundation/umi-bundle-defaults": "^1.5.1",
"@meteora-ag/dynamic-bonding-curve-sdk": "^1.5.10",
- "@mkkellogg/gaussian-splats-3d": "^0.4.7",
"@modelcontextprotocol/sdk": "^1.29.0",
"@neondatabase/serverless": "^0.10.1",
"@neynar/nodejs-sdk": "^3.176.0",
@@ -10068,13 +10067,6 @@
"version": "0.15.5",
"license": "MIT"
},
- "node_modules/@mkkellogg/gaussian-splats-3d": {
- "version": "0.4.7",
- "license": "MIT",
- "peerDependencies": {
- "three": ">=0.160.0"
- }
- },
"node_modules/@modelcontextprotocol/ext-apps": {
"version": "1.7.4",
"dev": true,
diff --git a/package.json b/package.json
index dbc981272..b89d44b21 100644
--- a/package.json
+++ b/package.json
@@ -496,7 +496,6 @@
"@metaplex-foundation/umi": "^1.5.1",
"@metaplex-foundation/umi-bundle-defaults": "^1.5.1",
"@meteora-ag/dynamic-bonding-curve-sdk": "^1.5.10",
- "@mkkellogg/gaussian-splats-3d": "^0.4.7",
"@modelcontextprotocol/sdk": "^1.29.0",
"@neondatabase/serverless": "^0.10.1",
"@neynar/nodejs-sdk": "^3.176.0",
diff --git a/pages/forge-studio.html b/pages/forge-studio.html
index c294d6519..9061dfb5c 100644
--- a/pages/forge-studio.html
+++ b/pages/forge-studio.html
@@ -4171,7 +4171,7 @@
Mesh tools export a real binary <strong>GLB</strong>; the Gaussian-splat viewer
renders the photoreal radiance-field format. Powered by
<a href="https://threejs.org" rel="noopener" target="_blank">three.js</a> and
- <a href="https://github.com/mkkellogg/GaussianSplats3D" rel="noopener" target="_blank">GaussianSplats3D</a>.
+ <a href="https://github.com/sparkjsdev/spark" rel="noopener" target="_blank">Spark</a>.
</p>
</div>
</div>
diff --git a/public/changelog.json b/public/changelog.json
index 08c2d1900..6125254a4 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-07T21:48:14.180Z",
+ "generated_at": "2026-09-07T21:49:42.100Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -187,6 +187,16 @@
"infra"
]
},
+ {
+ "date": "2026-09-07",
+ "type": "update",
+ "title": "Studio Lab reads the same splat formats as the viewer",
+ "summary": "The Lab's Gaussian-splat tools ran on a different rendering engine from the Splat Viewer, so the two disagreed about which files they would open: the viewer had just gained .spz and .sog and the Lab had not. Both now share one engine, so anything one of them opens the other opens too, the Lab works out a dropped file's format from its contents instead of its name, and its camera frames the scene it loaded.",
+ "link": "/forge-studio",
+ "tags": [
+ "improvement"
+ ]
+ },
{
"date": "2026-09-07",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index c32926692..83432f855 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -142,6 +142,14 @@
<category>fix</category>
<description>Search engines were shown a different version of every /avatars/... and /agents/... page than people were, and that version had nothing on it: the name and description were hidden in a fallback block that a crawler removes before reading, the rest was a spinner, and the last line of the page sent the crawler straight back to the URL it was already on. Tens of thousands of avatar and agent pages therefore looked identical to Google and were filed as duplicates instead of being listed. Crawlers now get the same content a visitor sees: the name, the description, the rendered card, the creator, the tags, the skills, the on-chain identity, and links onward into the gallery and the directory. A link to an avatar or agent that no longer exists now says so honestly instead of quietly bouncing to a listing page, an id that belongs to the other side of the platform redirects to where it actually lives, and a private agent is no longer readable by anything sending a crawler's name. Signed-in surfaces were also unblocked in robots.txt so their existing no-index instruction can finally be read and obeyed.</description>
</item>
+ <item>
+ <title>Studio Lab reads the same splat formats as the viewer</title>
+ <link>https://three.ws/forge-studio</link>
+ <guid isPermaLink="false">2026-09-07:Studio Lab reads the same splat formats as the viewer</guid>
+ <pubDate>Mon, 07 Sep 2026 12:00:00 GMT</pubDate>
+ <category>improvement</category>
+ <description>The Lab's Gaussian-splat tools ran on a different rendering engine from the Splat Viewer, so the two disagreed about which files they would open: the viewer had just gained .spz and .sog and the Lab had not. Both now share one engine, so anything one of them opens the other opens too, the Lab works out a dropped file's format from its contents instead of its name, and its camera frames the scene it loaded.</description>
+ </item>
<item>
<title>The AgenC task embed now loads even when it is inlined or served from a blob</title>
<link>https://three.ws/agenc/embodied</link>
diff --git a/public/locales/en.json b/public/locales/en.json
index fd1f2c7d4..0e1121253 100644
--- a/public/locales/en.json
+++ b/public/locales/en.json
@@ -8018,7 +8018,7 @@
"embed_this_model_on_any_webs_title": "Embed this model on any website",
"engine": "Engine",
"enter_a_prompt_to_generate": "Enter a prompt to generate",
- "every_lab_tool_runs_entirely_in_your": "Every Lab tool runs entirely in your browser — no API key, no upload, no cost. Mesh tools export a real binary <strong>GLB</strong>; the Gaussian-splat viewer renders the photoreal radiance-field format. Powered by <a href=\"https://threejs.org\" rel=\"noopener\" target=\"_blank\">three.js</a> and <a href=\"https://github.com/mkkellogg/GaussianSplats3D\" rel=\"noopener\" target=\"_blank\">GaussianSplats3D</a>.",
+ "every_lab_tool_runs_entirely_in_your": "Every Lab tool runs entirely in your browser — no API key, no upload, no cost. Mesh tools export a real binary <strong>GLB</strong>; the Gaussian-splat viewer renders the photoreal radiance-field format. Powered by <a href=\"https://threejs.org\" rel=\"noopener\" target=\"_blank\">three.js</a> and <a href=\"https://github.com/sparkjsdev/spark\" rel=\"noopener\" target=\"_blank\">Spark</a>.",
"fill_the_box_with_a_random_v_arialabel": "Fill the box with a random vivid prompt",
"finalizing_glb": "Finalizing GLB",
"free_no_api_key_your_own_key": "<span class=\"el-item\"><span class=\"el-free\">FREE</span> no API key</span> <span class=\"el-item\" ><svg class=\"el-key\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><circle cx=\"8\" cy=\"15\" r=\"4\"></circle><path d=\"M10.85 12.15 19 4\"></path><path d=\"m18 5 2 2\"></path><path d=\"m15 8 2 2\"></path></svg> your own key</span> <span class=\"el-item\"><span class=\"el-dot el-dot-busy\"></span> busy</span> <span class=\"el-item\"><span class=\"el-dot el-dot-down\"></span> unavailable</span>",
diff --git a/src/forge-studio/lab/lab.js b/src/forge-studio/lab/lab.js
index 0a7a94dda..3935459ec 100644
--- a/src/forge-studio/lab/lab.js
+++ b/src/forge-studio/lab/lab.js
@@ -9,9 +9,10 @@
* - Mesh → Gaussian-splat conversion (mesh-to-splat.js): our own splat
* generation lane — resamples any mesh (a Lab model or an uploaded GLB) into
* a Gaussian-splat radiance field, downloadable as a real .splat file.
- * - A Gaussian-splat / radiance-field viewer from the npm package
- * `@mkkellogg/gaussian-splats-3d` — a 3D representation the platform didn't
- * have. Loads a .splat/.ply (or a generated sample) into its own renderer.
+ * - A Gaussian-splat / radiance-field viewer on the shared splat stage
+ * (`src/splat-stage.js`, Spark), a 3D representation the platform didn't
+ * have. Loads a .ply / .spz / .splat / .ksplat / .sog, or a generated
+ * sample, into a real three.js scene.
*
* Nothing here calls a paid API or the network; every model is computed in the
* browser, so it is fully self-contained and testable.
@@ -23,6 +24,7 @@ import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { getMeshoptDecoder } from '../../viewer/internal.js';
import { GENERATORS } from './generators.js';
import { meshToSplatBuffer } from './mesh-to-splat.js';
+import { loadSpark, detectSplatFormat, mountSplatScene, SPLAT_EXTENSIONS, SPLAT_EXTENSIONS_LABEL } from '../../splat-stage.js';
import { launchTalk } from '../talk-launch.js';
let _inited = false;
@@ -32,7 +34,7 @@ let _lastGlbBlob = null; // last mesh GLB blob (for "Bring it alive")
let _lastLabel = '';
let _lastSplatUrl = null;
let _lastObject = null; // live Object3D from the last mesh gen (for splat conversion)
-let _splat = null; // lazy { viewer, url }
+let _splat = null; // handle from mountSplatScene
const MESHSPLAT_TOOL = {
id: 'meshsplat',
@@ -56,10 +58,10 @@ const MESHSPLAT_TOOL = {
const SPLAT_TOOL = {
id: 'splat',
label: 'Splat Viewer',
- blurb: 'View a Gaussian-splat / radiance-field capture (.splat / .ply) — the photoreal 3D format. Drop a file, or render the built-in sample.',
+ blurb: 'View a Gaussian-splat / radiance-field capture (.ply, .spz, .splat, .ksplat, .sog) - the photoreal 3D format. Drop a file, or render the built-in sample.',
kind: 'splat',
controls: [
- { key: 'file', label: 'Splat file (.splat / .ply / .ksplat)', type: 'splatfile', default: null },
+ { key: 'file', label: 'Splat file (.ply, .spz, .splat, .ksplat, .sog)', type: 'splatfile', default: null },
],
};
@@ -176,7 +178,7 @@ function renderControls() {
wrap.appendChild(labelRow);
wrap.appendChild(input);
} else if (f.type === 'image' || f.type === 'splatfile' || f.type === 'glbfile') {
- const accept = f.type === 'image' ? 'image/*' : f.type === 'glbfile' ? '.glb,.gltf,model/gltf-binary' : '.splat,.ply,.ksplat';
+ const accept = f.type === 'image' ? 'image/*' : f.type === 'glbfile' ? '.glb,.gltf,model/gltf-binary' : SPLAT_EXTENSIONS.join(',');
input = el('input', { type: 'file', id: `lab-field-${f.key}`, accept });
const hintText = f.type === 'image' ? 'optional — uses a sample if empty' : f.type === 'glbfile' ? 'pick a .glb / .gltf' : 'optional — renders a sample if empty';
const hint = el('span', { class: 'lab-field-out', text: hintText });
@@ -352,7 +354,7 @@ async function convertToSplats() {
});
if (params.source === 'upload') disposeObject(source); // free the uploaded scene
const colorNote = textured ? ' · textured' : '';
- await renderSplatBuffer(buffer, `${count.toLocaleString()} splats from ${sourceLabel}${colorNote}`);
+ await renderSplatBuffer(buffer, `${count.toLocaleString()} splats from ${sourceLabel}${colorNote}`, undefined, false);
// .splat download
if (_lastSplatUrl) URL.revokeObjectURL(_lastSplatUrl);
_lastSplatUrl = URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' }));
@@ -394,54 +396,47 @@ function sampleSplatBuffer(count = 4000) {
async function renderSplatFile() {
const fileField = $('#lab-field-file');
const uploaded = fileField?._fileData || null;
- let buffer, format, label;
- const GS = await loadSplatLib();
+ let buffer, format, label, flip;
+ const SPARK = await loadSpark();
if (uploaded) {
buffer = uploaded.buffer;
- format =
- uploaded.name.endsWith('.ply') ? GS.SceneFormat.Ply :
- uploaded.name.endsWith('.ksplat') ? GS.SceneFormat.KSplat :
- GS.SceneFormat.Splat;
+ // Read the container from the bytes, not the name: an upload called
+ // "scene" or "capture.bin" is still a capture we can decode.
+ format = detectSplatFormat(uploaded.name, buffer, SPARK);
label = `Loaded ${uploaded.name}`;
+ flip = true;
} else {
buffer = sampleSplatBuffer();
- format = GS.SceneFormat.Splat;
+ format = SPARK.SplatFileType.SPLAT;
label = 'Sample radiance field · 4,000 splats';
+ flip = false; // authored Y-up, unlike a real capture
}
- await renderSplatBuffer(buffer, label, format);
+ await renderSplatBuffer(buffer, label, format, flip);
// Allow re-downloading the loaded/sample splat.
if (_lastSplatUrl) URL.revokeObjectURL(_lastSplatUrl);
_lastSplatUrl = URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' }));
setDownload(_lastSplatUrl, uploaded ? uploaded.name : 'sample.splat', 'Download .splat');
}
-let _GS = null;
-async function loadSplatLib() {
- if (!_GS) _GS = await import('@mkkellogg/gaussian-splats-3d');
- return _GS;
-}
-
-async function renderSplatBuffer(buffer, label, format) {
+async function renderSplatBuffer(buffer, label, format, flip = false) {
status('Loading splat engine…');
- const GS = await loadSplatLib();
+ const SPARK = await loadSpark();
+ // A buffer we generated ourselves carries no header for Spark to sniff, so
+ // name the container rather than letting detection guess at raw floats.
+ if (!format) format = SPARK.SplatFileType.SPLAT;
await teardownSplat();
- const host = $('#lab-splat');
- host.innerHTML = '';
- const url = URL.createObjectURL(new Blob([buffer]));
- const viewer = new GS.Viewer({
- rootElement: host,
- sharedMemoryForWorkers: false,
- dynamicScene: false,
- useBuiltInControls: true,
- gpuAcceleratedSort: false,
- cameraUp: [0, 1, 0],
- initialCameraPosition: [0, 0, 4],
- initialCameraLookAt: [0, 0, 0],
- });
- _splat = { viewer, url };
status('Rendering splats…');
- await viewer.addSplatScene(url, { format: format ?? GS.SceneFormat.Splat, showLoadingUI: false, progressiveLoad: false });
- viewer.start();
+ try {
+ _splat = await mountSplatScene($('#lab-splat'), buffer, {
+ fileType: format,
+ flip,
+ onSorting: (count) => status(`Sorting ${count.toLocaleString()} splats…`),
+ onContextLost: () => { _splat = null; status('The 3D context was lost. Render again to restore it.', 'err'); },
+ });
+ } catch (err) {
+ console.error('[lab] splat decode failed', err);
+ throw new Error(`That file isn't a splat scene this build can read. Expected a ${SPLAT_EXTENSIONS_LABEL}.`);
+ }
status(label, 'ok');
}
@@ -449,17 +444,7 @@ async function teardownSplat() {
if (!_splat) return;
const s = _splat;
_splat = null;
- try {
- s.viewer.stop?.();
- // dispose() cleans up the renderer + its canvas first, then tries to
- // document.body.removeChild(rootElement) — which throws because our root
- // (#lab-splat) is nested, not a direct child of body. Everything we care
- // about is already torn down by then, so we await and swallow that one.
- await s.viewer.dispose?.();
- } catch { /* harmless nested-root removeChild from the splat lib */ }
- if (s.url) URL.revokeObjectURL(s.url);
- const host = document.getElementById('lab-splat');
- if (host) host.innerHTML = '';
+ s.dispose();
}
// ── Misc ──────────────────────────────────────────────────────────────────────
diff --git a/src/splat-stage.js b/src/splat-stage.js
new file mode 100644
index 000000000..1c6feb734
--- /dev/null
+++ b/src/splat-stage.js
@@ -0,0 +1,209 @@
+// splat-stage: mount a Gaussian-splat scene into a DOM element.
+//
+// Shared by the Splat Viewer (`src/splat-viewer.js`) and the Forge Studio Lab
+// (`src/forge-studio/lab/lab.js`), which need exactly the same thing: hand it an
+// element and a buffer of splat bytes, get back an orbiting scene and a handle
+// that tears itself down completely.
+//
+// It runs on Spark (`@sparkjsdev/spark`, MIT, World Labs). Spark renders splats
+// as ordinary objects inside a normal three.js scene, which is what lets us
+// frame the camera on the actual scene and, later, put splats and meshes in one
+// stage. It also reads the compressed containers real captures ship as: .spz is
+// about a tenth of the equivalent PLY and .sog about a fifteenth to a twentieth.
+//
+// Three behaviours here look like a broken page if you skip them, which is the
+// reason this module exists instead of the same code twice:
+//
+// 1. The canvas must be OPAQUE. Spark accumulates colour with premultiplied
+// alpha and leaves destination alpha at zero, so on a transparent canvas
+// the browser composites a fully rendered scene away to nothing.
+// 2. The camera must be framed in WORLD space. A loaded capture wears a
+// 180-degree flip (3DGS files are authored Y-down), so framing the mesh's
+// own bounding box aims at the mirror image of where the scene is.
+// 3. The first frame must be WAITED for. Spark sorts splats on a worker and
+// paints once that lands, up to about a second on a weak GPU. Going live
+// before then shows an empty stage.
+
+import { Box3, Color, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const FOV = 55;
+const FIRST_PAINT_TIMEOUT_MS = 8000;
+const DEFAULT_BACKGROUND = 0x0f0e16;
+
+/** Every container Spark can decode, in the order a file picker should list them. */
+export const SPLAT_EXTENSIONS = ['.ply', '.spz', '.splat', '.ksplat', '.sog'];
+
+/** Human-readable form of the above, for error copy and page text. */
+export const SPLAT_EXTENSIONS_LABEL = '.ply, .spz, .splat, .ksplat, or .sog';
+
+let _spark = null;
+
+/** Load Spark once, lazily: it is far too large to sit on a page's critical path. */
+export async function loadSpark() {
+ if (!_spark) _spark = await import('@sparkjsdev/spark');
+ return _spark;
+}
+
+// Spark sniffs the container from its magic bytes, which is the reliable answer
+// and the only one available for a URL that ends in a query string or carries no
+// extension at all. Two formats it cannot sniff fall back to the name: `.splat`
+// is a raw 32-byte-per-splat array with no header, and a bundled `.sog` is a zip
+// whose signature it does not claim.
+export function detectSplatFormat(name, bytes, SPARK) {
+ const sniffed = SPARK.getSplatFileType(new Uint8Array(bytes.slice(0, 1024)));
+ if (sniffed) return sniffed;
+ const n = (name || '').toLowerCase();
+ if (n.endsWith('.sog')) return SPARK.SplatFileType.PCSOGSZIP;
+ if (n.endsWith('meta.json')) return SPARK.SplatFileType.PCSOGS;
+ if (n.endsWith('.ksplat')) return SPARK.SplatFileType.KSPLAT;
+ if (n.endsWith('.spz')) return SPARK.SplatFileType.SPZ;
+ if (n.endsWith('.ply')) return SPARK.SplatFileType.PLY;
+ return SPARK.SplatFileType.SPLAT;
+}
+
+// Fit the camera to whatever came out of the file. `centers_only` ignores the
+// per-splat radii, so one stray oversized splat cannot blow the frame out to
+// nothing, which is the usual failure of naive splat framing.
+function frameCamera(camera, controls, mesh) {
+ let box;
+ try { box = mesh.getBoundingBox(true); } catch { box = null; }
+ if (!box || box.isEmpty()) box = new Box3(new Vector3(-1, -1, -1), new Vector3(1, 1, 1));
+ mesh.updateMatrixWorld(true);
+ box.applyMatrix4(mesh.matrixWorld);
+ const center = box.getCenter(new Vector3());
+ const radius = Math.max(box.getSize(new Vector3()).length() / 2, 0.001);
+ const distance = (radius / Math.sin((FOV * Math.PI) / 360)) * 1.15;
+ camera.near = Math.max(distance / 1000, 0.001);
+ camera.far = distance * 100;
+ camera.updateProjectionMatrix();
+ camera.position.set(center.x, center.y, center.z + distance);
+ controls.target.copy(center);
+ controls.update();
+ return { center: center.clone(), position: camera.position.clone() };
+}
+
+/**
+ * Mount `buffer` into `host` and resolve once the scene is actually on screen.
+ *
+ * @param {HTMLElement} host element to fill; its contents are replaced
+ * @param {ArrayBuffer} buffer splat bytes in any container Spark reads
+ * @param {object} [options]
+ * @param {*} [options.fileType] Spark SplatFileType; sniffed if absent
+ * @param {string} [options.fileName] name, used only to disambiguate the format
+ * @param {boolean} [options.flip=true] apply the 3DGS Y-down convention flip.
+ * Pass false for splats authored Y-up,
+ * such as procedurally generated samples.
+ * @param {number} [options.background] clear colour behind the scene
+ * @param {Function} [options.onSorting] called once decoding is done and the
+ * first sort is pending, with the splat count
+ * @param {Function} [options.onContextLost] called if the browser drops the GL context
+ * @returns {Promise<{count:number, recenter:Function, dispose:Function}>}
+ * @throws if the bytes are not a splat scene this build can decode
+ */
+export async function mountSplatScene(host, buffer, {
+ fileType,
+ fileName,
+ flip = true,
+ background = DEFAULT_BACKGROUND,
+ onSorting,
+ onContextLost,
+} = {}) {
+ const SPARK = await loadSpark();
+ host.innerHTML = '';
+
+ // Antialias off on Spark's own advice: MSAA does nothing for splats and costs
+ // real frame time.
+ const renderer = new WebGLRenderer({ antialias: false });
+ renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+ const width = () => host.clientWidth || 640;
+ const height = () => host.clientHeight || 420;
+ renderer.setSize(width(), height());
+ host.appendChild(renderer.domElement);
+
+ const scene = new Scene();
+ scene.background = new Color(background);
+ const camera = new PerspectiveCamera(FOV, width() / height(), 0.01, 1000);
+ const controls = new OrbitControls(camera, renderer.domElement);
+ controls.enableDamping = true;
+
+ let onFirstPaint;
+ const firstPaint = new Promise((resolve) => { onFirstPaint = resolve; });
+ const spark = new SPARK.SparkRenderer({ renderer, onDirty: () => onFirstPaint() });
+ scene.add(spark);
+
+ let frame = 0;
+ let mesh = null;
+ let disposed = false;
+ const resize = () => {
+ renderer.setSize(width(), height());
+ camera.aspect = width() / height();
+ camera.updateProjectionMatrix();
+ };
+
+ function dispose() {
+ if (disposed) return;
+ disposed = true;
+ if (frame) cancelAnimationFrame(frame);
+ window.removeEventListener('resize', resize);
+ // Order matters: drop the splat data, then the Spark renderer holding GPU
+ // buffers for it, then the controls' listeners, then the context itself.
+ try { mesh?.dispose?.(); } catch { /* already torn down */ }
+ try { spark.dispose?.(); } catch { /* already torn down */ }
+ try { controls.dispose?.(); } catch { /* already torn down */ }
+ // renderer.dispose() frees the three.js caches and leaves the WebGL context
+ // alive. Without an explicit release every scene swap leaks a live context,
+ // and a browser grants a page only a handful before it starts reclaiming
+ // the oldest out from under a running scene.
+ try {
+ renderer.forceContextLoss?.();
+ renderer.dispose?.();
+ } catch { /* context already lost */ }
+ host.innerHTML = '';
+ }
+
+ try {
+ mesh = new SPARK.SplatMesh({ fileBytes: buffer, fileType, fileName });
+ if (flip) mesh.quaternion.set(1, 0, 0, 0);
+ await mesh.initialized;
+ } catch (err) {
+ dispose();
+ throw err;
+ }
+ if (disposed) throw new Error('splat stage was disposed while decoding');
+
+ scene.add(mesh);
+ const home = frameCamera(camera, controls, mesh);
+ window.addEventListener('resize', resize);
+ resize();
+
+ const tick = () => {
+ if (disposed) return;
+ frame = requestAnimationFrame(tick);
+ controls.update();
+ renderer.render(scene, camera);
+ };
+ frame = requestAnimationFrame(tick);
+
+ renderer.domElement.addEventListener('webglcontextlost', (e) => {
+ e.preventDefault();
+ if (disposed) return;
+ dispose();
+ onContextLost?.();
+ }, { once: true });
+
+ const count = mesh.packedSplats?.numSplats ?? 0;
+ onSorting?.(count);
+ await Promise.race([firstPaint, new Promise((r) => setTimeout(r, FIRST_PAINT_TIMEOUT_MS))]);
+
+ return {
+ count,
+ dispose,
+ recenter() {
+ if (disposed) return;
+ camera.position.copy(home.position);
+ controls.target.copy(home.center);
+ controls.update();
+ },
+ };
+}
diff --git a/src/splat-viewer.js b/src/splat-viewer.js
index 38085612a..8803cca7c 100644
--- a/src/splat-viewer.js
+++ b/src/splat-viewer.js
@@ -1,67 +1,35 @@
-// Splat Viewer — render Gaussian-splat / radiance-field avatars in the browser.
-//
-// Runs on Spark (`@sparkjsdev/spark`, MIT, World Labs), which renders splats as
-// ordinary objects inside a normal three.js scene rather than inside a private
-// viewer of its own. Two things follow from that, and both are the reason this
-// page moved off `@mkkellogg/gaussian-splats-3d`:
-//
-// 1. It reads the formats real captures actually ship. A scene that is a 1 GB
-// PLY is roughly a 42 MB SOG or a 100 MB SPZ, and those are the files
-// people are handed today. Extension-sniffing is also gone: the format is
-// read from the bytes, so a URL with no extension (or the wrong one) still
-// decodes.
-// 2. The camera can frame the scene it actually loaded. The old viewer parked
-// the camera at a fixed z=3.2 for every file, which is correct for a scene
-// authored at unit scale and nothing else.
+// Splat Viewer - render Gaussian-splat / radiance-field avatars in the browser.
//
// Loads a .ply (plain or compressed), .spz, .splat, .ksplat, or .sog from a URL
// (?src=), a file upload, or a procedurally generated sample. Every state is
-// designed: idle, loading, error, and the live HUD.
+// designed: idle, fetching, decoding, sorting, error, and the live HUD.
+//
+// The renderer itself lives in `src/splat-stage.js`, shared with the Forge
+// Studio Lab, which needs the same scene and the same three non-obvious Spark
+// behaviours. This file is the page: fetching, format plumbing, and the states.
-import { Box3, Color, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from 'three';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { Color } from 'three';
+import { loadSpark, detectSplatFormat, mountSplatScene, SPLAT_EXTENSIONS_LABEL } from './splat-stage.js';
const $ = (s, r = document) => r.querySelector(s);
const STAGE = () => $('#sp-stage');
const HOST = () => $('#sp-host');
-// ── Splat lib (lazy) ─────────────────────────────────────────────────────────
-let _spark = null;
-async function loadSplatLib() {
- if (!_spark) _spark = await import('@sparkjsdev/spark');
- return _spark;
-}
-
-// ── Active scene lifecycle ───────────────────────────────────────────────────
-let _stage = null; // { renderer, scene, camera, controls, spark, mesh, frame }
+// -- Active scene lifecycle ---------------------------------------------------
+let _scene = null; // handle from mountSplatScene
+let _token = 0; // guards a slow load finishing after a newer one started
let _downloadUrl = null; // blob URL backing the download button
-let _lastRender = null; // { buffer, fileType, label, flip }, for recenter / re-render
+let _lastRender = null; // { buffer, fileType, fileName, label, flip }, for recenter
function teardown() {
- const s = _stage;
- if (!s) return;
- _stage = null;
- if (s.frame) cancelAnimationFrame(s.frame);
- // Order matters: drop the splat data, then the Spark renderer that holds GPU
- // buffers for it, then the controls' listeners, then the context itself.
- try { s.mesh?.dispose?.(); } catch { /* already torn down */ }
- try { s.spark?.dispose?.(); } catch { /* already torn down */ }
- try { s.controls?.dispose?.(); } catch { /* already torn down */ }
- // renderer.dispose() frees the three.js caches and leaves the WebGL context
- // alive. Without an explicit release, every scene swap leaks a live context,
- // and a browser only grants a page a handful before it starts reclaiming the
- // oldest ones out from under a running scene.
- try {
- s.renderer?.forceContextLoss?.();
- s.renderer?.dispose?.();
- } catch { /* context already lost */ }
- s.resize && window.removeEventListener('resize', s.resize);
- const host = HOST();
- if (host) host.innerHTML = '';
+ _token++;
+ if (!_scene) return;
+ _scene.dispose();
+ _scene = null;
}
-// ── State overlays ───────────────────────────────────────────────────────────
+// -- State overlays -----------------------------------------------------------
function showOnly(id) {
for (const k of ['sp-idle', 'sp-loading', 'sp-error']) {
const node = $(`#${k}`);
@@ -112,166 +80,49 @@ function setDownload(url, filename) {
btn.hidden = false;
}
-// ── Format detection ─────────────────────────────────────────────────────────
-// Spark sniffs the container from its magic bytes, which is the reliable answer
-// and the only one available for a URL that ends in a query string or no
-// extension at all. Two formats it cannot sniff fall back to the name: `.splat`
-// is a raw 32-byte-per-splat array with no header, and a bundled `.sog` is a zip
-// whose signature it does not claim.
-function formatFor(name, bytes, SPARK) {
- const sniffed = SPARK.getSplatFileType(new Uint8Array(bytes.slice(0, 1024)));
- if (sniffed) return sniffed;
- const n = (name || '').toLowerCase();
- if (n.endsWith('.sog')) return SPARK.SplatFileType.PCSOGSZIP;
- if (n.endsWith('meta.json')) return SPARK.SplatFileType.PCSOGS;
- if (n.endsWith('.ksplat')) return SPARK.SplatFileType.KSPLAT;
- if (n.endsWith('.spz')) return SPARK.SplatFileType.SPZ;
- if (n.endsWith('.ply')) return SPARK.SplatFileType.PLY;
- return SPARK.SplatFileType.SPLAT;
-}
-
-const ACCEPTED = '.ply, .spz, .splat, .ksplat, or .sog';
-
-// ── Core render ──────────────────────────────────────────────────────────────
-const FOV = 55;
-const FIRST_PAINT_TIMEOUT_MS = 8000;
-
-// Fit the camera to whatever came out of the file. `centers_only` ignores the
-// per-splat radii, so one stray oversized splat cannot blow the frame out to
-// nothing, which is the usual failure of naive splat framing.
-//
-// getBoundingBox reports the mesh's OWN coordinates, and a loaded capture wears
-// the 180-degree flip below. Framing the local box would aim the camera at the
-// mirror image of where the scene actually is, which is invisible for anything
-// not centred on the origin, so push the box through the world matrix first.
-function frameCamera(camera, controls, mesh) {
- let box;
- try { box = mesh.getBoundingBox(true); } catch { box = null; }
- if (!box || box.isEmpty()) box = new Box3(new Vector3(-1, -1, -1), new Vector3(1, 1, 1));
- mesh.updateMatrixWorld(true);
- box.applyMatrix4(mesh.matrixWorld);
- const center = box.getCenter(new Vector3());
- const radius = Math.max(box.getSize(new Vector3()).length() / 2, 0.001);
- const distance = (radius / Math.sin((FOV * Math.PI) / 360)) * 1.15;
- camera.near = Math.max(distance / 1000, 0.001);
- camera.far = distance * 100;
- camera.updateProjectionMatrix();
- camera.position.set(center.x, center.y, center.z + distance);
- controls.target.copy(center);
- controls.update();
- return { center: center.clone(), position: camera.position.clone() };
-}
-
+// -- Core render --------------------------------------------------------------
async function renderBuffer(buffer, { label, fileType, fileName, flip = true }) {
_lastRender = { buffer, fileType, fileName, label, flip };
- setLoading('Decoding radiance field…', `${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB`);
- const SPARK = await loadSplatLib();
+ setLoading('Decoding radiance field\u2026', `${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB`);
teardown();
- const host = HOST();
- host.innerHTML = '';
-
- // Opaque, and antialias off on Spark's own advice: MSAA does nothing for
- // splats and costs real frame time. Opaque is not a style choice either.
- // Spark accumulates splat colour with premultiplied alpha and leaves the
- // destination alpha at zero, so on a transparent canvas the browser
- // composites a fully rendered scene away to nothing. The clear colour stands
- // in for the stage's own gradient, which the canvas covers.
- const renderer = new WebGLRenderer({ antialias: false });
- renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
- renderer.setSize(host.clientWidth || 640, host.clientHeight || 420);
- host.appendChild(renderer.domElement);
-
- const scene = new Scene();
- scene.background = new Color(0x0f0e16);
- const camera = new PerspectiveCamera(FOV, (host.clientWidth || 640) / (host.clientHeight || 420), 0.01, 1000);
- const controls = new OrbitControls(camera, renderer.domElement);
- controls.enableDamping = true;
- // Spark sorts the splats on a worker and only paints once that first sort
- // lands, which on a weak GPU is a visible second or more. Without this the
- // stage would go live over an empty canvas and read as a broken page, so
- // hold the loading state until Spark says it has something to draw. The
- // timeout is the safety net: a scene that never reports back still gets
- // handed to the user rather than hanging on the overlay forever.
- let onFirstPaint;
- const firstPaint = new Promise((resolve) => { onFirstPaint = resolve; });
- const spark = new SPARK.SparkRenderer({ renderer, onDirty: () => onFirstPaint() });
- scene.add(spark);
+ const token = _token;
- const stage = { renderer, scene, camera, controls, spark, mesh: null, frame: 0, home: null };
- _stage = stage;
-
- let mesh;
+ let scene;
try {
- mesh = new SPARK.SplatMesh({ fileBytes: buffer, fileType, fileName });
- // 3DGS captures are authored Y-down, so every viewer in the ecosystem
- // flips them 180 degrees about X to stand them up. Our procedural samples
- // are authored Y-up and pass flip:false.
- if (flip) mesh.quaternion.set(1, 0, 0, 0);
- await mesh.initialized;
+ scene = await mountSplatScene(HOST(), buffer, {
+ fileType,
+ fileName,
+ flip,
+ onSorting: (count) => {
+ if (token !== _token) return;
+ setLoading('Sorting splats\u2026', count ? `${count.toLocaleString()} splats` : '');
+ },
+ onContextLost: () => {
+ if (token !== _token) return;
+ _scene = null;
+ setError('The 3D context was lost', 'Your browser released the WebGL context, usually after a GPU reset or heavy memory pressure. Load the scene again to restore it.');
+ },
+ });
} catch (err) {
- teardown();
- setError('That file isn’t a valid splat', `Expected a ${ACCEPTED} Gaussian-splat scene. Check the file and try again.`);
+ if (token !== _token) return false;
+ setError('That file isn\u2019t a valid splat', `Expected a ${SPLAT_EXTENSIONS_LABEL} Gaussian-splat scene. Check the file and try again.`);
console.error('[splat] decode failed', err);
return false;
}
- if (_stage !== stage) { try { mesh.dispose(); } catch { /* superseded mid-decode */ } return false; }
-
- stage.mesh = mesh;
- scene.add(mesh);
- stage.home = frameCamera(camera, controls, mesh);
-
- const resize = () => {
- const w = host.clientWidth || 640;
- const h = host.clientHeight || 420;
- renderer.setSize(w, h);
- camera.aspect = w / h;
- camera.updateProjectionMatrix();
- };
- stage.resize = resize;
- window.addEventListener('resize', resize);
- resize();
+ // A newer load started while this one was decoding: throw this one away rather
+ // than letting it paint over the scene the user is now waiting on.
+ if (token !== _token) { scene.dispose(); return false; }
- const tick = () => {
- if (_stage !== stage) return;
- stage.frame = requestAnimationFrame(tick);
- controls.update();
- renderer.render(scene, camera);
- };
- stage.frame = requestAnimationFrame(tick);
-
- watchContextLoss(stage);
- const count = mesh.packedSplats?.numSplats;
- setLoading('Sorting splats…', count ? `${count.toLocaleString()} splats` : '');
- await Promise.race([firstPaint, new Promise((r) => setTimeout(r, FIRST_PAINT_TIMEOUT_MS))]);
- if (_stage !== stage) return false;
- setLive(count ? `${label} · ${count.toLocaleString()} splats` : label);
+ _scene = scene;
+ setLive(scene.count ? `${label} \u00b7 ${scene.count.toLocaleString()} splats` : label);
return true;
}
-// A GPU driver reset or a browser-reclaimed context leaves a live canvas painting
-// nothing. Say so instead of showing a frozen frame, and offer the way back.
-function watchContextLoss(stage) {
- const canvas = stage.renderer?.domElement;
- if (!canvas) return;
- canvas.addEventListener('webglcontextlost', (e) => {
- e.preventDefault();
- if (_stage !== stage) return;
- teardown();
- setError('The 3D context was lost', 'Your browser released the WebGL context, usually after a GPU reset or heavy memory pressure. Load the scene again to restore it.');
- }, { once: true });
-}
-
// Reset the camera on the live scene. Rebuilding from the cached buffer also
// works, but it drops and recreates a WebGL context for what is a two-line
// transform change, and the stage flashes through the loading overlay.
function recenter() {
- const s = _stage;
- if (s?.home) {
- s.camera.position.copy(s.home.position);
- s.controls.target.copy(s.home.center);
- s.controls.update();
- return;
- }
+ if (_scene) { _scene.recenter(); return; }
if (_lastRender) renderBuffer(_lastRender.buffer, _lastRender);
}
@@ -309,7 +160,7 @@ async function loadFromUrl(url, label) {
try { parsed = new URL(url, location.href); } catch { setError('That doesn’t look like a URL', url); return; }
parsed = normalizeAssetUrl(parsed);
setLoading('Fetching splat…', parsed.hostname);
- const SPARK = await loadSplatLib();
+ const SPARK = await loadSpark();
let buffer;
try {
const res = await fetch(parsed.href);
@@ -321,7 +172,7 @@ async function loadFromUrl(url, label) {
return;
}
const name = parsed.pathname.split('/').pop() || 'remote.splat';
- const ok = await renderBuffer(buffer, { label: label || name, fileName: name, fileType: formatFor(name, buffer, SPARK) });
+ const ok = await renderBuffer(buffer, { label: label || name, fileName: name, fileType: detectSplatFormat(name, buffer, SPARK) });
// The bytes are already in memory, so a remote scene is as saveable as an
// uploaded one. Handing back the fetched buffer also spares the user a second
// round trip to a host that may not allow one.
@@ -329,12 +180,12 @@ async function loadFromUrl(url, label) {
}
async function loadFromFile(file) {
- const SPARK = await loadSplatLib();
+ const SPARK = await loadSpark();
setLoading('Reading file…', file.name);
let buffer;
try { buffer = await file.arrayBuffer(); }
catch (err) { setError('Couldn’t read that file', err.message); return; }
- const ok = await renderBuffer(buffer, { label: file.name, fileName: file.name, fileType: formatFor(file.name, buffer, SPARK) });
+ const ok = await renderBuffer(buffer, { label: file.name, fileName: file.name, fileType: detectSplatFormat(file.name, buffer, SPARK) });
setDownload(ok ? URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' })) : null, file.name);
}
@@ -410,7 +261,7 @@ function sampleBust(count = 14000) {
}
async function loadSample(kind) {
- const SPARK = await loadSplatLib();
+ const SPARK = await loadSpark();
const isBust = kind === 'bust';
const buffer = isBust ? sampleBust() : sampleShell();
const label = isBust ? 'Synthetic head bust' : 'Radiance shell';