openvistapro/docs/knowledgebase/architecture-notes.md

Architecture Notes

Proposed Rust workspace structure

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

• src/terrain.rs: height grid, bounds, sampling, normals, terrain transforms.
• src/import/: importers for open/safe formats; historical compatibility later.
• src/scene.rs: camera, target, light, atmosphere, water, vegetation parameters.
• src/render/: CPU reference renderer first, then WGPU renderer.
• src/script.rs: parse and execute OpenVistaPro script commands.
• src/colormap.rs: palettes and elevation/biome color mapping.
• src/bin/openvistapro.rs or current src/main.rs: CLI entry point.

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.
• gdal support should be optional because native GDAL dependency 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.