added Citations

CITATION.md

@@ -0,0 +1,115 @@
+# Geodata and Tooling Citation
+
+## 1) LVermGeo RLP / GeoShop RLP (terrain, ortho, buildings)
+
+Source: GeoShop RLP - Digitale Gelaendemodelle (DGM)  
+Source URL: https://geoshop.rlp.de/digitale_gelaendemodelle/digitale_gelaendemodelle_dgm.html  
+GeoShop entry point: https://geoshop.rlp.de/  
+Open data portal: https://www.lvermgeo.rlp.de/geodaten-geoshop/open-data  
+License: Data Licence Germany - Attribution - Version 2.0 (dl-de/by-2-0)  
+License URL: https://www.govdata.de/dl-de/by-2-0  
+Accessed: 2026-01-19
+
+Products used:
+- DGM1 (Digitales Gelaendemodell, GeoTIFF)
+- DOM1 (Digitales Oberflaechenmodell, GeoTIFF)
+- DOP20 (Digitale Orthophotos, JP2)
+- 3D-Gebaeudemodelle LOD2 (CityGML)
+- BDOM20RGBI (Gebaeude-/Objektpunktwolke, LAZ)
+- LPOLPG (LAS-Punktwolke, kombiniert; abgeleitete Teilmengen: LPG/LPO)
+
+GeoBasis download patterns used in the pipeline:
+- DGM1: `https://geobasis-rlp.de/data/dgm1/current/tif/dgm01_32_{x}_{y}_1_rp.tif`
+- DOM1: `https://geobasis-rlp.de/data/dom1/current/tif/dom1_32_{x}_{y}_1_rp_2020.tif`
+- DOP20: `https://geobasis-rlp.de/data/dop20rgb/current/jp2/dop20rgb_32_{x}_{y}_2_rp_2023.jp2`
+- LoD2 CityGML: `https://geobasis-rlp.de/data/geb3dlo/current/gml/LoD2_32_{x}_{y}_2_RP.gml`
+- BDOM20RGBI: `https://geobasis-rlp.de/data/bdom20rgbi/current/las/bdom20rgbi_32_{x}_{y}_2_rp.laz`
+- LPOLPG: `https://geobasis-rlp.de/data/las/current/las/lpolpg_32_{x}_{y}_1_rp.laz`
+
+Required attribution (verbatim):
+(c) GeoBasis-DE / LVermGeoRP 2026, dl-de/by-2-0, www.lvermgeo.rlp.de
+
+If modified, append:
+[Data modified] (or in German: [Daten bearbeitet])
+
+## 2) HydroRIVERS (river network for erosion workflow)
+
+Dataset: HydroRIVERS v1.0 (Europe tile used in pipeline)  
+Download URL used by pipeline: https://data.hydrosheds.org/file/HydroRIVERS/HydroRIVERS_v10_eu_shp.zip  
+Project page: https://www.hydrosheds.org  
+License: Covered by the HydroSHEDS License Agreement (see https://www.hydrosheds.org)  
+Accessed: 2026-01-23
+
+Recommended citation (from HydroRIVERS Technical Documentation v1.0):
+Lehner, B., Grill G. (2013): Global river hydrography and network routing: baseline data and new approaches to study the world's large river systems. Hydrological Processes, 27(15): 2171-2186. Data is available at www.hydrosheds.org.
+
+## 3) HydroLAKES (lake depth support for erosion workflow)
+
+Dataset: HydroLAKES v1.0 polygon database  
+Download URL used by pipeline: https://data.hydrosheds.org/file/hydrolakes/HydroLAKES_polys_v10_shp.zip  
+Project page: https://www.hydrosheds.org  
+License: Creative Commons Attribution 4.0 International (CC BY 4.0)  
+License URL: https://creativecommons.org/licenses/by/4.0/  
+Accessed: 2026-01-23
+
+Recommended citation (from HydroLAKES Technical Documentation v1.0):
+Messager, M.L., Lehner, B., Grill, G., Nedeva, I., Schmitt, O. (2016): Estimating the volume and age of water stored in global lakes using a geo-statistical approach. Nature Communications: 13603. doi: 10.1038/ncomms13603. Data is available at www.hydrosheds.org.
+
+## 4) GeoData pipeline tools used
+
+Core geospatial and conversion tooling used by `GeoData/geodata_to_unity.py` and `GeoData/geodata_pipeline/`:
+- Python (project runtime; configured for 3.11-3.12)
+- `uv` (environment and dependency management)
+- GDAL / OGR / OSR (`osgeo`) including `gdalbuildvrt`
+- PDAL
+- citygml-tools 2.4.0
+- cjio (`cjio[export,reproject]`)
+- laspy (`laspy[lazrs]`)
+- NumPy
+- SciPy
+- scikit-learn
+- Shapely
+- trimesh
+- requests
+- tomli-w
+
+Reference implementation locations:
+- Dependencies: `GeoData/pyproject.toml`
+- Main CLI: `GeoData/geodata_to_unity.py`
+- Pipeline modules: `GeoData/geodata_pipeline/`
+
+## 5) Numerical methods and related implementations (BibTeX)
+
+```bibtex
+@article{saetra2012,
+  title={Shallow Water Simulations on Multiple GPUs},
+  author={S{\ae}tra, ML and Brodtkorb, AR},
+  year={2012}
+}
+
+@book{toro2009,
+  title={Riemann Solvers and Numerical Methods for Fluid Dynamics},
+  author={Toro, EF},
+  edition={3},
+  year={2009}
+}
+
+@article{kader2022,
+  title={A New Variant of Rusanov Scheme},
+  author={Kader, ...},
+  journal={IJAM},
+  year={2022}
+}
+
+@article{audusse2004,
+  title={A Fast and Stable Well-Balanced Scheme...},
+  author={Audusse, E and Bouchut, F and ...},
+  year={2004}
+}
+
+@github{bshishov2019,
+  title={UnityTerrainErosionGPU},
+  author={Bshishov, A},
+  url={https://github.com/bshishov/UnityTerrainErosionGPU}
+}
+```

README.md

@@ -1,96 +1,61 @@
-## GeoData Toolkit
+# GeoData
 
-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.
+Toolkit zum Export von Geodaten in Unity-kompatible Assets (`export_unity/...`).
 
-### Prerequisites
+## 1) Wie startet man das Projekt?
-- `uv` installed. Use Python 3.10–3.12 for now (`triangle2` from `cjio[export]` has no CPython 3.13 wheels).
-- Optional: Java 17+ if you want to experiment with the bundled `citygml-tools` utilities (not needed for heightmaps/orthophotos).
 
-### Environment setup (uv)
+**Voraussetzungen**
-- Install deps (creates `.venv` if missing): `uv sync`. You can skip manual activation by prefixing commands with `uv run ...`; if you prefer activation, run `uv venv && source .venv/bin/activate`.
+- Python `>=3.11,<3.13`
-- `uv run <cmd>` executes with the project environment (e.g., `uv run python geodata_to_unity.py --setup`). Use `--directory` to target another path if needed; `--offline` disables network fetches.
+- `uv`
-- 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`.
+- GDAL (inkl. `osgeo`)
-- Create the default directory tree and config: `uv run python geodata_to_unity.py --setup` (or `bash scripts/setup_dirs.sh` for directories only).
+- Optional fuer Gebaeude: `cjio`, `citygml-tools`
 
-### Repository Layout
+**Schnellstart**
-- `raw/` — working inputs (not versioned): `raw/dgm1/`, `raw/dop20/jp2/`, `raw/citygml/lod1/`, `raw/citygml/lod2/`.
+```bash
-- `archive/` — offline storage for untouched downloads (e.g., zipped DOP/CityGML tiles, dop20 filelist).
+cd GeoData
-- `work/` — intermediates such as `dgm.vrt` and `_tmp.tif` files; safe to delete/regenerate.
+uv sync
-- `export_unity/height_png16/` — final 16-bit PNG heightmaps for Unity import.
+uv run python geodata_to_unity.py --setup
-- `export_unity/tile_index.csv` — manifest mapping tile IDs to world bounds and scaling ranges (`global_min/global_max` plus per-tile `tile_min/tile_max`), plus `tile_key`; built during heightmap export and required by orthophotos.
+uv run python geodata_to_unity.py --export all
-- `export_unity/ortho_jpg/` — cropped orthophoto tiles aligned to the terrain grid (JPEG + worldfiles).
+```
-- `geodata_to_unity.py` — main CLI (uses `geodata_pipeline/` library modules).
-- `scripts/` — helpers to create the directory tree and fetch DOP20 inputs.
-- `geodata_config.toml` — generated config (see `geodata_config.example.toml` for defaults).
-- `AGENTS.md` — contributor guide.
 
-### Quick Start
+**Alternative mit Archivdaten**
-1. Activate the uv venv (`source .venv/bin/activate`) or prefix commands with `uv run`.
+```bash
-2. Initialize config + directories: `uv run python geodata_to_unity.py --setup`.
+uv run python geodata_to_unity.py --build-from-archive --export all
-3. Export assets (builds VRTs automatically if missing):
+```
-   ```bash
-   uv run python geodata_to_unity.py --export all
-   # heightmaps only: uv run python geodata_to_unity.py --export heightmap
-   # textures only:   uv run python geodata_to_unity.py --export textures
-   # buildings:       uv run python geodata_to_unity.py --export buildings
-   # trees (CSV+GLB): uv run python geodata_to_unity.py --export trees
-   ```
-4. Import the PNGs into Unity Terrains using `tile_index.csv` for placement and height scaling (0–65535, per-tile by default).
 
-### How the export works
+## 2) Welche Funktionen umfasst das Projekt und wie werden diese genutzt?
-- Heightmaps: the pipeline builds `work/dgm.vrt` from all `raw/dgm1/*.tif`, computes a global min/max once (legacy fallback), and warps each tile footprint to `heightmap.out_res` with `srcNodata=-9999`. Per-tile min/max are computed from the warped tile and used to scale PNGs to `[0, 65535]` by default (`heightmap.use_tile_minmax=false` keeps global scaling). `export_unity/tile_index.csv` records `global_min/global_max`, `tile_min/tile_max`, and `tile_key = f"{floor((xmin + overlap_x) / tile_size_x)}_{floor((ymin + overlap_y) / tile_size_y)}"` (defaults: `tile_size_x=1000.0`, `tile_size_y=1000.0`, `overlap_x=0.5`, `overlap_y=0.5` in `[tile_key]`).
-- Orthophotos: `work/dop.vrt` is built from `raw/dop20/jp2/*.jp2`; the manifest drives the cropping bounds. JPEG tiles are written to `export_unity/ortho_jpg/` with matching `.jgw` worldfiles. If the manifest is missing, the orthophoto export aborts—run the heightmap export first or use `--export all`.
-- Archives: `--build-from-archive` supports a monolithic ZIP (`archive/archive_raw.zip`) and expands every `*.zip` under `archive/*` into the matching `raw/*` directories; dataset zips overlay the monolithic data. It also copies `archive/dop20/filelist.txt` next to `raw/dop20/` for the downloader.
-- Cleanup: temporary `_tmp.tif` and GDAL aux XML files under `work/` and `raw/dgm1/` are removed at the end of the heightmap export; avoid storing non-GDAL metadata in those folders.
 
-### Key Commands
+```bash
-- Refresh VRT: `gdalbuildvrt work/dgm.vrt raw/dgm1/*.tif`
+# Hoehenmodelle (PNG16) + tile_index.csv
-- Run export pipeline: `uv run python geodata_to_unity.py --export all`
+uv run python geodata_to_unity.py --export heightmap
-- Inspect an output tile: `gdalinfo export_unity/height_png16/<tile>.png | head`
-- Override config paths: use `--config <path>`, `--raw-dgm1-path <dir>`, `--raw-dop20-path <dir>`.
-- Build raws from archives: `uv run python geodata_to_unity.py --build-from-archive --export all` (uses `archive/archive_raw.zip` when present, then overlays `archive/*/*.zip`).
-- Deterministic submission rebuild: `uv run python geodata_to_unity.py --build-from-archive --clean-raw --validate --export all --force-vrt`.
-- Rebuild VRTs after moving data: add `--force-vrt`.
 
-### Workflow Notes
+# Orthofotos (JPG), nutzt tile_index.csv
-- Heightmaps normalize per tile using `tile_min/tile_max` by default; set `heightmap.use_tile_minmax=false` to restore global scaling across tiles. Adjust `heightmap.out_res` or `heightmap.resample` in `geodata_config.toml` if your AOI or target resolution changes.
+uv run python geodata_to_unity.py --export textures
-- `tile_key` config controls the tile grouping key in the manifest; defaults are `tile_size_x=1000.0`, `tile_size_y=1000.0`, `overlap_x=0.5`, `overlap_y=0.5` with `enabled=true`.
-- `_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 helper lives in `scripts/dlscript_dop20.sh` and pulls JP2/J2W/XML orthophotos listed in `archive/dop20/filelist.txt` (one URL per line); `archive/` can hold zipped 3D building tiles for future use.
-- `--clean-raw` only removes managed ingestion dirs (`raw/dgm1`, `raw/dop20/jp2`, `raw/dop20/j2w`, `raw/dop20/meta`, `raw/citygml/lod1`, `raw/citygml/lod2`) and intentionally keeps custom masks.
-- `--validate` writes `work/archive_materialize_report.json` and fails only when core datasets are missing (`dgm1 tif`, `dop20 jp2`, `citygml lod2`); optional sidecar gaps are warnings.
-- 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 `heightmap.out_res` aligned with the importer’s expected resolution (currently 1025).
 
-### Orthophotos (textures)
+# Gebaeude (GLB) aus CityGML LoD2
-1. Ensure DOP assets are present in `raw/dop20/jp2/`, `raw/dop20/j2w/`, and `raw/dop20/meta/`; use `scripts/dlscript_dop20.sh` to fetch JP2/J2W/XML entries listed in `archive/dop20/filelist.txt` (one URL per line).
+uv run python geodata_to_unity.py --export buildings
-2. From `GeoData/`, run:
-   ```bash
-   uv run python geodata_to_unity.py --export textures
-   ```
-   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.
-   - The download script relies on a Linux/OpenSSL toolchain with system CA bundle at `/etc/ssl/certs/ca-certificates.crt`; it builds a trust chain by fetching the geobasis intermediate. macOS/Windows users should either provide a combined CA via `CURL_CA_BUNDLE` or download with a browser/wget and place files manually.
-   - Place companion `.j2w` and `.xml` files under `raw/dop20/j2w/` and `raw/dop20/meta/` if available; they are not required for the VRT but help provenance.
 
-### Downloads (raw data)
+# Baeume (CSV + GLB)
-- Run: `uv run python geodata_to_unity.py --download` (uses `geodata_download.toml`).
+uv run python geodata_to_unity.py --export trees
-- Shows a progress bar while downloading and exits cleanly on Ctrl+C (exit code 130).
+```
 
-### Buildings (automated exporter)
+**Hauptausgaben**
-- Run: `uv run python geodata_to_unity.py --export buildings`
+- `export_unity/height_png16/` und `export_unity/tile_index.csv`
-- What it does per tile:
+- `export_unity/ortho_jpg/`
-  - Converts LoD2 CityGML → CityJSON (citygml-tools), triangulates with cjio, rebases to tile-local XY using `tile_index.csv`.
+- `export_unity/buildings_tiles/`
-  - Merges all buildings into one GLB (1 mesh with roof/wall primitives), decimates to the configured triangle budget.
+- `export_unity/trees*/`
-  - Roofs: planar UVs from tile-local XY, embedded per-tile DOP20 orthophoto as base color (unlit by default).
-  - Walls: vertex colors sampled from the ortho as a fallback (neutral otherwise).
-  - Coordinates: glTF-friendly (x=east, y=height, z=-north) so glTFast instantiates one GameObject with two submeshes.
-- Requirements: LoD2 GMLs under `raw/citygml/lod2/`, per-tile orthos in `export_unity/ortho_jpg/`, tools on PATH (`tools/citygml-tools-2.4.0/citygml-tools`, `cjio` or override via `CJIO` env).
-- Open items: richer wall coloring from BDOM/LPO facades, better simplification, footprint-aware ground snapping beyond the current clamp-to-ground.
 
-### Troubleshooting
+## 3) Welche externen Bibliotheken und Quellen wurden verwendet?
-- Empty raw directories cause VRT creation to fail fast (`No sources available to build VRT`); populate inputs or adjust `--raw-*` overrides.
+
-- If you moved raw data or deleted `work/`, add `--force-vrt` to rebuild VRTs before exporting.
+**Bibliotheken/Tools**
-- Orthophoto export warnings like `Computed -srcwin ... falls partially outside source raster extent` indicate coverage gaps; add neighboring JP2s or accept the NoData edge fill.
+- Python
-- If GDAL Python bindings are missing, install system GDAL first and re-run `uv sync` so `osgeo` imports succeed.
+- uv
+- GDAL
+- cjio
+- citygml-tools
+
+**Externe Datenquellen (Kategorien)**
+- DGM1 (GeoTIFF) in `raw/dgm1/`
+- DOP20 (JP2) in `raw/dop20/jp2/`
+- CityGML LoD2 in `raw/citygml/lod2/`
+- Optional: DOM1, BDOM, LPO/LPG fuer Baum-/Masken-Workflows