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/terrain_gen.rs: TerrainGenerationSpec, TerrainGenerationSettings, and DeterministicTerrainGenerator for the seeded terrain-generation pipeline; cargo test terrain_gen exercises the determinism/seed note and the first shipped fractal preset.
• 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 legacy file compatibility is out of scope for the current clean-room pipeline; the supported export surfaces are project-owned .ovp.toml scenes and PNG renders. Any future compatibility work needs a separately reviewed plan.