openvistapro/docs/knowledgebase/manual-features.md

# Manual Feature List

A point-by-point inventory of features described in the three PDF manuals in
`manuals/`. This is a faithful extraction of what the legacy manuals document —
not a reconciliation against the OpenVistaPro codebase. For that, see
[feature-inventory.md](./feature-inventory.md).

Source documents:

- **`VistaPro2UserManual.pdf`** — Vista Pro 2 User Manual (Commodore Amiga edition).
- **`VPWGUIDE.PDF`** — Vistapro 3.0 / 3.1 for Windows, User Manual.
- **`MPWGUIDE.PDF`** — MakePath Flight Director for Windows, User Guide.

---

## 1. Vistapro (core program)

Vistapro is a 3-D landscape simulation/rendering program. It renders real
landscapes from USGS Digital Elevation Model (DEM) data and synthetic fractal
landscapes from a seed number. The two manuals describe the same program on two
platforms (Amiga = v2, Windows = v3); features below are merged, with
platform-specific items marked.

### 1.1 Terrain data sources

- Render real-world terrain from USGS DEM (Digital Elevation Model) files at
  ~30 m resolution.
- Generate fractal landscapes from a seed number — over 4 billion distinct
  landscapes addressable.
- Landscape sizes: **Small** (258×258, ~65k points / 130k polygons), **Large**
  (514×514), **Huge** (1026×1026, ~1M points / 2M+ polygons), **Mega**
  (2050×2050, Windows v3 only).
- **Automatic** landscape size — sizes the topographic map to match the next
  DEM loaded.
- Load multiple contiguous "X-series" DEM tiles into one Large/Huge/Mega region
  (**Load Region** / DEM Region, with Manual or Auto placement).
- **Load Binary** — import raw signed 16-bit integer elevation grids (any 2-D
  integer array up to 1024×1024 can be visualized).
- Edit/store landscape name and comments in the DEM file header; fractal
  settings are saved in the header for regeneration.

### 1.2 Camera and target

- **Camera** and **Target** placement by clicking the topographic map or by
  typing X/Y/Z coordinates directly.
- Camera Z auto-set 30 m above terrain when placed by mouse.
- **X / Y / Z locks** — constrain camera/target movement on individual axes.
- **dR / dX / dY / dZ** — camera-to-target distance and per-axis offsets,
  directly editable.
- **Bank / Head / Pitch** — camera orientation (roll, heading, pitch) angles.
- **Range** — clip rendering beyond (positive value) or closer than (negative
  value) a distance from the camera.
- **P (wire-frame perspective view)** — preview what the camera sees as a wire
  frame; click to re-aim, arrow keys to zoom.

### 1.3 Camera lens

- **Wide** lens (90° field of view, focal length 16) and **Zoom** lens (~45°,
  focal length 32).
- **FclLn** — arbitrary focal length value (1–30000); lower = wider, higher =
  more magnification.
- **Port / Starboard / Forward** lens modes — render three 90° panorama
  segments designed for a three-monitor setup.
- **Left / Right** lens offsets, **CamSep** (camera separation) and **ImgSep**
  (image separation) — stereoscopic image-pair rendering.

### 1.4 Terrain feature controls

- **SeaLvl** — set sea level; floods/sinks terrain, optionally adds ocean waves.
- **TreeLn** — timber line: elevation above which trees do not grow ("fuzzy",
  AI-adjusted for cliffs, ridges, valleys).
- **SnowLn** — snow line: lowest elevation covered with snow (AI-adjusted).
- **HazeDn** — atmospheric haze density; auto-computed from camera/target
  distance or set manually.
- **Lake** — fill a basin with water from a clicked elevation point.
- **River** — generate a river that flows downhill, fills depressions into
  ponds/lakes, widens when overlapped, and stops at sea level or map edge.
- **Stars** — render a randomly generated star field in the night sky
  (optional double-width / double-height stars).
- **Sky** — toggle sky rendering.
- **Horizn** — toggle the distant horizon disk.
- **Tree** — open the Tree Control Panel and enable rendered trees.
- **Valley** (Windows v3) — control how far trees climb valley bottoms and snow
  reaches into valleys; used by Stretch.
- **Cliffs** (Windows v3) — slope threshold above which terrain uses cliff
  colors.
- **Clouds** (Windows v3) — open the Cloud Control Panel and enable clouds.

### 1.5 Terrain editing / transformation

- **VScale** — vertical re-scaling; values >1 exaggerate, 0–1 flatten, negative
  flips the terrain (special effects: calderas, stepped peaks).
- **Enlarg** — blow up a sub-region to fill the whole topographic map, with
  **Interpolate** (averaged) or **Duplicate** (stepped) infill.
- **Shrink** (Windows v3) — reduce Large/Huge landscapes to the next size down.
- **Smooth** — erode/smooth jagged terrain (repeatable); useful for fractal
  terrain and snow-capped peaks.
- **Frctlz / Fractalize** — add fractal detail/roughness to existing terrain.
- **Strtch / Stretch** — vertically exaggerate existing features (peaks taller,
  valleys deeper) at a scale set by the fractal divisor.
- **Random** fractal generation, with **Island** vs **Floating** edge modes,
  **FrDim** (fractal dimension/roughness), **Fractal Divisor** (1/2/4/8 feature
  scale), and the **Fractal Landscape Number** seed gadget.
- `SetAltitude` script command — directly modify the elevation of a single
  terrain point.

### 1.6 Rendering controls

- **Render** — generate the image; **ReDraw** — redraw last image; **View** —
  redisplay last image.
- **Poly** size 1 / 2 / 4 / 8 — polygon coarseness vs. render speed tradeoff.
- **Dither** — fuzziness of the boundaries between elevation color bands.
- **Texture** — Off / Low / Medium / High artificial detail, in two modes:
  **Shading texture** (split polys, shaded separately) and **Altitude texture**
  (fractalized polys for photo-realistic detail).
- **PixDth / PDithr** — pixel-level dithering (Ordered or Random) to simulate
  more colors.
- **Bound** — restrict rendering to a marked rectangular sub-region.
- **BFCull** — back-face culling toggle.
- **Blend** — average each polygon's color with its neighbors to reduce
  distant aliasing.
- **GShade** — Gouraud shading for smooth, painterly surfaces.
- **Range**-based culling for fast script test renders (see 1.2).

### 1.7 Lighting

- **N / S / E / W** quick light directions (sun 45° above horizon).
- **Custom** light direction/angle set by clicking the topographic map.
- **Azimuth** and **Declin** (declination) numeric light controls.
- **Exager** — exaggerated shading to bring out small terrain irregularities.
- **Rough** — adds random per-polygon shading variation for surface roughness.
- **Shadow** — cast terrain shadows from the sun direction (terrain only; trees
  cast no shadows).

### 1.8 Trees (Tree Control Panel)

- Four tree types: **Pine, Oak, Palm, Cactus**; assignable per elevation zone
  (Tree1–Tree4) or to **All** zones.
- Per-zone **Size** and **Density** (out of 256); **Mean Size** / **Mean
  Density** to set all zones at once.
- 3-D detail levels: **Low / Medium / High / Ultra** (controls branch/leaf
  levels); no detail level = 2-D trees.
- **Leaves** toggle (leafless trees for autumn/winter).
- **Texture** — fractal texturing on branches and leaves.
- When no tree type is selected, "under-tree" colors (–Tree1–4) color the
  ground instead.

### 1.9 Clouds (Cloud Control Panel, Windows v3)

- **Fractal Detail** — add fractal detail for realistic clouds.
- **Density** (0–100), **Hardness** (fluffiness), **Altitude**, and **Cloud
  Size** (S / M / L / X).
- **Generate Clouds** — random fractal cloud map (seedable via `CloudNumber`).
- **DEM → Clouds** — turn the current landscape into a cloud pattern (peaks
  become clouds); enables "sky writing" from a text PCX-derived DEM.
- Save/load cloud maps (`.CLD`).

### 1.10 Colors (Color Control Panel)

- RGB and HSV (Hue/Saturation/Value) sliders for mixing colors.
- Editable color families: **Sky, Snow 1–4, Bare 1–4, –Tree 1–4, Horizon,
  Cliff 1–4, Water 1–5, Beach, Tree 1–4, Bark 1–4, SkyHaze, Haze, House 1–4,
  –House 1–4**.
- **Exposure** and **Contrast** controls.
- **Copy**, **Swap**, and **Spread** (smooth gradient between two colors)
  palette operations.
- Save / load **ColorMap** files independently of the terrain.
- **Sound** option (Amiga v2 color panel).

### 1.11 Palette controls

- **NumClr** — limit Vistapro to fewer than 256 colors, reserving the rest.
- **RGBPal** — compute a palette from the colors actually in a 24-bit image.
- **LckPal / LockPalette** — lock the palette so it is reused across frames
  (needed for VANIM animations).
- **Load Palette** — render using the palette from an external PCX file.

### 1.12 Image / display

- Image sizes from tiny (16×10 / 80×50) up to **4096×4096**, plus a Custom size.
- **Enable 24 bit** internal buffer for true-color (16M color) output.
- **Render Viewing Options** (Windows v3): view rendering in real time, every
  N seconds, or only on completion (progress bar).
- Amiga display modes (v2): **Low Res** (32 colors), **HalfBrite** (64 colors),
  **Hi Res** (16 colors), **HAM** (4096 colors), **DCTV**, **HAM-E**,
  **Interlace**, **Overscan** (704/736/768), **Firecracker24** display board
  (1- or 2-monitor).
- **Background** image — load a 24-bit image drawn behind the landscape (e.g.
  a sky); **Foreground** image — overlay (black pixels treated as transparent,
  e.g. a cockpit/dashboard).

### 1.13 File formats

- **Landscapes:** Vistapro DEM, binary, ASCII-Z (MathCAD-style text export,
  Windows v3), Extended/Session DEM (saves DEM + every program setting for
  resuming aborted animations).
- **Images:** PCX, Targa24 (TGA), BMP24 (Windows); IFF, IFF24, RGB
  (Sculpt-Animate/Mimetics framebuffer triplets, Amiga).
- **3-D export:** DXF polyface mesh and Targa24 **texture maps** for 3D Studio
  integration (Windows v3); **Turbo Silver** object export (Amiga v2).
- **Stereo:** **Load Stereo** merges a left/right Targa24 pair into a red/blue
  anaglyph image.
- ColorMap and cloud-map (`.CLD`) files.

### 1.14 Import / convert (ExpImp / Property menu)

- **DEM ↔ PCX** — save the topographic map as a PCX contour image and reload it;
  enables painting elevations between digitized contour lines.
- **Col ↔ PCX** — export/import Vistapro's internal polygon color (terrain
  type) table; lets you hand-place trees, rivers, cliffs, **houses**, etc. in a
  paint program.
- **View → DEM / Alt** — convert the rendered image into elevation data
  (Intensity or Color mode).
- **View → Col** — convert the rendered image into the internal color table.
- **View → RGB** — convert the rendered image into the 24-bit buffer (used to
  build background/foreground images).
- Map a satellite image or arbitrary picture onto the terrain via PCX → Col in
  color mode.

### 1.15 Scripting and animation

- **Scripts** are landscape-independent lists of camera/target positions, used
  mainly for animations and reusable across landscapes.
- **Generate** — quick straight-line camera→target path of N frames.
- **Create / Open / Add** — build a script by appending current camera/target
  positions.
- **Preview** — show the script path on the topographic map in 2-D dots or 3-D
  wire frame.
- **Run / Execute** — render every frame; output as **Run Targa24 / Run BMP24 /
  Run PCX / Run VAN** (Windows) or IFF / IFF24 / RGB / VANIM (Amiga).
- Aborting and continuing (appending to) a partially rendered animation.
- **Batch files** — run a DOS batch file after each rendered frame.
- **VANIM** (`.VAN`) proprietary animation format — disk-streamed playback,
  per-frame palette, forward/reverse/step playback; played by the bundled
  **Animation Viewer**.
- Full **Vistapro Script Language** (Windows v3): ~100+ text commands covering
  camera/target, colors (`SetColor*`), trees, clouds, lighting, sea/tree/snow
  lines, fractal generation, texture/shading, image size, GrMode, default
  directories, `Render`, `RewriteImage`, `Spawn` (run external programs),
  `Smooth`, `Stretch`, `Enlarge`, `MakeLake`, `MakeRiver`, `SetAltitude`, etc.
- **ARexx** interface for all script functions (Amiga v2).
- **Quality** menu (Windows v3) — Low / Medium / High / Ultra / User presets
  implemented as editable scripts in the `IQ` directory.

### 1.16 3D Studio integration (Windows v3)

- **Method 1** — export terrain as DXF + Vistapro-generated texture map; 3DS
  renders everything.
- **Method 2** — export DEM as a DXF "matte" object; Vistapro renders the
  landscape background and 3DS renders objects composited over it.
- `VUE2SCR` utility — convert 3D Studio camera VUE files into Vistapro scripts.

### 1.17 Bundled utilities

- **Animation Viewer** — plays VANIM (`.VAN`) files.
- **AVI Builder** (Windows v3) — assembles PCX/TGA/BMP frame sequences into AVI.
- Image **print** utility (Windows v3 prints PCX/TGA/BMP24; Amiga v2 prints the
  View screen directly).

### 1.18 Status / workflow aids

- Live topographic map colored by elevation (green low → brown mid →
  gray-white high).
- Status window showing pointer X/Y/Z and the current render phase
  (Generate, Color, Cliffs, Shade, Tree, Sky, Horizon, Render).
- **About Vistapro / About DEM / About Image** info panels (image polygon
  count and render time).
- Abort any long operation with Esc or the right mouse button.

---

## 2. MakePath Flight Director

MakePath is a companion animation-path tool for Vistapro. It turns a few
control points into a smooth flight path and exports it as a Vistapro script.

### 2.1 Path creation

- Load any Vistapro DEM into a topographic map (same map style as Vistapro).
- Place **spline nodes** by clicking the map; the path is a smooth spline curve
  through them (minimum four nodes).
- **MakePath** button — generate the smooth spline path from the current nodes
  and motion settings.
- Spline curve type: **Bezier** (passes through nodes) or **BSpline** (smoother,
  does not pass through nodes) via the **Use BSpline** option.
- **New Path** — clear nodes and path.

### 2.2 Node editing

- **Add Node** — insert a node between the nearest two, or append to an end.
- **Delete Node** — remove a node.
- Move a node by grabbing it with the mouse (lines rubber-band; right-click
  aborts).
- **Edit Node** — numerically edit a node's X/Y/Z coordinates and its target;
  step between nodes with Next/Previous.
- **Set Target / Unset Target** — attach (or remove) a look-at target point to a
  node so the camera watches it while passing.
- Adjust node altitude in the **Altitude Profile** view.

### 2.3 Motion controls

- **Fly** vs **Drive** — air vehicle (ignores ground contour) vs land vehicle
  (follows the ground).
- **Frames** vs **Speed** — generate a fixed number of frames, or as many as
  needed to hold a given speed (km/h at 30 fps).
- **Smooth** — reduce how closely the path follows rugged terrain.
- **Loop** — close the path back to the first node for continuous looping.
- **Bank** — bank into turns (positive, plane-like) or out of turns (negative,
  car-like).
- **Accel** — speed up on descents, slow on climbs.
- **Pitch** — pitch up on climbs / down on descents, plus a constant pitch
  offset (e.g. –90° for a straight-down "glass bottom boat" view).
- **Height** — altitude of each node above the ground beneath it.
- **MinHgt** — minimum ground clearance for the path / ride height for ground
  vehicles.
- **Avoid Collisions** — keep flying vehicles above the terrain (can be
  disabled to fly through obstacles).

### 2.4 Vehicle motion models

Predefined parameter sets selectable from the Models menu:

- **Glider, Jet, Cruise Missile, Helicopter, Dune Buggy, Motorcycle** — and any
  custom combination of the controls above.

### 2.5 Special path options

- **Add Barrel Roll** — add a roll over a chosen number of frames, clockwise or
  counter-clockwise.
- **Make Spin Path** — circular path orbiting the landscape with the camera
  fixed on its center (diameter set as a percentage of landscape size).

### 2.6 Preview

- **ViewPath** — wire-frame animation preview of the whole path.
- **ViewFrame** — wire-frame preview of a single frame.
- Animation controls (numeric keypad): step ±1 / ±10 frames, first/last frame,
  freeze, play forward/backward.
- **View Options / Preview Controls** — preview **Area Size** (Tiny→Huge,
  trading detail for constant speed), **Lens** (Wide/Medium/Zoom), and **Frame
  Speed** (Fast 18 fps / Medium 9 fps / Slow 6 fps).
- **Show Crosshairs** — toggle the on-map position crosshairs.

### 2.7 Altitude Profile

- Side-profile view of node and camera altitudes (red) against the terrain
  beneath the path (brown).
- Adjustable vertical scale (+ / = / –); horizontal slider to scroll long paths.
- Edit node altitude directly in the profile; small "wings" indicator shows
  bank.

### 2.8 Files

- **Save Script** — export the path as a Vistapro script for rendering.
- **Save Session / Load Session** — save/restore the full MakePath editing
  state (nodes, settings, and the associated landscape reference).
- **Load DEM** — load a landscape.

---

## 3. Cross-cutting notes

- Vistapro v2 (Amiga) and v3 (Windows) share the same core feature set; v3 adds
  Mega landscapes, Valley/Cliffs/Clouds controls, the Quality menu, the full
  scripting language, 3D Studio integration, stereoscopic anaglyph output, and
  Windows image formats. v2 adds Amiga display hardware modes and Turbo Silver
  export.
- Both Vistapro and MakePath emphasize the same workflow: rough fast preview
  (large polygons, low detail) → tune camera, lighting, and feature lines →
  full-detail final render.