TPT-Selenograph

Real-Time Centimeter-Accurate Lunar Digital Twin & Physics Engine

Selenograph ingests petabytes of synthetic sensor data from a robot swarm, fuses it into a continuous, centimeter-accurate 3D voxel mesh, runs a real-time lunar physics solver (structural integrity + seismic events), and streams the result to Earth as a highly compressed, delta-encoded video-like feed for human telepresence.

The project is a simulation / research harness: every subsystem (sensor swarm, distributed cluster, deep-space link) is modelled locally so the whole pipeline can be exercised on a laptop. Swap-in points for real hardware are called out in docs/architecture.md.

Workspace layout

A Cargo workspace of focused crates:

Crate	Responsibility
selenograph-core	Math, constants, config, errors, observability metrics
selenograph-voxel	Lock-free, sharded 3D voxel grid (the spatial DB)
selenograph-sensors	Procedural LiDAR / photogrammetry / GPR generators + robot agents
selenograph-physics	Lunar gravity, regolith coefficients, structural-integrity solver, seismic model
selenograph-compress	Voxel delta-encoding + zstd + simulated deep-space link
selenograph-net	Distributed node simulation: sharding, LWW consistency, failure/recovery
selenograph-render	Marching-cubes meshing, LoD tiers, async pipeline, Bevy renderer
selenograph-viewer	Earth-side telepresence client (decode + reconstruct + render)

Quick start

# Build everything (default features — no GPU / windowing required)
cargo build --workspace

# Run the unit + integration tests
cargo test --workspace

# Headless end-to-end demo: Moon-side streamer -> Earth-side decode
cargo run -p selenograph-viewer -- --serve 127.0.0.1:18500 --frames 120 --robots 4
cargo run -p selenograph-viewer -- --addr 127.0.0.1:18500

Templates & examples

New to the codebase? Start with the heavily-commented, headless examples. The quickstart walks the full pipeline (ingest → mesh → delta → compress → decode) in one small deterministic scene, and each crate ships a minimal "hello world":

# End-to-end pipeline walkthrough, one log line per stage
cargo run -p selenograph-viewer --example quickstart

# Per-crate starters
cargo run -p selenograph-voxel   --example ingest_demo
cargo run -p selenograph-physics --example integrity_demo

Reusable scenario templates (RobotPlan presets such as lawn_mower_survey, seismic_event, wall_collapse_demo) live in selenograph_sensors::presets. Every runnable example — with its exact cargo command — is indexed in the examples cookbook.

Live 3D viewer (needs a display)

cargo run -p selenograph-viewer --features bevy --example bevy_viewer

Controls: left-drag orbit · scroll zoom · W/A/S/D pan · Q/E up/down · O node-partition overlay · P physics-state overlay · B chunk/LoD overlay.

Benchmarks & stress tests

# Confirm only the active area runs full fidelity (LoD)
cargo run -p selenograph-render --example lod_bench

# Simulate a thousands-of-robots data volume
cargo run -p selenograph-viewer --example stress_robots -- --robots 2000 --frames 15

Feature flags

• selenograph-render / selenograph-viewer → bevy: enables the Bevy renderer + windowed viewer. Off by default so CI stays portable and fast.
• selenograph-physics → rapier: swaps the dependency-free rigid-block / slope-stability model for full Rapier3d rigid-body dynamics under lunar gravity.

Key design ideas

• LoD streaming — only geometry near active robots runs full-fidelity physics/render; the bulk of the world stays coarse and static until a robot approaches (see selenograph-render::lod).
• Lock-free spatial DB — chunks are sharded across RwLock-guarded buckets, so concurrent ingest from thousands of sensors scales with cores.
• Delta + zstd downlink — each frame ships only the voxel edits since the last frame, zstd-compressed, over a link that models bandwidth, latency and loss.
• Distributed by simulation — a coordinator + ingest/mesh-query nodes communicate over real loopback TCP with deterministic chunk sharding and last-writer-wins consistency.

See docs/ for the architecture overview, local multi-process run instructions, and the Linux cluster deployment notes.

License

Licensed under either of MIT or Apache-2.0 at your option.