# Ground Zero Unreal Landscape Import Plan

## Purpose

This document describes how to import the extracted Ground Zero 1-meter DEM
subset into Unreal as a Landscape heightmap.

## Source

```text
Data/Terrain/Extracted/gz_us_ca_pacifica_utm10n_e544_n4160/gz_us_ca_pacifica_utm10n_e544_n4160_1m_dem_subset.tif
```

Source properties:

- Size: 1000 x 1000 pixels.
- Pixel size: 1 m x 1 m.
- CRS: EPSG:26910 / NAD83 UTM zone 10N.
- Bounds: E 544000-545000, N 4160000-4161000.
- Elevation range: about 3.16 m to 96.51 m.

## Conversion Script

```text
Scripts/convert_ground_zero_dem_to_unreal_heightmap.py
```

The script:

- Reads the extracted 1-meter DEM subset.
- Resamples it to 1009 x 1009.
- Encodes elevation into unsigned 16-bit height values using Unreal's
  landscape midpoint, so sea level is approximately Unreal Z 0.
- Writes a little-endian `.r16` heightmap.
- Writes a small grayscale preview file.
- Writes import metadata with Unreal scale values.

## Output

```text
Data/Terrain/Unreal/gz_us_ca_pacifica_utm10n_e544_n4160/
```

Files:

- `gz_us_ca_pacifica_utm10n_e544_n4160_unreal_1009.r16`
- `gz_us_ca_pacifica_utm10n_e544_n4160_unreal_1009_preview.pgm`
- `gz_us_ca_pacifica_utm10n_e544_n4160_unreal_heightmap_metadata.json`

If Pillow is installed, the script also writes:

- `gz_us_ca_pacifica_utm10n_e544_n4160_unreal_1009.png`

## Unreal Import Settings

Use the generated metadata file as the source of truth.

Current settings:

```text
heightmap resolution: 1009 x 1009
tile world size: 1000 m x 1000 m
X scale: 99.2063492063492 cm
Y scale: 99.2063492063492 cm
Z scale: 100.0 cm
Z offset: 0.0 m
height encoding: Unreal landscape midpoint 32768 = approximately sea level
```

Why 1009:

- Unreal Landscape import requires specific valid dimensions.
- 1009 x 1009 is a valid import size and close to the 1000 x 1000 source DEM.
- X/Y scale maps 1008 intervals across exactly 1000 real meters.

## Import Steps

1. Open the Unreal Editor.
2. Open or create the Ground Zero terrain test map.
3. Go to Landscape mode.
4. Choose Import from File.
5. Select `gz_us_ca_pacifica_utm10n_e544_n4160_unreal_1009.r16`.
6. Set the landscape resolution to 1009 x 1009 if Unreal does not auto-detect it.
7. Set X scale and Y scale from metadata.
8. Set Z scale from metadata.
9. Place the landscape so the tile origin maps to the project terrain origin.
10. Save the map under the project terrain test area.

The repeatable project import path is:

```text
Scripts/setup_ground_zero_terrain_map.py
Scripts/verify_ground_zero_terrain_map.py
```

The generated terrain test map is:

```text
/Game/Agrarian/Maps/L_GroundZeroTerrain_Test
```

## Validation After Import

- Landscape bounds should be 1000 m x 1000 m.
- Imported elevation range should visually match the source: low coastal/valley
  terrain rising into hills.
- No extreme spikes or inverted terrain should appear.
- The north/south/east/west edges should remain suitable for seam comparison
  against neighboring tiles.
- The landscape should be treated as prototype terrain until material, water,
  biome, and resource layers are added.