GeoData/README.md

GeoData Heightmap Export

This repository converts DGM1 elevation tiles into Unity-ready 16-bit PNG heightmaps and a placement manifest. It relies on GDAL for mosaicking, resampling, and scaling to UInt16 ranges Unity expects.

Prerequisites

• GDAL installed with Python bindings (osgeo importable).
• Python 3.9+ available on PATH.
• DGM1 source tiles placed under raw/dgm1/ (legacy raw_dgm1/ still works) as dgm1_<utm_zone>_<easting>_<northing>.tif with matching .tfw files.
• Raw inputs (raw/dop/, raw/citygml/lod1/, raw/citygml/lod2/) are kept out of git; keep them locally or document how to fetch/regenerate. Legacy raw_dop/ and raw_3dgeb_lod*/ remain ignored/compatible.

Environment setup (uv)

• Create a project venv: uv venv && source .venv/bin/activate.
• Install dependencies from pyproject.toml: uv sync (generates uv.lock; warning-free with dependency-groups).
• If wheels fail to resolve, ensure system GDAL is present (e.g., brew install gdal or apt-get install gdal-bin libgdal-dev), then rerun uv sync.
• Create the default directory tree (inputs/archives/outputs): bash setup_dirs.sh.

Repository Layout

• raw/ — preferred working inputs (not versioned): raw/dgm1/, raw/dop/jp2/, raw/citygml/lod1/, raw/citygml/lod2/. Legacy directories (raw_dgm1/, raw_dop/, raw_3dgeb_lod1/, raw_3dgeb_lod2/) are still honored by the scripts.
• archives/ — optional offline storage for untouched downloads (e.g., zipped DOP/CityGML tiles) to keep raw inputs separated from working copies.
• work/ — intermediates such as dgm.vrt and _tmp.tif files; safe to delete/regenerate.
• export_unity/height_png16/ — final 16-bit PNG heightmaps for Unity import.
• export_unity/tile_index.csv — manifest mapping tile IDs to world bounds and global min/max used for scaling.
• export_unity/ortho_jpg/ — cropped orthophoto tiles aligned to the terrain grid (JPEG + worldfiles).
• export_heightmaps.py — main export script.
• export_ortho_tiles.py — exports orthophoto tiles from DOP JP2 inputs using the terrain manifest.
• AGENTS.md — contributor guide.

Quick Start

1. Activate the uv venv (source .venv/bin/activate) or prefix commands with uv run.
2. Export Unity heightmaps and manifest (builds work/dgm.vrt automatically if missing):

   uv run python export_heightmaps.py
   

3. Import the PNGs into Unity Terrains using tile_index.csv for placement and consistent height scaling (0–65535).

Key Commands

• Refresh VRT: gdalbuildvrt work/dgm.vrt raw/dgm1/*.tif (legacy: raw_dgm1/*.tif)
• Run export pipeline: uv run python export_heightmaps.py
• Inspect an output tile: gdalinfo export_unity/height_png16/<tile>.png | head
• Override defaults (e.g., orthophoto out dir): uv run python export_ortho_tiles.py --out-dir export_unity/ortho_jpg (see -h on each script for tunables).

Workflow Notes

• The script computes a global min/max from the VRT to scale all tiles consistently; adjust OUT_RES, RESAMPLE, or TILE_SIZE_M in export_heightmaps.py if your AOI or target resolution changes.
• _tmp.tif files in work/ are transient; you can delete work/ to force a clean rebuild.
• Keep file names stable to avoid churn in Unity scenes; re-exports overwrite in place.
• Large raw datasets are intentionally excluded from version control—document download sources or scripts instead of committing data.
• Additional inputs: download helpers live in raw/dop/dlscript.sh (legacy: raw_dop/dlscript.sh) which fetch JP2/J2W/XML orthophotos listed in filelist.txt; 3dgeblod1/ and 3dgeblod2/ hold zipped 3D building tiles with object lists for future use.
• Handoff to Unity: copy/sync export_unity/height_png16/ and export_unity/tile_index.csv into DTrierFlood/Assets/GeoData/ before running the Unity-side importer. Keep OUT_RES aligned with the importer’s expected resolution (currently 1025).

Orthophotos (textures)

1. Ensure DOP JP2s are present in raw/dop/jp2/ (legacy: raw_dop/jp2/; download helper lives in raw/dop/dlscript.sh or raw_dop/dlscript.sh).
2. From GeoData/, run:

   uv run python export_ortho_tiles.py
   

   This builds work/dop.vrt if missing and writes export_unity/ortho_jpg/<tile>.jpg + .jgw aligned to tile_index.csv.
   • If you see Computed -srcwin ... falls partially outside source raster extent warnings, the DOP coverage is slightly smaller than the tile footprint; edge pixels will be filled with NoData/zeros. Add adjacent JP2s or shrink the requested window if you need to avoid the warning.

Buildings

The building export pipeline is temporarily disabled while we choose a mesh conversion approach (GDAL lacks a native OBJ writer). CityGML LoD2 sources remain in raw_3dgeb_lod2/ locally (ignored in git); consider CityGML→glTF/OBJ tools (e.g., citygml-tools + cityjson2gltf) for future integration.