openvistapro/docs/knowledgebase/architecture-notes.md

Architecture Notes

Current Rust module structure

Start simple, then split into crates when module boundaries stabilize.

• src/terrain.rs: height grid, bounds, sampling, and deterministic terrain fixtures.
• src/import.rs: importers for open/safe formats (ovp-text, feature-gated HGT, feature-gated ESRI ASCII Grid, and feature-gated GeoTIFF via src/import/geotiff.rs); historical compatibility later. Each importer yields the same internal HeightGrid plus TerrainSourceMetadata, keeping source formats out of renderer code.
• src/scene.rs and src/scene_file.rs: camera, light, atmosphere, water/vegetation thresholds, and .ovp.toml persistence.
• src/render.rs: deterministic CPU top-down renderer plus CPU perspective demo renderer; WGPU renderer later.
• src/script.rs and src/script_exec.rs: parse and execute project-owned OpenVistaPro script commands.
• src/path.rs: MakePath-inspired camera keyframe interpolation.
• src/colormap.rs: palettes and elevation/biome color mapping.
• src/cli.rs plus src/main.rs: CLI entry point for info, scene export, render, and script run.
• src/app_state.rs, src/app.rs, and src/bin/openvistapro_app.rs: optional app feature shell built with eframe/egui.

Suggested technology choices

• Rust 2021 or newer.
• clap for CLI.
• serde plus ron/toml/serde_json for scene files.
• image for PNG output and texture loading.
• nalgebra or glam for vector/matrix math.
• wgpu plus winit/egui for the eventual interactive app.
• GeoTIFF support uses the pure-Rust geotiff-reader crate behind the optional import-geotiff feature, so default builds stay free of native dependencies. gdal is intentionally not used; any future GDAL-backed path would be a separate, opt-in feature because native GDAL setup can be heavy.

Development strategy

1. Build a deterministic CPU terrain renderer as a reference implementation.
2. Add parsers/importers around open formats using tiny test fixtures.
3. Add a scriptable CLI so CI can verify output dimensions/hashes/metadata.
4. Add interactive UI only after terrain/scene/render core is testable.
5. Add GPU renderer and advanced effects once CPU behavior is understood.

Compatibility strategy

OpenVistaPro should preserve workflow concepts first. Direct compatibility with old file formats can be added later only when it can be done cleanly and legally.