# Where terrain implementation lives

Updated 2026-10-03. The explorer is a consumer of portable kernels, not the
location for the only copy of a new regional scientific algorithm.

| Responsibility | Source of truth | Browser consumer | Engine availability |
|---|---|---|---|
| Slope/aspect/basic curvature/TPI/TRI | `products/sdk/folia-compute/src/terrain_ops.rs` | Small WASM bridge and matching GLSL/WGSL definitions | Existing registered operations |
| Principal/tangential curvature and vector contours | `products/sdk/folia-compute/src/terrain_geometry_ops.rs` | Styles 37–39 in GLSL/WGSL/WASM; regional segment export | Public Rust kernels; new recipe operation registration remains tracked |
| TWI/SPI/HAND | `products/sdk/folia-compute/src/terrain_indices_ops.rs` | Regional WASM worker using connected routes | Public Rust kernels; new recipe operation registration remains tracked |
| Observer visibility | `products/sdk/folia-compute/src/terrain_visibility_ops.rs` | Regional WASM viewshed | Existing `folia-engine/src/viewshed.rs` adapter calls this same kernel |
| Solar position | `products/sdk/folia-compute/src/terrain_solar_position.rs` | Point probe via WASM | Existing `folia-engine/src/solar_shade.rs` reexports this unchanged kernel |
| Solar energy/sunshine and shelter/dominance | `products/sdk/folia-compute/src/terrain_exposure_ops.rs` | Explicit regional point probe | Public Rust kernels; new recipe operation registration remains tracked |
| Horizon bins | `products/sdk/folia-compute/src/horizon_ops.rs` | Native helper/WASM, plus browser GPU-bin approximation | Existing horizon operations |
| True least-cost breaching | `products/sdk/folia-engine/src/bridged_hydrology.rs` → pinned vendored tool | Native demo adapter; browser-only deployments cannot run it | Existing registered engine operation; do not confuse the old compute function named `breach_depressions` with carving—it fills |
| Regional flat routing and outlet provenance | `terrain-region-algorithms.js` | Regional worker | Demo-only deterministic routing pass; migration into a reusable canonical Rust operation remains tracked |
| Browser display math/palettes | `terrain-display.js`, `terrain-palettes.js` | Shared coloring/legends and benchmark encoder | Presentation math; not a scientific raster operation |

Paths in the browser column are under `demos/fort-huger-terrain/`.

## Execution paths

`gpu-terrain.html` draws native downloaded terrain tiles. Local derivatives run
in WebGL2; supported layers can instead calculate with WebGPU or canonical Folia
WASM. `terrain-derivatives.js` contains GLSL sources and measure metadata;
`terrain-analysis.wgsl` is the WebGPU compute source. WebGL2 does not run WGSL.
The matching implementations use shared conventions and are checked against
manufactured surfaces. The native wgpu example executes the exact same WGSL
source, rather than maintaining a second native shader.

`terrain-regional-explorer.js` brings connected-region tools into the main layer
browser. Selecting a hydrology tool automatically downloads a connected 2×2
domain around the map center. Navigation updates it after a short debounce;
locking the area preserves its footprint. Display uses four native 512×512 PNG
tiles through an in-memory raster protocol: these are exact crops of the
1024×1024 colored result, with no resizing or analysis downsampling. Two PNG
revisions are retained. Source zoom stays fixed independently
of display zoom, with snap and view-at-analysis-zoom controls. Results remain
visible while replacing the region; obsolete downloads and workers are cancelled.
Viewshed and exposure tools use click/drag observer placement. Conditioning
(Fill/Breach) is a hydrology setting rather than a separate map page. A wide
viewport can exceed the bounded footprint; the outline remains explicit.

The standalone `terrain-region.html` retains explicit analysis controls, calls Folia
filling through WASM, then performs bounded plateau routing in its worker.
TWI/SPI/HAND use those connected routes. Threshold and slope-floor changes reuse
cached original elevation, direction and accumulation arrays. Viewsheds use
original elevations and explicit eye/target heights, distance and refraction.

`gpu-horizon-wasm/src/lib.rs` is the small browser ABI adapter. It validates shape
and resource limits, calls Rust kernels, and packs returned arrays. It is not the
full Folia engine, catalog resolver or recipe executor. SDK kernels are available
to native Rust callers, but a public kernel alone does not register an engine
recipe operation or Python/handle binding.

The solar/shelter/dominance UI is a **point probe**, not a map-wide raster layer.
It uses a local 32-bin horizon, a Horn surface normal, shared NOAA/Meeus geometric
solar position, 48 UTC-day midpoint samples, and explicit constant daytime fluxes.
Sunshine resolution is 0.5 hour. Diffuse light uses an isotropic sky quadrature.
It excludes weather, reflected ground light and terrain beyond the search radius.
Shelter reports skyline angle and a geometric proxy, not simulated wind speed.
Dominance follows an explicitly bounded RVT-inspired weighted observer-height
formula; edge-clamped support is disclosed if the window reaches the region edge.

Vector contour export returns GeoJSON **segments**, with source zoom, approximate
metric spacing and region bounds. These are real contour geometries, but are not
stitched, simplified or a survey-grade elevation product. Coordinates use native
cell centers and the Mapterhorn source grid. The vertical reference stays that of
the source dataset.

## Remaining delivery stages

1. Register new compute families as engine recipe operations with units, input
   contracts, version identities, locks, native/WASM bindings and refusal tests.
2. Move connected plateau routing into canonical Rust; broaden breaching tests
   and expose filled/carved surface differences and conditioning metadata.
3. Turn point solar/exposure/dominance calculations into cancellable map layers
   with halo/cache support and explicit boundary confidence.
4. Complete geomorphon options (skip radius, adaptive search, distance relaxation,
   border nulling and full patterns), with independent GRASS reference comparisons.
5. Extend horizons to regional/distant terrain for dependable long-range solar and
   visibility; broader projection, rectangular-cell and nodata verification.
6. Measure physical phone behavior. A desktop or software GPU check cannot supply
   this evidence. HTTPS/device setup and real device runs are still required.