Repository Guidelines

Project Structure & Module Organization

export_heightmaps.py is the main pipeline: builds work/dgm.vrt, scales heights, and writes export_unity/height_png16/*.png plus export_unity/tile_index.csv.
export_ortho_tiles.py exports orthophotos into export_unity/ortho_jpg/ using the terrain manifest.
Preferred raw layout: raw/dgm1/, raw/dop20/jp2/ (or raw/dop/jp2/), raw/citygml/lod1/, raw/citygml/lod2/; legacy paths (raw_dgm1/, raw_dop/, raw_3dgeb_lod*/) still work. archives/ can hold untouched downloads/zips.
export_unity/ is safe to sync to Unity projects; treat it as generated output. work/ holds intermediates and is disposable.

Create a venv: uv venv && source .venv/bin/activate. Install deps: uv sync (generates uv.lock).
If wheels fail, install system GDAL first (e.g., brew install gdal or apt-get install gdal-bin libgdal-dev), then rerun uv sync.
Prepare the directory tree (raw/archives/work/exports): bash scripts/setup_dirs.sh.
Heightmap export (rebuilds VRT if absent): uv run python export_heightmaps.py.
Orthophoto export: uv run python export_ortho_tiles.py (requires JP2s under raw/dop20/jp2/; alt raw/dop/jp2/ and legacy raw_dop/jp2/ still work). Use bash scripts/dlscript_dop20.sh to fetch JP2/J2W/XML listed in raw/dop20/filelist.txt.
Refresh VRT manually if needed: gdalbuildvrt work/dgm.vrt raw/dgm1/*.tif (legacy: raw_dgm1/*.tif).
Inspect a result: gdalinfo export_unity/height_png16/<tile>.png | head to sanity-check bounds and scaling.
Expected warning: Computed -srcwin ... falls partially outside source raster extent means 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 silence it.
Scripts accept CLI overrides (e.g., --out-dir, --jpeg-quality, --resample); run uv run python <script> -h to see options.

Python scripts use 4-space indentation, early-exit error handling, and SystemExit for fatal issues; follow PEP 8 where practical.
Keep tile IDs stable (base filename without extension); avoid renaming inputs to reduce churn downstream.
Prefer explicit constants for tunables (OUT_RES, RESAMPLE, TILE_SIZE_M) and log with clear context.

No automated tests yet; rely on manual validation: run exports on a small tile subset, open outputs in gdalinfo or GIS viewer, and confirm tile_index.csv aligns with Unity expectations.
When changing scaling or resolution, compare before/after stats (min/max) and spot-check terrain in Unity.

Commit messages are short, imperative summaries (e.g., "Ignore generated orthophotos"). Group related changes per commit; commit uv.lock when dependency versions change.
Before opening a PR: describe the change, list commands run, note data locations (not committed), and include any screenshots from Unity/GIS if visuals changed.
Ensure raw datasets and large intermediates stay out of git; verify .gitignore still covers generated files after changes.

Keep raw geodata local; avoid publishing source tiles or credentials. Document download sources/scripts instead of committing data.
Outputs may be large; prefer syncing export_unity/ artifacts via project-specific channels rather than embedding in the repo.