openvistapro/docs/plans/initial-roadmap.md

OpenVistaPro Implementation Plan

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: Build a Rust terrain visualization application inspired by VistaPro, starting with a testable command-line terrain renderer and growing toward a modern interactive UI.

Architecture: Start with a monolithic Rust crate containing terrain, scene, colormap, script, and CPU rendering modules. Split into workspace crates after APIs stabilize. Keep all historical compatibility code isolated from the clean internal data model.

Tech Stack: Rust, cargo, serde, image, clap, glam/nalgebra, optional future wgpu/winit/egui.

---

Phase 0: Project hygiene and research base

Task 1: Keep reference materials local-only

Objective: Ensure proprietary archives, ISO images, PDFs, screenshots, extracted files, and scratch output are not committed.

Files:

• Modify: .gitignore
• Create: docs/legal/asset-policy.md
• Create: docs/research/reference-inventory.md

Verification:

Run: git status --short --ignored Expected: reference/ and .work/ are ignored; docs and source files are visible.

Task 2: Maintain the knowledgebase

Objective: Convert observations from manuals/screenshots/public pages into project-owned notes.

Files:

• Create/modify: docs/knowledgebase/*.md

Verification:

Run: grep -R "TODO\|TBD" docs/knowledgebase docs/plans || true Expected: only intentional open questions remain.

Phase 1: Minimal terrain core

Task 3: Add HeightGrid

Objective: Represent a rectangular heightfield with dimensions, samples, min/max elevation, and safe indexing.

Files:

• Create: src/terrain.rs
• Modify: src/main.rs
• Test: unit tests inside src/terrain.rs

Implementation notes:

• Use Vec<f32> row-major storage.
• Provide new(width, height, samples) -> Result<HeightGrid, TerrainError>.
• Provide sample(x, y) -> Option<f32>.
• Provide min_max() -> Option<(f32, f32)>.

Verification:

Run: cargo test terrain Expected: all terrain unit tests pass.

Task 4: Add synthetic terrain generation

Objective: Generate deterministic test terrain without any proprietary data.

Files:

• Modify: src/terrain.rs

Implementation notes:

• Add HeightGrid::plane(width, height).
• Add HeightGrid::radial_hill(width, height, peak_height).
• Keep outputs deterministic for snapshot tests.

Verification:

Run: cargo test terrain Expected: deterministic dimensions and min/max assertions pass.

Phase 2: Scene model and CLI

Task 5: Add scene configuration structs

Objective: Represent camera, target, light, water, snow/tree/haze controls in Rust data structures.

Files:

• Create: src/scene.rs
• Modify: src/main.rs

Implementation notes:

• Keep fields close to VistaPro concepts but use modern names.
• Derive Debug, Clone, Serialize, and Deserialize after adding serde.

Verification:

Run: cargo test scene Expected: default scene values are valid.

Task 6: Add a CLI skeleton

Objective: Provide openvistapro render --preset hill --output out.png as the first user-facing workflow.

Files:

• Modify: Cargo.toml
• Modify: src/main.rs

Implementation notes:

• Add clap dependency.
• Subcommands: info, render.
• info prints build/version and supported importers.

Verification:

Run: cargo run -- info Expected: prints OpenVistaPro version and feature list.

Phase 3: CPU reference renderer

Task 7: Add colormap module

Objective: Map elevation and scene thresholds to RGB colors.

Files:

• Create: src/colormap.rs

Implementation notes:

• Start with a simple gradient: water, lowland, highland, snow.
• Add tests around threshold behavior.

Verification:

Run: cargo test colormap Expected: threshold tests pass.

Task 8: Render top-down preview PNG

Objective: Create a deterministic topographic/elevation preview image.

Files:

• Create: src/render.rs
• Modify: Cargo.toml
• Modify: src/main.rs

Implementation notes:

• Use the image crate.
• Render one pixel per height sample initially.
• Save PNG.

Verification:

Run: cargo run -- render --preset hill --output /tmp/openvistapro-hill.png Expected: PNG is created and has expected dimensions.

Task 9: Add simple perspective renderer spike

Objective: Produce a rough VistaPro-like perspective terrain image for architecture validation.

Files:

• Modify: src/render.rs

Implementation notes:

• Start with a CPU raymarch or projected grid approach.
• Prefer correctness/readability over performance.
• Document limitations.
• Initial implementation uses --camera-demo to select a deterministic, spike-quality CPU raymarcher with a fixed demo camera, fixed step size, bilinear height sampling, sky gradient, and distance haze. Current limitations: no shadows, no surface normals/lighting, no adaptive stepping, and no UI camera controls yet.

Verification:

Run: cargo run -- render --preset hill --camera-demo --output /tmp/openvistapro-perspective.png Expected: image is created; no panic for reasonable scene defaults.

Phase 4: Formats, scripts, UI

• Add open DEM/HGT/GeoTIFF importers behind feature flags.
  • Current importer surface: project-owned ovp-text fixtures, script-level PNG heightmap input, feature-gated SRTM/HGT byte parsing, and feature-gated ESRI ASCII Grid parsing.
  • GeoTIFF remains a strategy/research item until a separate feature slice chooses a dependency boundary.
• Define OpenVistaPro scene file format.
  • Initial implementation: .ovp.toml files with schema = "openvistapro.scene", version = 1, and a serialized Scene payload. CLI support starts with openvistapro scene export --output scene.ovp.toml and openvistapro render --preset hill --scene scene.ovp.toml --output out.png.
• Implement a VistaPro-inspired script language and executor.
  • Current CLI: openvistapro script run --input examples/demo.ovps.
  • The syntax is project-owned and not legacy VistaPro-compatible.
• Add a MakePath-like spline path generator.
  • Current module: src/path.rs with deterministic keyframe interpolation used as a foundation for future animation output.
• Build an interactive app with WGPU and egui after CLI renderer is stable.
  • Current app shell: cargo run --features app --bin openvistapro_app; it uses eframe/egui scene controls and a CPU terrain preview while full WGPU terrain rendering remains future work.