Add Ground Zero terrain pipeline and playable assets

2026-05-14 00:09:40 -07:00
parent 46d0e080b5
commit 6d25ff690d
77 changed files with 5770 additions and 84 deletions
@@ -0,0 +1,111 @@
+# 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.