openvistapro/README.md

# OpenVistaPro

OpenVistaPro is an early-stage, open-source Rust project to build a modern landscape generator inspired by classic VistaPro.

The goal is not to redistribute or reuse proprietary VistaPro code/assets. The local `reference/` directory is intentionally ignored by git and is used only for historical/product research.

## Current status

This repository currently contains:

- A Rust binary crate scaffold.
- A first-pass knowledgebase under `docs/knowledgebase/`.
- An implementation roadmap under `docs/plans/`.
- Legal and reference-material hygiene notes under `docs/legal/` and `docs/research/`.
- A clean-room terrain import boundary with project-owned `ovp-text` fixtures, a PNG heightmap script importer, an SRTM/HGT byte importer behind the `hgt` Cargo feature, an ESRI ASCII Grid parser behind the `ascii-grid-import` feature, a narrow GeoTIFF importer behind `import-geotiff`, and a deterministic terrain-generation module in `src/terrain_gen.rs` with `TerrainGenerationSpec` / `TerrainGenerationSettings` / `DeterministicTerrainGenerator` (see `cargo test terrain_gen` and its determinism/seed note). The UI shell and CLI both expose a seeded `fractal` preset alongside the legacy `plane` and `hill` fixtures.
- A project-owned script parser + executor in `src/script.rs` / `src/script_exec.rs`, MakePath-inspired camera path generation in `src/path.rs`, a project-owned color-map model with editable thresholds/bands in `src/scene.rs`, a light model with azimuth/elevation/intensity controls, and an `app` feature shell with top-level menus, about/help dialog surfacing, and working import/script/path/project/lighting controls in `src/app_state.rs`, `src/app.rs`, and `src/ui_shell.rs`.

## Development

```bash
cargo build
cargo test
cargo run -- info
cargo run -- scene export --output /tmp/openvistapro-default.ovp.toml
cargo run -- render --preset hill --width 256 --height 256 --output /tmp/openvistapro-hill.png
cargo run -- render --preset fractal --seed 1337 --width 256 --height 256 --output /tmp/openvistapro-fractal.png
cargo run -- render --preset hill --scene /tmp/openvistapro-default.ovp.toml --width 256 --height 256 --output /tmp/openvistapro-hill-from-scene.png
cargo run -- render --preset hill --camera-demo --width 256 --height 192 --output /tmp/openvistapro-perspective.png
cargo run -- render --preset hill --quality final --output /tmp/openvistapro-renders/
cargo run --features app --bin openvistapro_app
```

The crate’s default `cargo run` target is the CLI binary (`openvistapro`), so the commands above work without an extra `--bin` flag. Use `--features app --bin openvistapro_app` for the optional GUI shell.

The optional app shell is gated behind the `app` feature so default CLI builds stay GPU-free.
It opens an `eframe`/`egui` window titled `OpenVistaPro` with scene controls, top-level menus/dialogs, and a CPU-rendered terrain preview.
The native shell uses eframe's Glow renderer under X11/Xvfb, which keeps the app smoke launch independent of WGPU backend feature selection.

Importer status:

- `heightmap`: project-owned script input that imports grayscale PNG heightmaps with `import heightmap "path.png"` and maps brightness to elevation. This is a terrain-ingest convenience path, not a legacy VistaPro compatibility claim.
- `ovp-text`: project-owned plain-text heightfield fixture format used for import-boundary tests.
- `hgt`: enabled by the optional `hgt` Cargo feature; parses SRTM HGT payloads as square grids of big-endian signed 16-bit metre samples. The implementation and tests use open specifications and synthetic/tiny fixtures only.
- `esri-ascii-grid`: enabled by the optional `ascii-grid-import` Cargo feature; parses open ESRI ASCII Grid text with synthetic/project-owned fixtures only.
- `geotiff`: enabled by the optional `import-geotiff` Cargo feature; parses single-band GeoTIFF elevation tiles in memory via the pure-Rust `geotiff-reader` crate (no GDAL, no native dependency). It supports a deliberately narrow subset — a single-band raster decoded as `f32` — and is reported by `openvistapro info` only when the feature is built.

These importers all terminate at the same internal `HeightGrid` model. Legacy VistaPro landscape/image compatibility is intentionally out of scope for the clean-room project unless it returns as a separately reviewed compatibility plan.

All importer tests use tiny synthetic, project-owned fixture data: HGT uses inline synthetic byte arrays, ESRI ASCII Grid uses tiny project-owned text fixtures, and the GeoTIFF tests generate a tiny single-band tile in memory rather than reading committed binaries or real geodata.

To verify the importer feature surface:

```bash
cargo test import
cargo test hgt
cargo test hgt --features hgt
cargo test ascii_grid --features ascii-grid-import
cargo run --features hgt --bin openvistapro -- info
cargo run --features ascii-grid-import --bin openvistapro -- info
cargo test --no-default-features
cargo test geotiff --features import-geotiff
cargo run --features import-geotiff --bin openvistapro -- info
cargo test --all-features
```

The default `render` mode writes a deterministic top-down elevation preview.
Passing `--quality preview|balanced|final` selects the project-owned quality profile; if `--output` points to an existing directory, the renderer derives a quality-specific PNG name there.
Passing `--camera-demo` switches to the current CPU perspective renderer spike:
a simple pinhole-camera raymarcher with bilinear height sampling, fixed step
size, sky gradient, and distance haze. It is intended as a readable reference
renderer for architecture validation, not a performance target or final visual
model.

Scene files use the project-owned `.ovp.toml` format. Version 1 stores a
top-level `schema = "openvistapro.scene"`, `version = 1`, and a serialized
`Scene` payload containing camera position/target, camera heading-pitch-bank,
lens/FOV/clip ranges, light direction plus the UI-facing azimuth/elevation
controls, water, tree-line, snow-line, haze, and hydrology overlays/settings.
The format is intentionally human-readable while the data model is still evolving.

## Script language (MVP)

OpenVistaPro includes a small, line-oriented scripting language for driving
terrain and render jobs from a plain-text file (`src/script.rs`). The grammar
is **clean-room and project-owned**: it is **not VistaPro-compatible** and
deliberately does not mirror the legacy VistaPro scripting syntax. Its only
terrain-ingest command today is `import heightmap`, which loads grayscale PNG
input for the project-owned clean-room pipeline.

Each line is a blank line, a `#` comment (also usable as a trailing comment),
or one command:

```text
use preset fractal                          # `fractal`, `hill`, or `plane`
set thresholds water=0.18 tree=0.42 snow=0.77
import heightmap "data/demo-height.png"      # optional grayscale PNG terrain input
render output "out/demo.png"
```

Run the checked-in demo script with:

```bash
cargo run --bin openvistapro -- script run --input examples/demo.ovps
```

Script paths are resolved relative to the script file. `use preset` and
`import heightmap` select the active terrain; `use preset fractal` (or the CLI
`--preset fractal --seed ...`) drives the seeded procedural generator, `set thresholds` updates scene
bands, and execution writes each `render output` to a deterministic PNG.

## Project principles

- Clean-room implementation: do not decompile, copy, or translate proprietary binaries.
- Use open data formats and openly licensed datasets.
- Preserve the spirit/workflow of VistaPro while designing a modern UX and renderer.
- Start with a small, testable terrain engine before building advanced rendering or UI.