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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(splat): read the compressed capture formats, on Spark instead of a private viewer
nirholas22b9e24d5d21
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a68fd48eb..5cb422375 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- **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]`- **The partner-hosted demo page loads all of its pieces again**: Our partnership page is published once onto a partner's own website, so everything it loads comes from three.ws across origins. Two of its scripts were being refused by the browser there, which quietly cost the page its in-editor map and its iOS handoff. Both are now served with the same cross-origin permission the rest of the page already had, and an audit that loads the page from a foreign origin now passes end to end. `[fix]`+- **The splat viewer opens the compressed formats captures actually ship**: Gaussian-splat scenes used to arrive as enormous PLY files, and the tools that make them now export compressed containers instead: the same capture that is a gigabyte of PLY is about 100 MB as SPZ and about 42 MB as SOG. The viewer could not open either. It now reads .spz and .sog alongside .ply, .splat, and .ksplat, works out the format from the file contents instead of trusting the filename, and frames the camera on the scene it actually loaded rather than a fixed distance that suited one file in ten. It also shows the real splat count, and waits for the first sorted frame before going live so a slow machine no longer shows an empty stage. (`/splat`) `[improvement, feature]`- **Turn a photo into a 3D model without leaving your editor**: The Blender tools could already build a model from a written description. They now build one from a picture too: point at an image on your machine or a link to one, add a few words to steer it if you like, and the finished model opens in Blender. It runs on the same free lane as the text version and takes about as long. `[feature, sdk]`- **Tutorials and walkthroughs are now readable by search engines, and pages we never wanted indexed stopped asking to be**: The 76 tutorial and walkthrough pages loaded their content after the page opened, which meant a search engine reading the raw page found no text at all, and on tutorials found the words 'Tutorial not found' sitting under an empty heading. Those pages now arrive with their full text already in them, so they can finally be found by the questions they answer. Separately, eighteen pages were being submitted to Google while telling Google not to index them: sign-in surfaces, viewers that need a link to work, and one endpoint that returns data rather than a page. They have been withdrawn from the sitemap, and a new check refuses to let a page ask for indexing and refuse it at the same time. Two documentation pages that shared a title with the product page they described have been retitled. (`/tutorials`) `[improvement, docs]`- **World tiles show their artwork again**: The picker that lets you choose a community world was loading each world's artwork straight from a public storage gateway, and browsers now refuse to draw images served that way. Nine tiles on the page failed silently every visit. The artwork is now fetched through our own image service, so tiles paint their real picture, and a world whose artwork has gone missing falls back to its lettered tile instead of an empty square. `[fix]`diff --git a/data/changelog.json b/data/changelog.jsonindex d86efefab..9429a1e6b 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -26915,6 +26915,16 @@"improvement","feature"]+ },+ {+ "date": "2026-09-07",+ "title": "The splat viewer opens the compressed formats captures actually ship",+ "summary": "Gaussian-splat scenes used to arrive as enormous PLY files, and the tools that make them now export compressed containers instead: the same capture that is a gigabyte of PLY is about 100 MB as SPZ and about 42 MB as SOG. The viewer could not open either. It now reads .spz and .sog alongside .ply, .splat, and .ksplat, works out the format from the file contents instead of trusting the filename, and frames the camera on the scene it actually loaded rather than a fixed distance that suited one file in ten. It also shows the real splat count, and waits for the first sorted frame before going live so a slow machine no longer shows an empty stage.",+ "tags": [+ "improvement",+ "feature"+ ],+ "link": "/splat"}]}diff --git a/docs/oss-adoption-2026-09.md b/docs/oss-adoption-2026-09.mdindex c6fb291e8..46248472e 100644--- a/docs/oss-adoption-2026-09.md+++ b/docs/oss-adoption-2026-09.md@@ -13,18 +13,22 @@ answers "what should we adopt, and where does it go".Three passes, run on 2026-09-07:-1. **Gap detection.** A presence sweep of ~120 candidate project names across- `src/`, `api/`, `workers/`, `packages/`, `services/`, and `scripts/`. Anything- already wired (Kokoro TTS, `@pixiv/three-vrm`, Make-It-Animatable, TRELLIS,- Hunyuan3D 2.0/2.1, TripoSG, MDM, QuadriFlow, xatlas, meshoptimizer, Colyseus,- Yjs, Rapier, gltf-transform) was dropped from the list. This document only- contains things the repo genuinely lacks.+1. **Gap detection.** A presence sweep of roughly 250 candidate project names+ across `src/`, `api/`, `workers/`, `packages/`, `services/`, `scripts/`, and+ `server/`, in two rounds: one scoped to 3D and one across every other surface+ (audio, vision, LLM tooling, web infra, security, database, docs, i18n).+ Anything already wired was dropped, and that was most of the obvious list:+ Kokoro TTS, `@pixiv/three-vrm`, Make-It-Animatable, TRELLIS, Hunyuan3D+ 2.0/2.1, TripoSG, MDM, QuadriFlow, xatlas, meshoptimizer, Colyseus, Yjs,+ Rapier, gltf-transform, onnxruntime-web. **This document only contains things+ the repo genuinely lacks.**2. **Verification.** Every license, star count, and last-push date below camefrom the GitHub REST API or the npm registry directly, not from a blog. The"best of 2026" listicles were checked and discarded: several assert a- "TRELLIS.2" release that does not exist in `microsoft/TRELLIS`.-3. **Measurement, where a claim was cheap to test.** The BiRefNet latency- numbers below were measured locally rather than quoted.+ "TRELLIS.2" release that does not exist in `microsoft/TRELLIS`. Where GitHub+ reports `NOASSERTION`, the LICENSE file itself was read.+3. **Measurement, where a claim was cheap to test.** The BiRefNet latencies were+ measured, not quoted, and the Spark migration was driven in a real browser.Star counts are as of the sweep date and drift.@@ -32,10 +36,49 @@ Star counts are as of the sweep date and drift.## Shipped in this pass-### BiRefNet as an optional background-removal model+### 1. Spark, replacing the splat renderer++**[sparkjsdev/spark](https://github.com/sparkjsdev/spark)**+(`@sparkjsdev/spark`, MIT, 3.6k stars, by World Labs).++[/splat](https://three.ws/splat) ran on `@mkkellogg/gaussian-splats-3d`, which+reads `.ply`, `.splat`, and `.ksplat` and renders inside a private viewer of its+own. Three problems followed from that, and all three are fixed:++- **It could not open the formats real captures ship.** The same scene that is a+ 1 GB PLY is roughly 100 MB as [SPZ](https://github.com/nianticlabs/spz) (MIT,+ Niantic) and roughly 42 MB as+ [SOG](https://developer.playcanvas.com/user-manual/gaussian-splatting/formats/sog/)+ (PlayCanvas), 15 to 20 times smaller. Those are the files people are handed+ today and what SuperSplat exports. Both now load.+- **The format was guessed from the filename.** It is now read from the bytes,+ so a URL with a query string, a redirect, or no extension still decodes.+- **The camera sat at a fixed z=3.2 for every scene.** It now frames the splat+ centres in world space, which is the only thing that works across captures+ authored at wildly different scales.++Two things the migration surfaced that are worth writing down, because both look+like a broken page and neither is:++- Spark accumulates colour with premultiplied alpha and leaves destination alpha+ at zero. On a transparent canvas the browser composites a fully rendered scene+ away to nothing. The canvas has to be opaque.+- Spark sorts splats on a worker and only paints once that first sort lands, up+ to about a second on a weak GPU. The page now holds a "Sorting splats" state+ until Spark reports it has something to draw, with a timeout so a scene that+ never reports back is still handed over.++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.++### 2. BiRefNet as an optional background-removal model**[ZhengPeng7/BiRefNet](https://github.com/ZhengPeng7/BiRefNet)** (MIT, 4.2k-stars, last push 2026-09-02).+stars).The [rembg worker](../workers/rembg/) ran four DIS/U2Net-family models. Thosesmear a soft boundary (hair, fur, foliage, a thin strap) into a halo, and since@@ -44,8 +87,9 @@ becomes real polygons on the finished mesh.The pinned `rembg==2.0.59` already ships BiRefNet sessions; the worker's modelallowlist simply did not include them. `birefnet-general-lite` is now a-selectable model (short alias `birefnet`) across the worker, `api/forge-rembg.js`,-the x402 pipeline, the service catalog, and the MCP studio tool.+selectable model (short alias `birefnet`) across the worker,+`api/forge-rembg.js`, the x402 pipeline, the service catalog, and the MCP studio+tool.Measured on 4 threads with the repo's pinned `onnxruntime==1.28.0`, best of threewarm runs at 677x1024:@@ -56,8 +100,8 @@ warm runs at 677x1024:| `birefnet-general-lite` | 214 MB | 6.0 s |Six times the compute is worth it on a hero image and not worth it on a batch,-so the default is unchanged and the policy tests pin it that way. Details and-the model-choice table: [workers/rembg/README.md](../workers/rembg/README.md).+so the default is unchanged and the policy tests pin it that way. Details:+[workers/rembg/README.md](../workers/rembg/README.md).Note the license trap this avoids: **RMBG-2.0** is the model most "bestbackground removal" write-ups recommend, it is built on BiRefNet, and it is@@ -67,39 +111,7 @@ CC BY-NC 4.0. BiRefNet itself is MIT.## Tier 1: adopt next-### 1. Spark, for the splat surfaces--**[sparkjsdev/spark](https://github.com/sparkjsdev/spark)**-(`@sparkjsdev/spark`, MIT, 3.6k stars, npm 2.1.0) from World Labs.--Today [src/splat-viewer.js](../src/splat-viewer.js) drives-`@mkkellogg/gaussian-splats-3d`, which reads `.ply`, `.splat`, and `.ksplat`,-and runs its own `Viewer` with its own renderer and controls, separate from the-rest of the app's three.js scene. Two consequences:--- **We cannot open the formats modern captures actually ship.** PlayCanvas's- **SOG** is roughly 15-20x smaller than the equivalent PLY, and Niantic's- **[spz](https://github.com/nianticlabs/spz)** (MIT) is about 10x smaller.- A capture that is a 1 GB PLY is a ~42 MB SOG. On a page whose whole premise is- "open any splat scene in a browser", not reading the compressed formats is the- single biggest functional gap the viewer has.-- **Splats cannot share a scene with meshes.** Spark renders splats as ordinary- `THREE.Object3D`s inside an existing scene, with correct depth sorting against- mesh geometry, and supports transforms, color editing, displacement, and- skeletal animation on splats.--Spark reads PLY (including compressed), SPZ, SPLAT, KSPLAT, and SOG.--**Where it lands:** [src/splat-viewer.js](../src/splat-viewer.js) (368 lines) and-`src/forge-studio/lab/lab.js`, the only two consumers of the current library.-The teardown path is the delicate part: the current file releases the WebGL-context by hand because the old library's `dispose()` stops short of it, and a-Spark object living in a normal scene changes that shape entirely.--**Why it matters beyond the viewer:** a splat that can live in the main avatar-scene is the missing half of item 3 below.--### 2. OpenTelemetry, for fleet observability+### OpenTelemetry, for fleet observability**[open-telemetry/opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js)**(Apache-2.0, 3.5k stars).@@ -111,15 +123,13 @@ a slow `/forge` request that fans out to rembg, a mesh lane, rig, and texturecannot be attributed to a stage without reading four services' logs by hand.GCP has a first-party OTLP endpoint, so this is a pre-approved-surface adoption-with no new vendor: the Node SDK plus the Cloud Trace exporter in-[server/index.mjs](../server/index.mjs), and `traceparent` propagated on the-worker fetches in `api/_providers/gcp.js`.+with no new vendor.-**Where it lands:** `server/index.mjs` (boot), `api/_providers/gcp.js` (context-propagation to the workers), and each Python worker's FastAPI app for the far-end of the span.+**Where it lands:** [server/index.mjs](../server/index.mjs) (boot),+`api/_providers/gcp.js` (propagating `traceparent` to the workers), and each+Python worker's FastAPI app for the far end of the span.-### 3. LHM, for one-selfie photoreal humans+### LHM, for one-selfie photoreal humans**[aigc3d/LHM](https://github.com/aigc3d/LHM)** (Apache-2.0, 2.7k stars,ICCV 2025).@@ -128,23 +138,23 @@ ICCV 2025).onto a fixed-topology Wolf3D template: MediaPipe landmarks, a TPS texture warp,and a geometry morph. That is a sound, CPU-cheap, commercially clean design, andit is bounded by the template. It cannot produce hair, clothing, or body shape-that the template does not already have.+the template does not already have.LHM reconstructs an **animatable** 3D human from a single image and drives itwith SMPL-X pose, which is the interface our retargeter already thinks in.Published inference times are 1.41 s (LHM-MINI, 16 GB), 2.01 s (LHM-500M), and6.57 s (LHM-1B). It outputs 3D Gaussians, with a mesh export path.-This is why it is listed after Spark: LHM's native output is splats, and Spark-is what would let that render on the existing avatar stage next to GLB avatars-instead of in a walled-off viewer. Adopted together they are one feature,-"photoreal animatable avatar from one photo", not two.+This moved up the list the moment Spark shipped: LHM's native output is splats,+and Spark is what lets that render on the existing avatar stage next to GLB+avatars instead of in a walled-off viewer. Together they are one feature,+"photoreal animatable avatar from one photo".**Where it lands:** a new GPU lane beside the existing reconstruction worker, nota replacement. The template path stays as the CPU-cheap default and theguaranteed-riggable fallback.-### 4. Real part segmentation+### Real part segmentation[workers/segment](../workers/segment/) is deliberately pure geometry: connectedcomponents first, then geometric splitting. That is exactly right for an@@ -161,15 +171,32 @@ Two MIT options fill that in, and they solve different halves:- **[VAST-AI-Research/HoloPart](https://github.com/VAST-AI-Research/HoloPart)**(MIT, 665 stars) does amodal part completion: it recovers each part as a wholeobject, including the hidden geometry where parts meet, which is what makes a- split part actually usable as a swappable component.+ split part usable as a swappable component.**Avoid [nv-tlabs/PartField](https://github.com/nv-tlabs/PartField).** It is thebest-known name in this space and its NVIDIA License clause 3.3 restricts use to-non-commercial research and educational purposes. It cannot ship here.+non-commercial research and education. It cannot ship here.++### Audio2Face-3D, for real facial performance++**[NVIDIA/Audio2Face-3D](https://github.com/NVIDIA/Audio2Face-3D)**, open-sourced+in 2025 under the **NVIDIA Open Model License** (not an OSI license: read it+before committing, and see the trap table below).++Our avatars already ship the 52 ARKit blendshapes and 15 visemes+([workers/avatar-reconstruction](../workers/avatar-reconstruction/)), and lipsync+today is `wawa-lipsync` estimating visemes from the audio signal. Audio2Face-3D+is a 180M-parameter audio-to-facial-motion model, and NVIDIA's microservice form+of it emits ARKit blendshapes directly, which is the exact rig we already drive.+That is the difference between mouth shapes that track the audio and a facial+performance with jaw, tongue, and eyes.-**Where it lands:** PartCrafter as a forge lane option; HoloPart as a stage-inside [workers/segment](../workers/segment/) that runs after the geometric-split when the caller asks for complete parts.+It wants an NVIDIA GPU with TensorRT, which the fleet already has, and three.ws+is already in NVIDIA Inception, so the relationship for a license question exists.++**Where it lands:** a GPU worker producing an ARKit-52 blendshape track, consumed+by the existing lipsync path in `src/` alongside the cheap `wawa-lipsync`+fallback, the same way BiRefNet sits beside isnet: quality tier, not default.---@@ -177,13 +204,58 @@ split when the caller asks for complete parts.| Project | License | Why | Lands in ||---|---|---|---|-| [DreamTechAI/Direct3D-S2](https://github.com/DreamTechAI/Direct3D-S2) | MIT (1.3k stars) | Sparse-voxel latent diffusion at gigascale resolution; a genuinely different geometry prior from TRELLIS and Hunyuan | New `workers/model-direct3d-s2`, as a peer of the existing mesh backends |-| [stepfun-ai/Step1X-3D](https://github.com/stepfun-ai/Step1X-3D) | Apache-2.0 (888 stars) | Two-stage geometry then texture, fully open including training code | Same, another forge backend |-| [huanngzh/MV-Adapter](https://github.com/huanngzh/MV-Adapter) | Apache-2.0 (1.3k stars, ICCV 2025) | [workers/texture](../workers/texture/) hand-rolls multiview consistency with SDXL plus ControlNet-Depth and a back-projection pass; MV-Adapter is a purpose-built multiview-consistent adapter for exactly that | `workers/texture/`, replacing the per-view generation step and keeping the existing UV bake |-| [microsoft/MoGe](https://github.com/microsoft/MoGe) | MIT (2.9k stars; GitHub misreports this as unlicensed, the LICENSE file is MIT) | Accurate monocular geometry, useful as a depth prior for image-to-3D conditioning and for `/capture` on a single photo | `workers/model-video2scene/` as a single-image path |-| [facebookresearch/map-anything](https://github.com/facebookresearch/map-anything) | Apache-2.0 (3.7k stars) | Universal feed-forward metric 3D reconstruction. Prefer it over VGGT, which is the more famous model in this category and is not permissively licensed (see below) | `workers/model-video2scene/`, beside LingBot-Map |-| [playcanvas/supersplat](https://github.com/playcanvas/supersplat) | MIT (10k stars) | A full splat editor. Once Spark lands, this is the reference for what a three.ws splat editing surface should do, and its SOG writer is the export path | Reference plus `@playcanvas/splat-transform` (MIT) as the server-side SOG encoder |-| [EricGuo5513/momask-codes](https://github.com/EricGuo5513/momask-codes) | MIT (1.3k stars) | [workers/model-text2motion](../workers/model-text2motion/) chose MDM over MoMask on license grounds; the repo is MIT, so that call is worth re-testing on quality. Check the HumanML3D training-data terms separately from the code license before acting | `workers/model-text2motion/mdm_sampler.py` is already the only model-specific file, by design |+| [DreamTechAI/Direct3D-S2](https://github.com/DreamTechAI/Direct3D-S2) | MIT (1.3k) | Sparse-voxel latent diffusion at gigascale resolution; a genuinely different geometry prior from TRELLIS and Hunyuan | New `workers/model-direct3d-s2`, peer of the existing mesh backends |+| [stepfun-ai/Step1X-3D](https://github.com/stepfun-ai/Step1X-3D) | Apache-2.0 (888) | Two-stage geometry then texture, fully open including training code | Same, another forge backend |+| [huanngzh/MV-Adapter](https://github.com/huanngzh/MV-Adapter) | Apache-2.0 (1.3k) | [workers/texture](../workers/texture/) hand-rolls multiview consistency with SDXL plus ControlNet-Depth and a back-projection pass; MV-Adapter is a purpose-built multiview-consistent adapter for exactly that | `workers/texture/`, replacing the per-view generation step, keeping the UV bake |+| [microsoft/MoGe](https://github.com/microsoft/MoGe) | MIT (2.9k; GitHub misreports it as unlicensed, the LICENSE file is MIT) | Accurate monocular geometry as a depth prior for image-to-3D conditioning and for `/capture` from a single photo | `workers/model-video2scene/` as a single-image path |+| [facebookresearch/map-anything](https://github.com/facebookresearch/map-anything) | Apache-2.0 (3.7k) | Universal feed-forward metric 3D reconstruction. Prefer it over VGGT, the more famous model in this category, which is not permissively licensed | `workers/model-video2scene/`, beside LingBot-Map |+| [playcanvas/supersplat](https://github.com/playcanvas/supersplat) + `@playcanvas/splat-transform` | MIT (10k) | Now that Spark reads SOG, this is the encoder that writes it and the reference for a three.ws splat editing surface | A server-side SOG encode step, so captures are served compressed |+| [facebookresearch/sam2](https://github.com/facebookresearch/sam2) | Apache-2.0 (19.8k) | Promptable image and video segmentation. The `/motion-swap` mask lane and any "select this object" tool are both SAM-shaped problems | `workers/model-video2motion/` mask stage |+| [EricGuo5513/momask-codes](https://github.com/EricGuo5513/momask-codes) | MIT (1.3k) | [workers/model-text2motion](../workers/model-text2motion/) chose MDM over MoMask on license grounds; the repo is MIT, so that call is worth re-testing on quality. Check the HumanML3D training-data terms separately from the code license | `workers/model-text2motion/mdm_sampler.py` is already the only model-specific file, by design |++---++## Beyond 3D: what the second sweep found++The 3D sweep is where the product lives, but the wider sweep turned up gaps that+have nothing to do with rendering and are cheaper to close.++### Supply chain and secrets: nothing off the shelf is installed++`scripts/check-secrets.mjs` is a good hand-rolled push-time scan, and there is no+dependency-vulnerability or static-analysis tooling at all. Three drop-ins, all+of which run locally and none of which need GitHub Actions (which this repo does+not use):++- **[google/osv-scanner](https://github.com/google/osv-scanner)** (Apache-2.0,+ 11k) reads `package-lock.json` and the Python requirements files and reports+ known vulnerabilities. The `overrides` block in `package.json` shows this work+ is already being done by hand, one CVE at a time.+- **[gitleaks/gitleaks](https://github.com/gitleaks/gitleaks)** (MIT, 29k) as a+ second opinion beside the existing secrets check, which is worth having on a+ repo where a leaked key is a live wallet.+- **[semgrep/semgrep](https://github.com/semgrep/semgrep)** (LGPL-2.1, 16.5k) for+ the rules the custom `check:rules` cannot express. Note the LGPL: run it as a+ tool, do not vendor it into shipped code.++### Dead code: [webpro-nl/knip](https://github.com/webpro-nl/knip) (ISC, 12k)++"Delete aggressively" is a stated operating rule, and nothing mechanically+enforces it across 60-plus top-level directories, ~90 workspace packages, and+1,989 test files. Knip finds unused files, exports, and dependencies in exactly+this shape of monorepo. Expect a large first report; the value is in the+dependency and export findings, not the file list.++### Voice, if the neural TTS lane ever needs to grow++Kokoro already ships as the free in-browser voice, which was the right call and+covers the common case. If a lane ever needs zero-shot voice cloning or more+expressive delivery, the permissively licensed options are+**[resemble-ai/chatterbox](https://github.com/resemble-ai/chatterbox)** (MIT,+26k) and **[canopyai/Orpheus-TTS](https://github.com/canopyai/Orpheus-TTS)**+(Apache-2.0, 6.3k). **F5-TTS is the one to avoid**: its weights are CC BY-NC.+For speech-in, **[SYSTRAN/faster-whisper](https://github.com/SYSTRAN/faster-whisper)**+(MIT, 25k) is the standard server-side Whisper runtime.---@@ -198,9 +270,12 @@ actual LICENSE file, not the GitHub sidebar.| `briaai/RMBG-2.0` | CC BY-NC 4.0, commercial use needs a paid license. It is built on BiRefNet, which is MIT. Use BiRefNet || `nv-tlabs/PartField` | NVIDIA License 3.3: non-commercial research and education only || `facebookresearch/vggt` | Custom "VGGT License v1" with an Acceptable Use Policy and pass-through redistribution terms, not an OSI license. MapAnything (Apache-2.0) covers the same ground |-| `ByteDance-Seed/Depth-Anything-3` | Split licensing. DA3-SMALL, DA3-BASE, DA3MONO-LARGE, DA3METRIC-LARGE are Apache-2.0; DA3-LARGE, DA3-GIANT, and the DA3NESTED series are CC BY-NC 4.0. The repo code is Apache-2.0, so the checkpoint choice is the whole question |+| `ByteDance-Seed/Depth-Anything-3` | Split licensing. DA3-SMALL, DA3-BASE, DA3MONO-LARGE, DA3METRIC-LARGE are Apache-2.0; DA3-LARGE, DA3-GIANT and the DA3NESTED series are CC BY-NC 4.0. The repo code is Apache-2.0, so the checkpoint choice is the whole question |+| `SWivid/F5-TTS` | Weights are CC BY-NC. Chatterbox (MIT) and Orpheus (Apache-2.0) are the commercial-safe equivalents |+| `NVIDIA/Audio2Face-3D` | NVIDIA Open Model License. Permissive in intent and not OSI-approved; read it and record the read before the lane ships || `zju3dv/GVHMR` | Custom Zhejiang University terms, not permissive || `graphdeco-inria/hierarchical-3d-gaussians` | Inherits the INRIA 3DGS license, which is non-commercial |+| `semgrep/semgrep` | LGPL-2.1. Fine as a developer tool, not as vendored code |`microsoft/MoGe` is the inverse case: GitHub reports no license, and the LICENSEfile is plain MIT.@@ -210,21 +285,24 @@ file is plain MIT.## Deliberately not recommended- **A new JS 3D engine** (Babylon, PlayCanvas engine, Needle). three.js is the- foundation and the entire `avatar-sdk` public contract. Spark is recommended+ foundation and the entire `avatar-sdk` public contract. Spark was adoptedprecisely because it extends three.js instead of replacing it.- **A client-side search library** (Orama, MiniSearch). Search here runs againstPostgres over records the browser does not hold, and `@leeoniya/ufuzzy` alreadycovers in-page filtering.- **`transformers.js` as a general runtime.** `onnxruntime-web` is already the- in-browser inference path and Kokoro TTS already runs on it. Adding a second- runtime buys nothing unless a specific model needs it.+ in-browser inference path and Kokoro TTS already runs on it. A second runtime+ buys nothing unless a specific model needs it.- **`spz-js`.** It is the obvious way to add `.spz` support without touching the- renderer, and it depends on the entire `playcanvas` engine to do it. Spark- reads `.spz` natively.+ renderer, and it pulls in the entire `playcanvas` engine to do it. Spark reads+ `.spz` natively.- **UniRig.** Already evaluated and retired here in favour of Make-It-Animatable(see [workers/rig/README.md](../workers/rig/README.md)); its live instance- produced unusable 22-bone skeletons. Noting only that upstream has moved since- that call, so it is a re-test candidate rather than a closed question.+ produced unusable 22-bone skeletons. Upstream has moved since that call, so it+ is a re-test candidate rather than a closed question.+- **A JS linter swap** (oxlint, Biome). Prettier plus the custom `check:rules`+ already covers what this repo enforces, and the rules that matter here are+ house rules no off-the-shelf linter knows.---@@ -235,7 +313,7 @@ rebuilt:```bash# Does the repo already use a given project, anywhere that matters?-grep -ril 'PartCrafter' src api workers packages services scripts | grep -v node_modules+grep -ril 'PartCrafter' src api workers packages services scripts server | grep -v node_modules# Verify a license and its activity from the source, not a blog.curl -s https://api.github.com/repos/wgsxm/PartCrafter |@@ -243,6 +321,6 @@ curl -s https://api.github.com/repos/wgsxm/PartCrafter |console.log(j.full_name, j.license?.spdx_id, j.stargazers_count, j.pushed_at)})"# A NOASSERTION spdx_id means "GitHub could not classify it", not "no license".-# Read the file.+# Read the file. This is where the traps above were found.curl -s https://raw.githubusercontent.com/wgsxm/PartCrafter/main/LICENSE | head -20```diff --git a/docs/splat.md b/docs/splat.mdindex d145efd01..a05d2cbb2 100644--- a/docs/splat.md+++ b/docs/splat.md@@ -1,21 +1,30 @@# Splat Viewer: photoreal Gaussian-splat avatars in the browser-The Splat Viewer renders Gaussian-splat and radiance-field scenes right in your browser, the photoreal output of capture engines like GaussianAvatars and HumanGaussian. Load a `.ply`, `.splat`, or `.ksplat` by URL, drop a file in, or try a built-in sample, and orbit a photoreal avatar or scene with no plugin, no upload to a server, and no account. All decoding happens client-side.+The Splat Viewer renders Gaussian-splat and radiance-field scenes right in your browser, the photoreal output of capture engines like GaussianAvatars and HumanGaussian. Load a `.ply` (plain or compressed), `.spz`, `.splat`, `.ksplat`, or `.sog` by URL, drop a file in, or try a built-in sample, and orbit a photoreal avatar or scene with no plugin, no upload to a server, and no account. All decoding happens client-side.Page: [/splat](https://three.ws/splat)## Why it exists-Mesh avatars (GLB) are lightweight, riggable, and universal, and that is what most of three.ws generates. But the photoreal frontier of avatar capture is radiance fields: Gaussian splatting reconstructs a person or a scene as millions of tiny anisotropic blobs that render with real skin, hair, and lighting no polygon budget can match. Those captures ship as `.ply`, `.splat`, or `.ksplat` files, and most tools to view them are desktop apps. The Splat Viewer is the browser front door: a place to open any splat scene, evaluate a capture engine's output, and share a photoreal avatar with a link. It complements [/avatar-engines](https://three.ws/avatar-engines), which surveys the capture methods; the viewer is where their output actually renders.+Mesh avatars (GLB) are lightweight, riggable, and universal, and that is what most of three.ws generates. But the photoreal frontier of avatar capture is radiance fields: Gaussian splatting reconstructs a person or a scene as millions of tiny anisotropic blobs that render with real skin, hair, and lighting no polygon budget can match. Those captures ship as `.ply`, `.spz`, `.splat`, `.ksplat`, or `.sog` files, and most tools to view them are desktop apps. The compressed containers matter: the same scene that is a 1 GB PLY is roughly 100 MB as SPZ and roughly 42 MB as SOG, which is the difference between a scene you can share as a link and one you cannot. The Splat Viewer is the browser front door: a place to open any splat scene, evaluate a capture engine's output, and share a photoreal avatar with a link. It complements [/avatar-engines](https://three.ws/avatar-engines), which surveys the capture methods; the viewer is where their output actually renders.## How it works-The viewer (`src/splat-viewer.js`) is entirely client-side. It uses `@mkkellogg/gaussian-splats-3d`, already a platform dependency (the same library the Forge Studio Lab uses), lazy-loaded on first render so the page shell paints instantly. Format is detected from the filename extension: `.ply` maps to the PLY scene format, `.ksplat` to the compressed KSplat format, and everything else to the antimatter15 `.splat` layout (32 bytes per splat). The decoded buffer is handed to a `GS.Viewer` with built-in orbit controls, and every state is designed: idle, fetching, decoding, error, and a live HUD showing the scene label.+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.++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:++- **The format is read from the bytes, not the filename.** A URL that ends in a query string, a redirect, or no extension at all still decodes. Only two containers fall back to the name: `.splat` is a raw 32-byte-per-splat array with no header to sniff, and a bundled `.sog` is a zip.+- **The camera frames the scene it actually loaded**, from the splat centres in world space. Splat scenes are authored at wildly different scales, and a fixed camera distance is right for exactly one of them.+- **The live state waits for the first sorted frame.** Spark sorts splats on a worker and paints once that lands, so the stage holds a "Sorting splats" state rather than going live over an empty canvas on a slow GPU.+- **The canvas is opaque.** Spark accumulates colour with premultiplied alpha and leaves destination alpha at zero, so a transparent canvas would composite a fully rendered scene away to nothing.++Every state is designed: idle, fetching, decoding, sorting, error, and a live HUD showing the scene label and its real splat count.There are three ways to load a scene:- **By URL.** Paste a link and the viewer fetches the bytes and decodes them. To survive cross-origin blocks, it rewrites the human-facing URLs of common asset hosts to their CORS-enabled raw form: GitHub `raw`/`blob` links become `raw.githubusercontent.com`, Hugging Face `/blob/` becomes `/resolve/`, and Dropbox links are forced to a direct download. When a host still blocks the browser fetch, the error state tells you to download the file and upload it instead. Because the bytes are already in memory once a remote scene renders, the download control offers them back, so a scene you reached by URL is as saveable as one you uploaded.-- **By file.** Pick a file or drag and drop a `.ply`/`.splat`/`.ksplat` onto the stage. The file is read locally and never leaves your machine; a download button is offered for the loaded buffer.+- **By file.** Pick a file or drag and drop a `.ply`/`.spz`/`.splat`/`.ksplat`/`.sog` onto the stage. The file is read locally and never leaves your machine; a download button is offered for the loaded buffer.- **Samples.** Two procedurally generated scenes ship in the page: a radiance shell (6,000 splats) and a synthetic head-and-shoulders bust (14,000 splats) that evokes what a real GaussianAvatars capture looks like in the viewer. These are synthetic, generated in-browser, and downloadable.A deep link, `?src=<url>&name=<label>`, loads a scene straight from the URL on page load, so a photoreal avatar is shareable with a single link. A recenter control resets the camera on the live viewer, so it snaps back without dropping and rebuilding the WebGL context. Teardown is explicit: the renderer's graphics context is released by hand on every scene swap and when the page is hidden, because the splat library's own dispose stops short of that. If the browser drops the context anyway, after a GPU reset or under memory pressure, the stage reports it and offers a reload rather than freezing on the last frame.@@ -24,7 +33,7 @@ A deep link, `?src=<url>&name=<label>`, loads a scene straight from the URL on p1. Open [/splat](https://three.ws/splat).2. Try a sample first: click the radiance shell or the head bust to see the viewer in action.-3. Load your own scene: paste a `.ply`/`.splat`/`.ksplat` URL and click Render, or drop a file onto the stage, or pick one from disk.+3. Load your own scene: paste a `.ply`/`.spz`/`.splat`/`.ksplat`/`.sog` URL and click Render, or drop a file onto the stage, or pick one from disk.4. Orbit, zoom, and pan with the built-in controls. The HUD shows the scene label and splat count.5. Recenter if the camera drifts. Download the loaded buffer, whether the scene came from a file, a sample, or a URL.6. Share a scene by appending `?src=<url>` to the page URL.@@ -43,7 +52,9 @@ https://three.ws/splat?src=https://github.com/<user>/<repo>/blob/main/scene.splaSupported inputs at a glance:-- `.ply`: Gaussian-splat point cloud in PLY format.+- `.ply`: Gaussian-splat point cloud in PLY format, plain or in PlayCanvas's compressed variant.+- `.spz`: [Niantic's compressed container](https://github.com/nianticlabs/spz), about a tenth the size of the equivalent PLY. The broadest delivery format in the ecosystem.+- `.sog`: [PlayCanvas Spatially Ordered Gaussians](https://developer.playcanvas.com/user-manual/gaussian-splatting/formats/sog/), roughly 15 to 20 times smaller than the PLY. What SuperSplat exports.- `.splat`: the antimatter15 layout (32 bytes per splat).- `.ksplat`: the compressed KSplat format for faster loads.diff --git a/package-lock.json b/package-lock.jsonindex b2bb208e5..62b32929b 100644--- a/package-lock.json+++ b/package-lock.json@@ -137,6 +137,7 @@"@solana/pay": "^0.2.6","@solana/spl-token": "^0.4.14","@solana/web3.js": "^1.98.4",+ "@sparkjsdev/spark": "^2.1.0","@sparticuz/chromium-min": "^148.0.0","@tetsuo-ai/protocol": "^0.2.0","@tetsuo-ai/sdk": "^1.4.0",@@ -16254,6 +16255,18 @@"webidl-conversions": "^3.0.0"}},+ "node_modules/@sparkjsdev/spark": {+ "version": "2.1.0",+ "resolved": "https://registry.npmjs.org/@sparkjsdev/spark/-/spark-2.1.0.tgz",+ "integrity": "sha512-BRw+MuMzx0B3K8fDLQygt2OHEhYUV+41RX7btq9pZ3rCVrq42o57jW34VAIvC7JO/84DJh/1AutACV9ym6BfVg==",+ "license": "MIT",+ "dependencies": {+ "fflate": "^0.8.2"+ },+ "peerDependencies": {+ "three": ">=0.180.0"+ }+ },"node_modules/@sparticuz/chromium-min": {"version": "148.0.0","license": "MIT",@@ -40281,7 +40294,7 @@},"packages/blender-mcp": {"name": "@three-ws/blender-mcp",- "version": "0.3.0",+ "version": "0.5.0","license": "Apache-2.0","dependencies": {"@gltf-transform/core": "^4.4.0",diff --git a/package.json b/package.jsonindex 4e5ed93a4..92b890d7e 100644--- a/package.json+++ b/package.json@@ -518,6 +518,7 @@"@solana/pay": "^0.2.6","@solana/spl-token": "^0.4.14","@solana/web3.js": "^1.98.4",+ "@sparkjsdev/spark": "^2.1.0","@sparticuz/chromium-min": "^148.0.0","@tetsuo-ai/protocol": "^0.2.0","@tetsuo-ai/sdk": "^1.4.0",diff --git a/pages/splat.html b/pages/splat.htmlindex c6620b132..1bd7d09e7 100644--- a/pages/splat.html+++ b/pages/splat.html@@ -6,14 +6,14 @@<meta http-equiv="X-UA-Compatible" content="IE=edge" /><title data-i18n="splat.meta_title">Splat Viewer — Photoreal Gaussian Avatars · three.ws</title><meta name="viewport" content="width=device-width, initial-scale=1.0" />- <meta name="description" content="View photoreal Gaussian-splat and radiance-field avatars in the browser. Load a .ply / .splat / .ksplat by URL or upload — the same WebGL splat engine that powers the three.ws Lab." data-i18n-attr="content:splat.meta_description"/>+ <meta name="description" content="View photoreal Gaussian-splat and radiance-field avatars in the browser. Load a .ply, .spz, .splat, .ksplat, or .sog by URL or upload. Compressed captures decode client-side, nothing is uploaded." data-i18n-attr="content:splat.meta_description"/><meta name="theme-color" content="#000000" /><link rel="canonical" href="https://three.ws/splat" /><meta property="og:type" content="website" /><meta property="og:site_name" content="three.ws" /><meta property="og:title" content="Splat Viewer — Photoreal Gaussian Avatars · three.ws" data-i18n-attr="content:splat.meta_og_title"/>- <meta property="og:description" content="View photoreal Gaussian-splat avatars in the browser — load a .ply / .splat / .ksplat by URL or upload. The realistic-head output of engines like GaussianAvatars and HumanGaussian, rendered live." data-i18n-attr="content:splat.meta_og_description"/>+ <meta property="og:description" content="View photoreal Gaussian-splat avatars in the browser: load a .ply, .spz, .splat, .ksplat, or .sog by URL or upload. The realistic-head output of engines like GaussianAvatars and HumanGaussian, rendered live." data-i18n-attr="content:splat.meta_og_description"/><meta property="og:url" content="https://three.ws/splat" /><meta property="og:image" content="https://three.ws/api/page-og?s=build&t=Splat+Viewer%3A+Photoreal+Gaussian+Avatars&d=Render+Gaussian-splat+and+radiance-field+avatars+in+the+browser%3A+the+photoreal+output+of+engines+like+GaussianAvatars+and+HumanGaussian.+Load+a+.ply+%2F+.splat+%2F&p=%2Fsplat" /><meta name="twitter:card" content="summary_large_image" />@@ -175,7 +175,7 @@<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1"><meta property="og:locale" content="en_US"><meta property="og:image:alt" content="Splat Viewer — Photoreal Gaussian Avatars — three.ws">- <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Splat Viewer - Photoreal Gaussian Avatars","description":"Render Gaussian-splat and radiance-field avatars in the browser - the photoreal output of engines like GaussianAvatars and HumanGaussian. Load a .ply / .splat / .ksplat by URL or upload; decoding runs entirely client-side.","url":"https://three.ws/splat","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=build&t=Splat+Viewer+-+Photoreal+Gaussian+Avatars&d=Render+Gaussian-splat+and+radiance-field+avatars+in+the+browser+-+the+photoreal+output+of+engines+like+GaussianAvatars+and+HumanGaussian.+Load+a+.ply+%2F+.splat+%2F&p=%2Fsplat"}]}</script>+ <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Splat Viewer - Photoreal Gaussian Avatars","description":"Render Gaussian-splat and radiance-field avatars in the browser - the photoreal output of engines like GaussianAvatars and HumanGaussian. Load a .ply, .spz, .splat, .ksplat, or .sog by URL or upload; decoding runs entirely client-side.","url":"https://three.ws/splat","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=build&t=Splat+Viewer+-+Photoreal+Gaussian+Avatars&d=Render+Gaussian-splat+and+radiance-field+avatars+in+the+browser+-+the+photoreal+output+of+engines+like+GaussianAvatars+and+HumanGaussian.+Load+a+.ply+%2F+.splat+%2F&p=%2Fsplat"}]}</script></head><body><div class="sp-page">@@ -189,7 +189,7 @@<p data-i18n-html="splat.render_gaussian_splat_and_radiance_field_ava">Render Gaussian-splat and radiance-field avatars right in the browser — the photoreal outputof engines like <a href="/avatar-engines?family=photoreal-head">GaussianAvatars and HumanGaussian</a>.- Load a <code>.ply</code>, <code>.splat</code>, or <code>.ksplat</code> by URL or drop a file in.+ Load a <code>.ply</code>, <code>.spz</code>, <code>.splat</code>, <code>.ksplat</code>, or <code>.sog</code> by URL or drop a file in.</p></header>@@ -203,7 +203,7 @@<svg width="26" height="26" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><circle cx="12" cy="12" r="9"/><circle cx="9" cy="10" r="1.4" fill="currentColor"/><circle cx="15" cy="10" r="1.4" fill="currentColor"/><circle cx="12" cy="14" r="1.4" fill="currentColor"/><circle cx="8" cy="15" r="1.1" fill="currentColor"/><circle cx="16" cy="15" r="1.1" fill="currentColor"/></svg></div><h3 data-i18n="splat.load_a_splat_to_begin">Load a splat to begin</h3>- <p data-i18n-html="splat.drop_a_here_paste_a_url_or">Drop a <code>.ply</code> / <code>.splat</code> / <code>.ksplat</code> here, paste a URL, or try a sample on the right.</p>+ <p data-i18n-html="splat.drop_a_here_paste_a_url_or">Drop a <code>.ply</code>, <code>.spz</code>, <code>.splat</code>, <code>.ksplat</code>, or <code>.sog</code> here, paste a URL, or try a sample on the right.</p><button class="sp-btn" id="sp-idle-pick" type="button" style="width:auto">Choose a file</button></div>@@ -256,7 +256,7 @@<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 3v12 M7 11l5 4 5-4 M5 21h14"/></svg>Upload a file</button>- <input id="sp-file" type="file" accept=".ply,.splat,.ksplat" hidden />+ <input id="sp-file" type="file" accept=".ply,.spz,.splat,.ksplat,.sog" hidden /><p class="sp-hint" data-i18n="splat.files_stay_on_your_device_decoding_runs">Files stay on your device — decoding runs entirely in your browser.</p></div>diff --git a/public/changelog.json b/public/changelog.jsonindex 7021b554f..994e6e3ae 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-07T20:35:47.680Z",+ "generated_at": "2026-09-07T20:49:20.490Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -187,6 +187,17 @@"fix"]},+ {+ "date": "2026-09-07",+ "type": "update",+ "title": "The splat viewer opens the compressed formats captures actually ship",+ "summary": "Gaussian-splat scenes used to arrive as enormous PLY files, and the tools that make them now export compressed containers instead: the same capture that is a gigabyte of PLY is about 100 MB as SPZ and about 42 MB as SOG. The viewer could not open either. It now reads .spz and .sog alongside .ply, .splat, and .ksplat, works out the format from the file contents instead of trusting the filename, and frames the camera on the scene it actually loaded rather than a fixed distance that suited one file in ten. It also shows the real splat count, and waits for the first sorted frame before going live so a slow machine no longer shows an empty stage.",+ "link": "/splat",+ "tags": [+ "improvement",+ "feature"+ ]+ },{"date": "2026-09-07","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 19512f113..5869da7ed 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -142,6 +142,14 @@<category>fix</category><description>Our partnership page is published once onto a partner's own website, so everything it loads comes from three.ws across origins. Two of its scripts were being refused by the browser there, which quietly cost the page its in-editor map and its iOS handoff. Both are now served with the same cross-origin permission the rest of the page already had, and an audit that loads the page from a foreign origin now passes end to end.</description></item>+ <item>+ <title>The splat viewer opens the compressed formats captures actually ship</title>+ <link>https://three.ws/splat</link>+ <guid isPermaLink="false">2026-09-07:The splat viewer opens the compressed formats captures actually ship</guid>+ <pubDate>Mon, 07 Sep 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>Gaussian-splat scenes used to arrive as enormous PLY files, and the tools that make them now export compressed containers instead: the same capture that is a gigabyte of PLY is about 100 MB as SPZ and about 42 MB as SOG. The viewer could not open either. It now reads .spz and .sog alongside .ply, .splat, and .ksplat, works out the format from the file contents instead of trusting the filename, and frames the camera on the scene it actually loaded rather than a fixed distance that suited one file in ten. It also shows the real splat count, and waits for the first sorted frame before going live so a slow machine no longer shows an empty stage.</description>+ </item><item><title>Turn a photo into a 3D model without leaving your editor</title><link>https://three.ws/changelog</link>diff --git a/public/locales/en.json b/public/locales/en.jsonindex 37d34c66b..fd1f2c7d4 100644--- a/public/locales/en.json+++ b/public/locales/en.json@@ -18532,15 +18532,15 @@"couldn_t_load_that_splat": "Couldn’t load that splat","download_splat_arialabel": "Download splat","download_splat_title": "Download splat",- "drop_a_here_paste_a_url_or": "Drop a <code>.ply</code> / <code>.splat</code> / <code>.ksplat</code> here, paste a URL, or try a sample on the right.",+ "drop_a_here_paste_a_url_or": "Drop a <code>.ply</code>, <code>.spz</code>, <code>.splat</code>, <code>.ksplat</code>, or <code>.sog</code> here, paste a URL, or try a sample on the right.","fetching_and_decoding_the_radiance_field": "Fetching and decoding the radiance field.","files_stay_on_your_device_decoding_runs": "Files stay on your device — decoding runs entirely in your browser.","gaussian_splatting_webgl": "Gaussian Splatting · WebGL","load_a_splat_to_begin": "Load a splat to begin","load_by_url": "Load by URL","loading_splat_engine": "Loading splat engine…",- "meta_description": "View photoreal Gaussian-splat and radiance-field avatars in the browser. Load a .ply / .splat / .ksplat by URL or upload — the same WebGL splat engine that powers the three.ws Lab.",- "meta_og_description": "View photoreal Gaussian-splat avatars in the browser — load a .ply / .splat / .ksplat by URL or upload. The realistic-head output of engines like GaussianAvatars and HumanGaussian, rendered live.",+ "meta_description": "View photoreal Gaussian-splat and radiance-field avatars in the browser. Load a .ply, .spz, .splat, .ksplat, or .sog by URL or upload. Compressed captures decode client-side, nothing is uploaded.",+ "meta_og_description": "View photoreal Gaussian-splat avatars in the browser: load a .ply, .spz, .splat, .ksplat, or .sog by URL or upload. The realistic-head output of engines like GaussianAvatars and HumanGaussian, rendered live.","meta_og_title": "Splat Viewer — Photoreal Gaussian Avatars · three.ws","meta_title": "Splat Viewer — Photoreal Gaussian Avatars · three.ws","meta_twitter_description": "Render photoreal Gaussian-splat avatars in the browser.",@@ -18550,7 +18550,7 @@"radiance_shell_6k_splats": "<span class=\"sp-sample-dot\" style=\"background:#86efac\"></span> Radiance shell · 6k splats","recenter_camera_arialabel": "Recenter camera","recenter_camera_title": "Recenter camera",- "render_gaussian_splat_and_radiance_field_ava": "Render Gaussian-splat and radiance-field avatars right in the browser — the photoreal output of engines like <a href=\"/avatar-engines?family=photoreal-head\">GaussianAvatars and HumanGaussian</a>. Load a <code>.ply</code>, <code>.splat</code>, or <code>.ksplat</code> by URL or drop a file in.",+ "render_gaussian_splat_and_radiance_field_ava": "Render Gaussian-splat and radiance-field avatars right in the browser — the photoreal output of engines like <a href=\"/avatar-engines?family=photoreal-head\">GaussianAvatars and HumanGaussian</a>. Load a <code>.ply</code>, <code>.spz</code>, <code>.splat</code>, <code>.ksplat</code>, or <code>.sog</code> by URL or drop a file in.","samples": "Samples","samples_are_procedurally_generated_to_exerci": "Samples are procedurally generated to exercise the renderer — not real captures.","splat_scene_url": "Splat scene URL",diff --git a/src/splat-viewer.js b/src/splat-viewer.jsindex 1d610f1d0..38085612a 100644--- a/src/splat-viewer.js+++ b/src/splat-viewer.js@@ -1,11 +1,25 @@// Splat Viewer — render Gaussian-splat / radiance-field avatars in the browser.//-// Reuses @mkkellogg/gaussian-splats-3d (already a project dependency, used by the-// Forge Studio Lab). Loads a .ply / .splat / .ksplat from a URL (?src=), a file-// upload, or a procedurally generated sample. Every state is designed: idle,-// loading, error, and the live HUD.+// 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.+//+// 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.-import { Color } from 'three';+import { Box3, Color, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from 'three';+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';const $ = (s, r = document) => r.querySelector(s);@@ -13,40 +27,36 @@ const STAGE = () => $('#sp-stage');const HOST = () => $('#sp-host');// ── Splat lib (lazy) ─────────────────────────────────────────────────────────-let _GS = null;+let _spark = null;async function loadSplatLib() {- if (!_GS) _GS = await import('@mkkellogg/gaussian-splats-3d');- return _GS;+ if (!_spark) _spark = await import('@sparkjsdev/spark');+ return _spark;}-// ── Active viewer lifecycle ──────────────────────────────────────────────────-let _viewer = null;-let _objectUrl = null; // blob URL feeding the viewer+// ── Active scene lifecycle ───────────────────────────────────────────────────+let _stage = null; // { renderer, scene, camera, controls, spark, mesh, frame }let _downloadUrl = null; // blob URL backing the download button-let _lastRender = null; // { buffer, format, label } — for recenter / re-render--async function teardown() {- if (!_viewer) return;- const v = _viewer;- _viewer = null;- // dispose() nulls viewer.renderer partway through, so grab it first.- const renderer = v.renderer;- try {- v.stop?.();- // dispose() tears down the renderer then tries body.removeChild(rootElement),- // which throws for our nested host. Everything we care about is gone by then.- await v.dispose?.();- } catch { /* harmless nested-root removeChild from the splat lib */ }- // renderer.dispose() frees the three.js caches but leaves the WebGL context- // alive, and the removeChild throw above aborts the lib's own final cleanup- // before it can finish. Without an explicit release, every scene swap leaks a- // live GL context, and a browser only grants a page a handful of those before- // it starts reclaiming the oldest ones out from under a running scene.+let _lastRender = null; // { buffer, fileType, label, flip }, for recenter / re-render++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 {- renderer?.forceContextLoss?.();- renderer?.dispose?.();+ s.renderer?.forceContextLoss?.();+ s.renderer?.dispose?.();} catch { /* context already lost */ }- if (_objectUrl) { URL.revokeObjectURL(_objectUrl); _objectUrl = null; }+ s.resize && window.removeEventListener('resize', s.resize);const host = HOST();if (host) host.innerHTML = '';}@@ -58,117 +68,217 @@ function showOnly(id) {if (node) node.hidden = k !== id;}}-function setLoading(title, sub) {- $('#sp-loading-title').textContent = title;- if (sub != null) $('#sp-loading-sub').textContent = sub;- $('#sp-hud').hidden = true;++function setLoading(title, detail) {showOnly('sp-loading');+ const t = $('#sp-loading-title');+ const d = $('#sp-loading-detail');+ if (t) t.textContent = title;+ if (d) d.textContent = detail || '';+ setHud(null);}-function setError(title, sub) {- $('#sp-error-title').textContent = title;- $('#sp-error-sub').textContent = sub || '';- $('#sp-hud').hidden = true;++function setError(title, detail) {showOnly('sp-error');+ const t = $('#sp-error-title');+ const d = $('#sp-error-detail');+ if (t) t.textContent = title;+ if (d) d.textContent = detail || '';+ setHud(null);}+function setLive(label) {- $('#sp-hud-label').textContent = label;- $('#sp-hud').hidden = false;- for (const k of ['sp-idle', 'sp-loading', 'sp-error']) $(`#${k}`).hidden = true;+ showOnly(null);+ setHud(label);+}++function setHud(label) {+ const hud = $('#sp-hud');+ if (!hud) return;+ hud.hidden = !label;+ if (label) hud.textContent = label;+ const recenter = $('#sp-recenter');+ if (recenter) recenter.hidden = !label;}function setDownload(url, filename) {const btn = $('#sp-download');- if (_downloadUrl && _downloadUrl !== url) URL.revokeObjectURL(_downloadUrl);- if (!url) { btn.hidden = true; btn.removeAttribute('href'); _downloadUrl = null; return; }+ if (!btn) return;+ if (_downloadUrl) URL.revokeObjectURL(_downloadUrl);_downloadUrl = url;+ if (!url) { btn.hidden = true; btn.removeAttribute('href'); return; }btn.href = url;btn.download = filename || 'avatar.splat';btn.hidden = false;}// ── Format detection ─────────────────────────────────────────────────────────-function formatFor(name, GS) {+// 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('.ply')) return GS.SceneFormat.Ply;- if (n.endsWith('.ksplat')) return GS.SceneFormat.KSplat;- return GS.SceneFormat.Splat;+ 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 CAMERA_START = [0, 0, 3.2];-const CAMERA_TARGET = [0, 0, 0];+const FOV = 55;+const FIRST_PAINT_TIMEOUT_MS = 8000;-async function renderBuffer(buffer, { label, format }) {- _lastRender = { buffer, format, label };+// 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() };+}++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 GS = await loadSplatLib();- await teardown();+ const SPARK = await loadSplatLib();+ teardown();const host = HOST();host.innerHTML = '';- _objectUrl = 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: CAMERA_START,- initialCameraLookAt: CAMERA_TARGET,- });- _viewer = viewer;+ // 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 stage = { renderer, scene, camera, controls, spark, mesh: null, frame: 0, home: null };+ _stage = stage;++ let mesh;try {- await viewer.addSplatScene(_objectUrl, {- format: format ?? GS.SceneFormat.Splat,- showLoadingUI: false,- progressiveLoad: false,- });- viewer.start();- watchContextLoss(viewer);- setLive(label);- return true;+ 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;} catch (err) {- await teardown();- setError('That file isn’t a valid splat', 'Expected a .ply, .splat, or .ksplat Gaussian-splat scene. Check the file and try again.');+ teardown();+ setError('That file isn’t a valid splat', `Expected a ${ACCEPTED} 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();++ 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);+ 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(viewer) {- const canvas = viewer.renderer?.domElement;+function watchContextLoss(stage) {+ const canvas = stage.renderer?.domElement;if (!canvas) return;canvas.addEventListener('webglcontextlost', (e) => {e.preventDefault();- if (_viewer !== viewer) return;+ 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 viewer. Rebuilding from the cached buffer also+// 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 v = _viewer;- if (v?.camera && v.controls) {- v.camera.position.set(...CAMERA_START);- v.controls.target.set(...CAMERA_TARGET);- v.camera.lookAt(v.controls.target);- v.controls.update();- v.forceRenderNextFrame?.();+ 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 (_lastRender) renderBuffer(_lastRender.buffer, _lastRender);}// Rewrite the page/redirect URLs of common asset hosts to their CORS-enabled-// raw form. GitHub and Hugging Face host most public .ply/.splat scenes, but-// their human-facing URLs (github.com/.../raw, .../blob, HF /blob) 302-redirect-// or serve HTML, and the redirect target's CORS headers break a browser fetch.+// raw form. GitHub and Hugging Face host most public splat scenes, but their+// human-facing URLs (github.com/.../raw, .../blob, HF /blob) 302-redirect or+// serve HTML, and the redirect target's CORS headers break a browser fetch.// The canonical raw hosts (raw.githubusercontent.com, HF /resolve) send// `Access-Control-Allow-Origin: *`, so the same file loads cleanly.function normalizeAssetUrl(parsed) {@@ -199,7 +309,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 GS = await loadSplatLib();+ const SPARK = await loadSplatLib();let buffer;try {const res = await fetch(parsed.href);@@ -211,7 +321,7 @@ async function loadFromUrl(url, label) {return;}const name = parsed.pathname.split('/').pop() || 'remote.splat';- const ok = await renderBuffer(buffer, { label: label || name, format: formatFor(name, GS) });+ const ok = await renderBuffer(buffer, { label: label || name, fileName: name, fileType: formatFor(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.@@ -219,12 +329,12 @@ async function loadFromUrl(url, label) {}async function loadFromFile(file) {- const GS = await loadSplatLib();+ const SPARK = await loadSplatLib();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, format: formatFor(file.name, GS) });+ const ok = await renderBuffer(buffer, { label: file.name, fileName: file.name, fileType: formatFor(file.name, buffer, SPARK) });setDownload(ok ? URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' })) : null, file.name);}@@ -300,12 +410,14 @@ function sampleBust(count = 14000) {}async function loadSample(kind) {- const GS = await loadSplatLib();+ const SPARK = await loadSplatLib();const isBust = kind === 'bust';const buffer = isBust ? sampleBust() : sampleShell();- const label = isBust ? 'Synthetic head bust · 14,000 splats' : 'Radiance shell · 6,000 splats';- const ok = await renderBuffer(buffer, { label, format: GS.SceneFormat.Splat });- setDownload(ok ? URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' })) : null, isBust ? 'sample-bust.splat' : 'sample-shell.splat');+ const label = isBust ? 'Synthetic head bust' : 'Radiance shell';+ const name = isBust ? 'sample-bust.splat' : 'sample-shell.splat';+ // Authored Y-up, so skip the capture-convention flip.+ const ok = await renderBuffer(buffer, { label, fileName: name, fileType: SPARK.SplatFileType.SPLAT, flip: false });+ setDownload(ok ? URL.createObjectURL(new Blob([buffer], { type: 'application/octet-stream' })) : null, name);}// ── Wiring ───────────────────────────────────────────────────────────────────