Hermes Agent
201 lines
6.4 KiB
Markdown
201 lines
6.4 KiB
Markdown
# 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.
|