Evaluate Potree-Next vs extending RUXP streaming for LOD point cloud rendering

[pfmephisto]

The GUI viewport currently streams point clouds via RUXP binary paging but has no spatial level-of-detail — a 10M-point scan either loads in full or is truncated to a prefix. Two competing approaches exist; this issue tracks the evaluation of Potree-Next as one candidate.

Context

The rux GUI frontend (apps/rux/frontend) renders point clouds with a custom Three.js scene (src/viewport/PointCloudScene.ts). Points arrive from ruxd as streamed RUXP v1 binary pages (/clouds/{name}/points), decoded client-side and appended to a THREE.Points geometry per page. This works well for moderate clouds but gives a viewport full of nothing (or a prefix slice) for large scans.

Current state

• RUXP binary paging is live (PR S10 chunked/binary point transport for /clouds/{name}/points #283). Each page is a spatially-unordered chunk; the client displays a leading prefix of the cloud until all pages arrive.
• Issue Voxel LOD for /clouds/{name}/points (and Draco as a stretch) #320 ("Voxel LOD for /clouds/{name}/points") is open and in-progress: it proposes server-side voxel-grid downsampling via a max_points query parameter, and considers precomputing a Morton/octree ordering so paging and LOD collapse into one mechanism.
• No Potree integration exists; the frontend has no .potree tile consumer.

Scope

Potree-Next converts a point cloud into an octree tile tree of .potree chunk files served from a static directory. The browser fetches only the tiles that intersect the current camera frustum at the appropriate LOD level — providing immediate coarse previews of arbitrarily-large clouds with no per-request server compute.

The evaluation should answer:

1. Feasibility — can .rux clouds be exported to the Potree format at create clouds time (or on demand)? What is the conversion cost and storage overhead?
2. Serving model — Potree tiles are static files; RUXP pages are dynamic queries. Can ruxd serve tile trees alongside its existing API, or does this require a separate static file server?
3. Recommendation — is Potree-Next the right fit, or is extending the existing RUXP approach (Morton ordering + max_points, per Voxel LOD for /clouds/{name}/points (and Draco as a stretch) #320) sufficient and less disruptive? Produce a concrete decision with measured tradeoffs.

If Potree is deemed feasible and superior, follow-up issues should be filed covering: converter integration, ruxd tile-serving, and replacing PointCloudScene.ts's paging model with Potree-Next's PointCloudOctree.

Related

• GUI application: web frontend + C++ backend, designed via Claude Design #265 — GUI application plan (the viewport lives inside the rux GUI frontend described here)
• Voxel LOD for /clouds/{name}/points (and Draco as a stretch) #320 — Voxel LOD via RUXP max_points parameter — the competing approach; this evaluation should either complement or supersede it

[pfmephisto]

Research findings — Potree-Next vs RUXP LOD

Full write-up: docs/research/potree-vs-ruxp-lod.md (PR below).

---

Key findings

1. "Potree-Next" is two different projects

• m-schuetz/Potree-Next — WebGPU rewrite, AGPL-3.0, not a three.js
  integration. AGPL-3.0 requires delivering source to all network users.
  Incompatible with a proprietary server component; not evaluable as a drop-in.
• potree/potree — the original; BSD-2-Clause ✅; last code commit Apr 2024,
  development stalled, 822 open issues.

2. PotreeConverter only reads LAS/LAZ — not PLY

Verified experimentally: running the nixpkgs binary
(PotreeConverter unstable-2023-02-27) against a 1.2 M-point binary PLY
exported from the NewOffice scan produces #points: 0 and crashes. The source
confirms a single LasLoader — no PLY code path exists.

We have no LAS exporter. The conversion pipeline would require either a new
rux export las command (new dep: liblas/PDAL/laszip) or a custom C++
Potree 2.0 octree writer (~1 500 lines, equivalent to PotreeConverter's
indexer.cpp).

3. Best three.js loader: tentone/potree-core

@pnext/three-loader (last release Aug 2021, open issue #79: no Potree 2.0
support) is effectively abandoned. The actively maintained option is
tentone/potree-core (MIT, v2.0.15 Apr 2026, last commit 2026-09-14),
an ES-module wrapper around the Potree 2.0 octree.bin/hierarchy.bin/
metadata.json format with three.js as a peer dep.

4. Potree 2.0 format is implementable in C++

The format is 3 files total (metadata.json, octree.bin, hierarchy.bin), served
via HTTP Range: requests. The format is documented well enough to implement
a native C++ writer in io/. This is the cleanest path if Potree is chosen.

5. The label streaming gap

Our RUXP lod_source parameter zips label clouds against the geometry voxel
selection, keeping them index-aligned. Pre-baked Potree tiles cannot express
this — label mode would need a separate convert pipeline and loses dynamic
switching. This is a fundamental architectural mismatch for our use case.

---

Recommendation

Extend RUXP with Morton ordering + frustum-tile index (close #321 as
"won't do — not now").

The voxel LOD in #320 is already live. The remaining gap for interactive
exploration of large scans is solvable incrementally:

1. Morton ordering at create clouds time — any prefix = spatial LOD,
   no per-request voxel pass needed.
2. Spatial tile index — a compact per-page bounding-box index enables
   frustum-culled fetching from the existing /clouds/{name}/points endpoint.
3. Multi-level LOD — with Morton order, skip-sampling gives coarse/fine
   levels; the client transitions as the user zooms.

Potree wins when (a) scans exceed ~50 M points after create clouds — O(N)
per-request becomes expensive at that scale — or (b) multi-user CDN serving
(ruxd Phase 6) becomes a requirement. Neither is current.

If Potree is chosen over this recommendation, the follow-up issues are:

• rux export las (new dep)
• rux create potree subprocess integration OR native C++ Potree 2.0 writer
• Frontend replacement with tentone/potree-core
• Separate solution for label overlay (no clean answer today)

Effort comparison: Morton + tile index ≈ 2–3 weeks; Potree integration ≈ 4–6 weeks + label overlay gap.