# MVP Terrain Accuracy And Source Requirements

## Purpose

This document defines the terrain accuracy bar for the Ground Zero MVP tile and
the source data requirements for moving from the current point-sampled prototype
to a real Unreal terrain import pipeline.

The goal is practical accuracy, not survey-grade simulation. Terrain should be
recognizably based on the real place, preserve the correct horizontal scale, and
support believable traversal, water, biome, and resource placement.

## MVP Tile

```text
tile_id: gz_us_ca_pacifica_utm10n_e544_n4160
location: Linda Mar / San Pedro Valley edge, Pacifica, California
tile_size: 1 km x 1 km
prototype_grid: WGS84 / UTM zone 10N
```

## Accuracy Tiers

### Tier 0 - Prototype Complete

This is the current state.

- Point-sampled USGS elevation data is available for the tile.
- A normalized `.r16` heightmap exists.
- Source and generation metadata are recorded.
- Tile registry status can move to `generated`.

Tier 0 is enough to prove the automation path, but not enough for final MVP
terrain art or gameplay.

### Tier 1 - MVP Required

This is the minimum bar for the first playable real-terrain MVP tile.

- Horizontal scale must remain 1 Unreal kilometer per real 1 kilometer.
- Ground elevation source should be 1 meter where available.
- If 1 meter source is unavailable, 1/3 arc-second or better can be used
  temporarily, but the tile must be flagged as lower-confidence.
- Terrain vertical values must preserve real elevation range within a documented
  tolerance after import.
- The generated Unreal landscape must include metadata for source dataset,
  source date/version, vertical datum, horizontal datum/projection, min/max
  elevation, and generation version.
- Terrain should not have visible seams at tile edges when adjacent tiles use
  the same source and generation version.
- Slopes should be smoothed only enough for playable traversal; smoothing must
  not erase major hills, valleys, drainage cuts, or coastal features.
- Water features present in source data should be represented at least as
  gameplay placeholders.
- Biome/resource placement should use source-derived hints, not purely manual
  placement.

### Tier 2 - Preferred After MVP

- Use lidar-derived source DEM or point-cloud processing where available.
- Preserve drainage, road/trail cuts, ridgelines, and terrain breaks with higher
  fidelity.
- Build separate masks for slope, wetness, vegetation class, water, coastline,
  and traversal difficulty.
- Add automated QA maps for slope extremes, seam mismatch, missing samples, and
  source confidence.
- Generate World Partition-ready landscape tiles directly from the pipeline.

## Final Ground Elevation Source Requirements

Primary source:

- USGS 3DEP 1-meter DEM or USGS Seamless 1-Meter DEM where available.

Preferred fallback order:

1. USGS 3DEP 1-meter DEM / Seamless 1-Meter DEM.
2. USGS 3DEP source DEM or lidar-derived DEM with better local coverage.
3. USGS 3DEP 1/3 arc-second DEM.
4. USGS Elevation Point Query Service only for quick validation and prototypes.

The point-query service should not be the final production importer because it
is inefficient for dense raster generation and does not provide the full source
surface metadata we need for repeatable tiles.

## Coastal And Bathymetry Requirements

The Ground Zero region is coastal, so the MVP terrain requirements must account
for ocean/coastal data even if the first Ground Zero tile is mostly land.

Minimum coastal requirements:

- Determine whether each tile contains ocean, shoreline, beach, creek mouth, or
  wetland features.
- If a tile includes ocean or nearshore water, use NOAA/NCEI coastal DEM,
  bathymetry, or Coastal Relief Model data where appropriate.
- Track vertical datum and unit differences between land and bathymetric sources.
- Do not use bathymetric products for navigation.
- Represent ocean depth as gameplay terrain/water depth data, not as a real
  nautical chart.

Preferred source order:

1. NOAA/NCEI coastal DEM or CUDEM where available for the specific coast.
2. NOAA/NCEI Coastal Relief Model for broader topographic/bathymetric context.
3. NOAA/NCEI bathymetry data viewer products for source discovery.
4. Coarser global relief only as placeholder context, not final MVP tile data.

## Import Requirements For Unreal

The terrain pipeline should produce:

- Raw heightmap in Unreal-compatible format.
- Metadata JSON.
- Tile registry update.
- Optional preview CSV or GeoJSON for debugging.
- Source confidence report.

Required metadata:

- `tile_id`
- source dataset name
- source URI or stable identifier
- source license/usage note
- source acquisition/publication date if available
- source resolution
- horizontal datum/projection
- vertical datum
- min elevation
- max elevation
- normalized heightmap format
- Unreal landscape scale assumptions
- generation version
- pipeline version

## Acceptance Tests

Before a terrain tile can be considered MVP-ready:

- [ ] Source DEM/raster covers the full 1 km tile.
- [ ] Generated tile is exactly 1000 m x 1000 m in projected coordinates.
- [ ] Heightmap resolution and Unreal landscape scale are documented.
- [ ] Min/max elevation in metadata matches generated heightmap scaling.
- [ ] Tile can be regenerated and produces the same content hash from the same
      source inputs.
- [ ] Tile registry status moves through `source_data_found`, `generated`, and
      `validated` intentionally.
- [ ] Adjacent-edge sample rows/columns can be compared for seam validation.
- [ ] Water/coastline handling is documented for the tile.
- [ ] Biome/resource hints are recorded.

## Current Prototype Gap List

The current `33 x 33` USGS point-sampled heightmap is useful, but it must be
replaced or supplemented before MVP terrain lock.

Known gaps:

- It samples point elevations instead of downloading a complete DEM raster.
- It has coarse 31.25 m sample spacing.
- It does not yet preserve source vertical datum metadata.
- It does not include land-cover, hydrography, coastline, or bathymetry layers.
- It is not yet imported into an Unreal Landscape actor.
- It is not yet validated against neighboring tile seams.

## Decision

For the Ground Zero MVP tile, the target terrain source is USGS 3DEP 1-meter DEM
or the USGS Seamless 1-Meter DEM if it is available for the tile. NOAA/NCEI
coastal DEM or Coastal Relief Model data should be used for coastal and
bathymetric context where the MVP tile or its immediate neighbors intersect
shoreline/ocean features.
