60 lines
4.2 KiB
Markdown
60 lines
4.2 KiB
Markdown
## 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 in `raw_dgm1/` as `dgm1_<utm_zone>_<easting>_<northing>.tif` (with matching `.tfw` files).
|
||
- Raw inputs (`raw_dop/`, `raw_3dgeb_lod1/`, `raw_3dgeb_lod2/`) are **kept out of git**; keep them locally or document how to fetch/regenerate.
|
||
|
||
### 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`.
|
||
|
||
### Repository Layout
|
||
- `raw_dgm1/` — input rasters (not versioned).
|
||
- `raw_dop/` — raw orthophoto downloads (JP2/J2W/XML), ignored in git.
|
||
- `raw_3dgeb_lod1/`, `raw_3dgeb_lod2/` — CityGML building tiles, ignored in git.
|
||
- `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):
|
||
```bash
|
||
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`
|
||
- Run export pipeline: `uv run python export_heightmaps.py`
|
||
- Inspect an output tile: `gdalinfo export_unity/height_png16/<tile>.png | head`
|
||
|
||
### 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: `raw_dop/` contains an HTTPS download helper (`raw_dop/dlscript.sh`) that fetches 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/` (use `raw_dop/dlscript.sh` if needed).
|
||
2. From `GeoData/`, run:
|
||
```bash
|
||
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.
|