Skip to content

Commit da43372

Browse files
claudeclaude
committed
feat(cesium): scaffold optional Cesium/ArcGIS reference + parity oracle (skeleton)
12-module skeleton — compiling, ///-commented scaffold only, NO live impl yet. Optional/dev workspace member (crates/*, NOT in default-members → optional by construction). Hard rules baked into lib.rs: reverse-engineer-ONLY → CAM SoA; NO JSON in hotpath (ArcGIS PBF preferred over f=json); refactor > reverse- engineer. Grounding refs (CesiumGS/cesium, KHR_gaussian_splatting + SPZ, arcpbf/arcgisutils/arcGIS-Rust-runtime/locup, staehlli/3D-settlement, Inria .ply) in the module map. Sonnet battery fills the 12 slots next (groups A-D); Opus + CodeRabbit/Codex review live before any impl is uncommented. The oracle's live 'run real Cesium' stays commented until a reference renderer is wired (first ref = Inria .ply via splat3d::ply).
1 parent f054bc7 commit da43372

14 files changed

Lines changed: 162 additions & 0 deletions

‎crates/cesium/Cargo.toml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[package]
2+
name = "cesium"
3+
version = "0.0.0"
4+
edition = "2021"
5+
publish = false
6+
description = "OPTIONAL Cesium/ArcGIS reference + parity oracle — NOT a production dependency. Reverse-engineers 3D Tiles / KHR_gaussian_splatting / ArcGIS-PBF into ndarray CAM SoA for parity diffing against splat3d. Dev/reference only; relocates to lance-graph/crates/cesium when flawless."
7+
8+
# Workspace member via `crates/*`, deliberately NOT in `default-members` →
9+
# optional/dev by construction (a member, never a default build target).
10+
# RULE 3: no serde, no json crates. Prefer ArcGIS PBF (binary) over f=json.
11+
# JSON, if unavoidable at the cold import boundary, never reaches the hotpath.
12+
13+
[dependencies]
14+
# Wired when modules go live (see src/lib.rs). The skeleton is dependency-free
15+
# so it compiles trivially and CI stays green.
16+
# ndarray = { workspace = true } # splat3d::GaussianBatch CAM SoA target + cam_pq
17+
# prost / quick-protobuf = ... # ArcGIS PBF decode (binary, no-JSON) — module `arcgis_pbf`
18+
19+
[features]
20+
default = []
21+
# oracle = [] # gates module `oracle` (reference-render diff harness) once a real reference renderer is wired

‎crates/cesium/src/arcgis_pbf.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `arcgis_pbf` (group B) — ArcGIS FeatureService PBF (binary, the no-JSON path) ingestion
2+
//! Ground against: R-ArcGIS/arcpbf; AdaWorldAPI/arcgisutils; dfridkin/arcGIS-Rust-runtime; EsriDevEvents/locup.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group B; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-B): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/esri_crs.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `esri_crs` (group B) — ESRI_crs WKID (h+v) reproject -> WGS84 / local-origin
2+
//! Ground against: ArcGIS ESRI_crs; AdaWorldAPI/arcgisutils.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group B; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-B): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/fixtures.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `fixtures` (group D) — golden scenes + parity gates
2+
//! Ground against: staehlli/3D-settlement-development.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group D; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-D): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/hlod.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `hlod` (group C) — HLOD tree + refine ADD/REPLACE
2+
//! Ground against: OGC 3D Tiles refine; CesiumGS/cesium HLOD (Apr 2026).
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group C; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-C): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/implicit_tiling.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `implicit_tiling` (group A) — subtree availability bitstreams + Morton/Z-order
2+
//! Ground against: OGC 3D Tiles implicit tiling; CesiumGS/cesium.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group A; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-A): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/khr_gs.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `khr_gs` (group A) — KHR_gaussian_splatting glTF parse (POSITION/ROTATION/SCALE/COLOR_0/SH)
2+
//! Ground against: Khronos KHR_gaussian_splatting; CesiumGS/cesium.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group A; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-A): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/lib.rs‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
//! # cesium — optional Cesium / ArcGIS reference + parity oracle
2+
//!
3+
//! **NOT a production dependency.** This crate is the *runnable legacy pillar*
4+
//! (see `.claude/knowledge/crate-registry.md`, modesty clause): it
5+
//! reverse-engineers external geospatial-splat formats into ndarray CAM SoA and
6+
//! diffs our `splat3d` render against a reference, to keep "parity / better"
7+
//! honest by **measurement**. It is a workspace member but **NOT** in
8+
//! `default-members`, so it is optional/dev by construction. It relocates to
9+
//! `lance-graph/crates/cesium` once flawless.
10+
//!
11+
//! ## Hard rules (from crate-registry.md)
12+
//! - **Reverse-engineer ONLY** — extract data, rebuild as CAM SoA; never depend
13+
//! on, round-trip, or emit the source format. Refactor > reverse-engineer.
14+
//! - **CAM SoA target** — output is ndarray's splat SoA
15+
//! (`splat3d::gaussian::GaussianBatch`) + `cam_pq` codebook indices. No AoS,
16+
//! no source-native structs survive past the import boundary.
17+
//! - **NO JSON IN THE HOTPATH, EVER** — JSON only at the cold import boundary.
18+
//! Prefer the **ArcGIS PBF (protobuf, binary)** path over `f=json`.
19+
//!
20+
//! ## Grounding references (reverse-engineer against these — do NOT fabricate;
21+
//! mark anything you cannot confirm against a source as `// UNVERIFIED:`)
22+
//! - `CesiumGS/cesium` — 3D Tiles / HLOD / KHR_gaussian_splatting behaviour
23+
//! - Khronos `KHR_gaussian_splatting` + `KHR_gaussian_splatting_compression_spz`
24+
//! - `R-ArcGIS/arcpbf`, `AdaWorldAPI/arcgisutils`, `dfridkin/arcGIS-Rust-runtime`,
25+
//! `EsriDevEvents/locup` — ArcGIS FeatureService **PBF** (binary, no-JSON) + `ESRI_crs`
26+
//! - `staehlli/3D-settlement-development` — a real 3DGS scene for fixtures
27+
//! - Inria `.ply` via ndarray `splat3d::ply` — first reference render for the oracle
28+
//!
29+
//! ## Module map (12 slots — `///` commented scaffold ONLY until reviewed live
30+
//! by Opus + CodeRabbit/Codex)
31+
//! | module | group | purpose |
32+
//! |---|---|---|
33+
//! | [`tileset`] | A | 3D Tiles `tileset.json` / `.3tz` parse (cold import) |
34+
//! | [`implicit_tiling`] | A | subtree availability bitstreams + Morton/Z-order |
35+
//! | [`khr_gs`] | A | KHR_gaussian_splatting glTF parse (POSITION/ROTATION/SCALE/COLOR_0/SH_DEGREE_n) |
36+
//! | [`arcgis_pbf`] | B | ArcGIS FeatureService **PBF** ingestion (binary, the no-JSON path) |
37+
//! | [`spz`] | B | `KHR_gaussian_splatting_compression_spz` decode (quantize+gzip) |
38+
//! | [`esri_crs`] | B | `ESRI_crs` WKID (h+v) reproject → WGS84 / local-origin |
39+
//! | [`to_cam_soa`] | C | reverse-engineer parsed splats → CAM SoA (`GaussianBatch` + `cam_pq`) |
40+
//! | [`sse`] | C | screen-space-error LOD selection (`geometricError·viewportH/(dist·2tan(fovy/2))`) |
41+
//! | [`hlod`] | C | HLOD tree + refine ADD·REPLACE |
42+
//! | [`point_fallback`] | D | point-cloud fallback (KHR base extension = point primitives) |
43+
//! | [`oracle`] | D | reference-render invocation + SSIM/PSNR diff vs `splat3d` |
44+
//! | [`fixtures`] | D | golden scenes + parity gates |
45+
46+
pub mod tileset;
47+
pub mod implicit_tiling;
48+
pub mod khr_gs;
49+
pub mod arcgis_pbf;
50+
pub mod spz;
51+
pub mod esri_crs;
52+
pub mod to_cam_soa;
53+
pub mod sse;
54+
pub mod hlod;
55+
pub mod point_fallback;
56+
pub mod oracle;
57+
pub mod fixtures;

‎crates/cesium/src/oracle.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `oracle` (group D) — reference-render invocation + SSIM/PSNR diff vs splat3d
2+
//! Ground against: CesiumGS/cesium render; Inria .ply via splat3d::ply.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group D; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-D): scaffold per src/lib.rs module map + grounding refs above.

‎crates/cesium/src/point_fallback.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//! `point_fallback` (group D) — point-cloud fallback (KHR base extension = point primitives)
2+
//! Ground against: Khronos KHR_gaussian_splatting base ext.
3+
//! Reverse-engineer ONLY → CAM SoA; NO JSON in hotpath (rule 3).
4+
//! `///` commented scaffold to be filled by Sonnet group D; reviewed live by
5+
//! Opus + CodeRabbit/Codex before any impl is uncommented.
6+
7+
// TODO(group-D): scaffold per src/lib.rs module map + grounding refs above.

0 commit comments

Comments
 (0)