This started as a set of Node.js SDK/CLI, standalone-packaged, converters: take a tiled / LoD source format — HLOD Hierarchical Level of Detail, tiled point clouds, meshes, or 3D Gaussian splats (COPC, Potree, I3S, stream-SOG, LCC, RAD, 3MX, GeoSplats, …) — and
turn it into OGC 3D Tiles 1.1 (splats via KHR_gaussian_splatting +
KHR_gaussian_splatting_compression_spz_2 GLB tiles). The unifying idea behind every converter is
the same: translate each of the tree-hierarchy and tile-geometry as-is, since each source format is already some spatial tree of pre-tiled, LoD'd content — so the
converter just maps that tree onto a 3D Tiles HLOD tree, implicit (octree/quadtree) or explicit (arbitrary), and re-encodes node content into one shared
output (standard mesh primitives, TRIANGLES, POINTS, or spzGlb.js for splats). The decode differs per format; the output is uniform.
It has since grown into an on-the-fly streaming middleware (packages/tile-server, the offline
converters' live counterpart): point it at a <format> source URL and it serves a 3D Tiles tileset
live, so any 3D-Tiles-compatible client — browser/JS viewers, CesiumJS or its native plugins
(Unreal, Unity, Nvidia Omniverse, Open-3d-Engine), GIS software (QGIS, ESRI etc), anything that speaks the OGC standard — can consume any of these tiled
formats without a pre-conversion step, with tile-hierarchy/content caching and prefetching
tunable per use case (cache=none|hierarchy|all). The viewer (CesiumJS + 3DTilesRendererJS) is the
reference client, and doubles as a bbox + geometric-error-aware crop/extract tool (/extract/*) for
pulling a sub-region, with user-controlled Geometric Error target precision, of any of these formats back out as LAS/COPC/GLB/SPZ/SOG/PLY.
Where this is going next. Two items that used to be listed here as "concrete and addressable" are
now done: containerizing the server (Dockerfile + docker-compose.yml + a GHCR-publishing GitHub
Actions workflow — docker compose up --build runs the whole stack) and a first pass at the
Fumadocs documentation site (apps/docs) — most of this README's detail now lives there; see
Documentation below.
Further out: a browser/server tiled-splat transcoding UI in the spirit of SuperSplat's splat-transform
tooling; a georeferencing/geolocator step for splats that don't ship one, along the lines of
WilliamLiu's 3dtiles-inspector or MapTiler GeoSplats'; and an aggregator unifying the
export/interchange formats of other splat platforms, behind the same 3D Tiles pipeline. A
longer-running goal underneath all of this: be the fastest point-cloud — and eventually splat —
tiler, by reusing the octree-computation principles behind Potree 2.0's converter.
This README is a pitch + quickstart. The detailed, up-to-date documentation — architecture,
per-converter usage, endpoint reference, format specs, TODOs, and findings — lives in a
Fumadocs site under apps/docs.
→ Deployed: docs.3dtiled.iconem.com (live demo viewer:
demo.3dtiled.iconem.com, middleware:
3dtiled.iconem.com). Those are this project's instances, published
from the GHCR images by the docker-publish workflow and fronted by Traefik.
Or run it locally:
pnpm --filter docs dev # http://localhost:3002You can also read the source .md files directly on GitHub under
apps/docs/content/docs/guide/ and
apps/docs/content/docs/references/.
Self-hosting note. Those domains appear only here, in the human-facing README. The running services never hardcode them: the tile-server's homepage and
openapi.jsonbuild their links fromDOCS_URL/VIEWER_URL/REPO_URL(and the request's own origin), so your deployment links to your instances, not these. Seepackages/tile-server/homepage-live.jsand the{{DOCS_URL}}placeholder inopenapi.json.
Guide pages (mirrors this README's original section breakdown, one page each):
- Introduction · Ambition · Format comparison
- Related tilers / prior art · Monorepo & usage · TODO / Future work
- Architecture: the materialization continuum · Converters · Sample Data
- Dependencies · Performance & parallelism · Candidate source formats
- Documentation (findings, format notes) · 3D Gaussian Splatting extension lineage
- Vision: towards a TiTiler for 3D · Known blockers
- Missing features & unsupported code-paths · Appendix: per-format schema diagrams
Format-spec deep-dives (canonical sources + hand-distilled local notes), readable directly on GitHub
under docs-references/ — e.g.
copc-format.md, potree-format.md,
rad-format-notes.md, lcc-format.md,
i3s-spec.md, streamed-sog.md,
sog.md, spz-format.md,
maptiler-geosplats.md, and 16 more (see the directory listing).
npm/pnpm workspaces monorepo. Two ports cover day-to-day use:
pnpm install # installs the whole workspace
pnpm dev # http://localhost:3000 (3D Tiled — the React viewer app, + /vanilla-viewer + /docs folded in)
# http://localhost:3001 (tile-server — the streaming/convert middleware)pnpm dev runs the viewer's Vite dev server alongside the tile-server and the Fumadocs site's Next dev
server (port 3002, proxied under /docs from the viewer — see Documentation above to
reach it directly). pnpm uses pnpm-workspace.yaml + .npmrc (node-linker=hoisted); npm's workspaces
field works too.
Layout at a glance:
apps/
viewer/ 3D Tiled — React 19 + Vite viewer app (CesiumJS + 3DTilesRendererJS), port 3000
docs/ Fumadocs site — the canonical docs (see above), port 3002
packages/
core/ 3dtiles-convert-core — shared: SPZ-v2 GLB + POINTS GLB encoders, parallelMap, format detection
convert/ 3dtiles-convert — meta-converter; `3dtiled` CLI + JS/TS API, auto-detects format
tile-server/ — live streaming/convert/extract HTTP middleware, port 3001
rad-to-3dtiles/ sog-to-3dtiles/ lcc-to-3dtiles/ copc-to-3dtiles/ potree-to-3dtiles/ i3s-to-3dtiles/
— the per-format offline converters (each its own package + deps)
docs-references/ hand-distilled format-spec notes (mirrored into apps/docs/content/docs/references/)
sample-data/ small input/output fixtures used by the converters and viewer presets
Each per-format converter is independent (install just the one you need); the meta-converter
(packages/convert) auto-detects input format and dispatches to the right one:
npm run convert -- <input> <outDir> [--format rad|sog|lcc|lcc2|copc|potree|i3s]
# or directly:
node packages/convert/cli.js sample-data/input/RAD/coit.rad sample-data/output/rad/coit-3dtiles-from-radSee Converters and
Monorepo & usage for the full per-converter CLI/API
reference, and Vision: towards a TiTiler for 3D
for the live /stream, /convert, and /extract HTTP endpoints served by packages/tile-server.
🟢 = operational · 🟡 draft = scaffold built, partially/un-validated · 🟠 doc = spec referenced in
docs-references/, converter not built (lower-priority / niche). See
the full format-comparison page for canonical spec
links and local-mirror notes per format.
| Format | Status | Hierarchy / subdivision | Node (leaf) content | Refine | HTTP range |
|---|---|---|---|---|---|
| 3D Tiles (output) | 🟢 out | explicit or implicit; box/region/sphere volumes | glTF/GLB w/ KHR_gaussian_splatting+_spz_2 (splats) or POINTS/TRIANGLES |
REPLACE/ADD | ✅ |
| Format | Status | Hierarchy / subdivision | Node (leaf) content | Refine | HTTP range |
|---|---|---|---|---|---|
| COPC (Cloud Optimized Pointcloud) | 🟢 | octree (EPT-style) | LAZ-compressed LAS points | ADD | ✅ designed for range reads |
| Potree (v1 and v2) | 🟢 | octree (named r/r0..r7) |
points: position int32×3·scale+offset + rgb | ADD | ✅ |
| Format | Status | Hierarchy / subdivision | Node (leaf) content | Refine | HTTP range |
|---|---|---|---|---|---|
3D Tiles packages .3tz/.3dtiles |
🟢 | passthrough — whatever the wrapped tileset.json declares |
the wrapped tileset's own tile content, unchanged | (wrapped tileset's own) | N/A — O(1) offset/key lookup |
| I3S (Esri) | 🟡 draft | node tree (always explicit), OBB/MBS LoD (SLPK or REST) | nodes/geometry/textures; PerAttributeArray or Draco | REPLACE | ✅ REST/range |
| 3MX (Bentley/Acute3D) | 🟢 | master Scene.3mx JSON → 3MXBO binary node tree |
OpenCTM mesh + JPEG baseColor → transcoded to glTF | REPLACE | ➖ per-file GET |
| OSGB (OpenSceneGraph binary: ContextCapture, DJI Terra) | 🟢 live only | osg::PagedLOD nodes over one .osgb per level of each tile, metadata.xml for the SRS |
osg::Geometry mesh + embedded JPEG → glTF |
REPLACE | ➖ per-file GET |
| Bing Maps 3D | 🟢 | quadtree of quadkeys (availability by HTTP probe) | tf=3dv4 GLB — Draco + KTX2, ECEF in node matrix |
REPLACE | ➖ per-file GET |
Nexus (CNR-ISTI, 3DHOP: .nxs / .nxz) |
🟢 | one file, a DAG of mesh nodes coarse to fine (patches name the finer nodes); a tree by level or by path | node mesh (positions, normals, colours, uvs) + JPEG, Corto-decoded → glTF | REPLACE | ✅ header, tables, one node at a time |
| Format | Status | Hierarchy / subdivision | Node (leaf) content | Refine | HTTP range |
|---|---|---|---|---|---|
| SOG (streamed) (PlayCanvas) | 🟢 | binary spatial tree (AABB split) | unbundled SOG chunk: WebP textures → DataTable | REPLACE | ✅ per-file |
| LCC (XGRIDS) | 🟢 | grid of Units (cellX×Y) × per-cell LODs | Data.bin fixed 32 B/splat (+SH Shcoef.bin) |
REPLACE | ✅ offsets into Data.bin |
| RAD (SparkJS) | 🟢 | LoD merge tree, variable fanout | RADC chunk: per-splat columns, mixed encodings | REPLACE | ✅ chunked .radc |
| GeoSplats (MapTiler) | 🟢 | octree voxel grids × 8 progressive LODs | per-octant SOGS or octant_<n>.ply |
REPLACE (LOD subset) | ✅ per-file / range |
Six offline converters (packages/<fmt>-to-3dtiles) turn a tiled source format into 3D Tiles on disk:
copc-to-3dtiles, rad-to-3dtiles, sog-to-3dtiles, lcc-to-3dtiles, i3s-to-3dtiles (🟡 draft),
potree-to-3dtiles. Each has its own CLI, npm deps, and design notes (implicit-octree mapping for COPC,
LoD merge-tree decode for RAD, WebP/DataTable decode for SOG, etc). The repo also ships two viewers:
vanilla-viewer.html (offline, zero-React reference viewer) and 3D Tiled (apps/viewer, the React
port — shadcn/ui, R3F, CesiumJS + 3DTilesRendererJS side by side).
See the Converters guide for per-format CLI usage, output layout, design notes, and known scope gaps (e.g. I3S's Draco/attribute limitations).
npm/pnpm-workspaces monorepo: each input format is an independent converter package, a shared core
holds common machinery (SPZ-v2/POINTS GLB encoders, parallelism, format detection), and a
meta-converter (packages/convert) auto-detects input and dispatches. packages/tile-server is the
live streaming/convert/extract counterpart — see Vision: towards a TiTiler for
3D for its
endpoints.
See the Monorepo & usage guide for the meta-converter
API, /stream lazy-loading semantics, per-format native chunking units, and individual-converter usage.
A running, dated log of what's shipped recently, what's still open, and a survey of other capture/scanner ecosystems checked for tiled formats worth adding (none found so far worth an adapter). Includes the SPZ v4/v5 roadmap notes (Niantic Spatial's compression format used for splat tiles here).
See the TODO / Future work guide for the full, dated list.
The conceptual core of packages/tile-server: every live format adapter sits somewhere on one axis —
how much of the source dataset the middleware materializes before serving a tile, from cache=none
(pure pass-through decode per request) through cache=hierarchy (index cached, geometry streamed) to
cache=all//convert (fully preprocessed and cached, same code path as the offline converters). Covers
why push-based offline converters stay separate from the pull-based live path, the endpoint rework
history, and per-converter parallelism notes.
See the Architecture guide for the full model, the harmonization plan, and current vs. future endpoint shape.
Small, sample-data/-friendly fixtures and curl commands for RAD (Gaussian splat LoD), Streamed SOG
(PlayCanvas), and COPC (LiDAR) — real public/open datasets (Coit Tower, Autzen Stadium, IGN LiDAR HD,
PlayCanvas example scenes, etc), used by the converters' own README examples and the viewer's preset bar.
See the Sample Data guide for the full curl commands and source links.
A short table of the handful of non-obvious shared npm dependencies (copc, @gltf-transform/core,
proj4, @sparkjsdev/spark) and which converters use them.
See the Dependencies guide for the full table.
All five operational converters (rad, sog, lcc, copc, potree) fan tiles out via bounded-concurrency
parallelMap + async gzip (i3s, still a draft, remains serial); the outstanding piece is a real
worker_threads pool for multicore decode rather than just event-loop concurrency.
See the Performance & parallelism guide for the current, accurate per-converter picture (supersedes older performance notes elsewhere).
A ranked crawl (Candidates vs. Discarded, by openness × feasibility × remote-consumability) of GIS/CAD-AEC/VFX/heritage tiled formats not yet ingested — SPZ v5, Splatter, 2.5D terrain, OSGB, Nexus, SuperMap S3M — and blocked cases like Autodesk ReCap. Includes a separate 2.5D terrain track (DEM raster → TIN → 3D Tiles/quantized-mesh).
See the Candidate source formats guide for the full tier breakdown and implemented-adapter notes (3MX, Bing Maps 3D, Nexus).
How the glTF extensions for 3D Gaussian splatting evolved through 2025–2026 — from a single
experimental KHR_spz_gaussian_splats_compression to the current split of KHR_gaussian_splatting
(renderer-agnostic base) + KHR_gaussian_splatting_compression_spz_2 (SPZ-blob child extension).
Understanding this lineage is what pinned down a real SPZ-version rendering bug (see Known blockers).
See the 3D Gaussian Splatting extension lineage guide for the full timeline.
The live HTTP API surface of packages/tile-server: /convert (any-format → 3D Tiles, cached),
/3dtiles-self-contained (serve .3tz/.3dtiles packages in-place), 3D-Tiles-to-3D-Tiles transcodes,
and the assessed-but-blocked potree-to-copc (needs a JS LAZ encoder).
See the Vision guide for full endpoint semantics, request/response shapes, and implementation notes.
Two resolved war-stories kept for reference: (1) RAD splats rendering wrong after conversion — fixed by emitting SPZ v2, not v3; (2) COPC point clouds appearing "upside down" in 3DTilesRendererJS's Env controls (correct in Globe mode) — a renderer coordinate-convention mismatch, not a converter bug.
See the Known blockers guide for the full root-cause writeups.
A consolidated, honest list of what's not handled and where it would go: SH beyond DC, I3S's
Draco/texture/attribute gaps, parallelism/architecture notes, the two packages/tile-server modes,
true range-streaming status per format, and the live /geosplats, /extract, /proxy, and API
playground/OpenAPI endpoints.
See the Missing features guide for the full, itemized list.
Mermaid diagrams of each source format's LoD/hierarchy tree (RAD, Streamed SOG, LCC, COPC).
See the Appendix guide for the full diagrams.
MIT. Material mirrored under apps/docs/content/docs/references/ stays under its authors' own terms.