geoskill-flood-inundation-modeling

洪水淹没模拟 | Flood Inundation Modeling

Bathtub (static) flood inundation modeling from a digital elevation model (DEM). Given a water level (--water-level), every pixel whose elevation is below the water level is considered potentially inundated, with water depth equal to the difference between the water level and the ground elevation. Suitable for rapid floodplain screening, flood storage/detention area assessment, and estimation of storm-surge and dam-break inundation extents.

Two modes are implemented:

• static: purely static inundation — every pixel with DEM < water_level is counted as flooded (including interior isolated depressions).
• connected: hydrological connectivity constraint. Uses scipy.ndimage.label for 8-connectivity component analysis and keeps only the inundated regions connected to the raster boundary, excluding interior isolated depressions — in real physical processes these depressions would not be filled by external floodwater. This mode is closer to the actual inundation extent.

Outputs an inundation extent raster (0/1), a water depth raster (m), and a statistics JSON (inundated area in m²/km², stored water volume in m³, mean/max water depth, etc.). The --synthetic mode generates a simulated DEM containing valley depressions and isolated depressions, so the workflow and the difference between the two modes can be validated offline without network access or real data.

Dependencies / 依赖

pip install numpy rasterio scipy

Usage / 使用方法

Basic usage (synthetic data, offline)

python geoskill-flood-inundation-modeling.py --bbox 116.0 39.0 117.0 40.0 --water-level 15.0 --output-dir ./output

Example 1: connectivity-constrained inundation (synthetic data)

python geoskill-flood-inundation-modeling.py \
    --bbox 116.0 39.0 117.0 40.0 \
    --water-level 18.0 \
    --method connected \
    --synthetic \
    --output-dir ./flood_connected

Example 2: static inundation (including isolated depressions)

python geoskill-flood-inundation-modeling.py \
    --bbox 116.0 39.0 117.0 40.0 \
    --water-level 18.0 \
    --method static \
    --synthetic \
    --output-dir ./flood_static

Example 3: real DEM inundation

python geoskill-flood-inundation-modeling.py \
    --input dem.tif \
    --water-level 5.0 \
    --method connected \
    --output-dir ./real_flood

Example 4: comparison of different water-level scenarios

python geoskill-flood-inundation-modeling.py --bbox 116 39 117 40 --water-level 10.0 --method connected --output-dir ./wl10 --quiet
python geoskill-flood-inundation-modeling.py --bbox 116 39 117 40 --water-level 20.0 --method connected --output-dir ./wl20 --quiet

Output / 输出

Data Source / 数据源 / Source

• DEM: local input GeoTIFF (EPSG:4326), which may come from SRTM / ASTER GDEM / Copernicus DEM
• Synthetic mode: locally generated simulated DEM with valley depressions and isolated depressions; no external data source

Privacy / 隐私声明 / Privacy

• Fully offline by default; no network requests are made
• --synthetic mode reads no external data
• All computation is performed locally; user data is never uploaded

License / License

MIT

---

---

name: geoskill-flood-inundation-modeling description: '基于 DEM 的 Bathtub 静态洪水淹没模拟，支持水文连通性约束（flood-fill）。Static bathtub flood inundation modeling from DEM with optional hydrological connectivity constraint. 输出淹没范围/水深 GeoTIFF + 面积体积统计 JSON。'

洪水淹没模拟 | Flood Inundation Modeling

基于数字高程模型（DEM）的 Bathtub（浴缸）静态洪水淹没模拟。给定一个水位 （--water-level），所有高程低于该水位的像元被视为潜在淹没区，水深为水位 与地面高程之差。适用于洪泛区快速筛查、蓄滞洪区评估、风暴潮/溃坝淹没范围 估算等场景。

实现两种模式：

• static：纯静态淹没，凡 DEM < water_level 的像元均计为淹没（含内部孤立洼地）。
• connected：水文连通性约束。用 scipy.ndimage.label 做 8 连通域分析， 只保留至少与栅格边界连通的淹没区，排除内部孤立洼地——真实物理过程中这些 洼地不会被外部洪水填充。该模式更贴近实际淹没范围。

输出淹没范围栅格（0/1）、水深栅格（m），以及淹没面积（m²/km²）、蓄水体积 （m³）、平均/最大水深等统计 JSON。支持 --synthetic 模式生成含河谷洼地与 孤立洼地的模拟 DEM，无需网络和真实数据即可验证流程并对比两种模式差异。

依赖

pip install numpy rasterio scipy

使用方法

基本用法（合成数据，离线）

python geoskill-flood-inundation-modeling.py --bbox 116.0 39.0 117.0 40.0 --water-level 15.0 --output-dir ./output

示例 1：连通性约束淹没（合成数据）

python geoskill-flood-inundation-modeling.py \
    --bbox 116.0 39.0 117.0 40.0 \
    --water-level 18.0 \
    --method connected \
    --synthetic \
    --output-dir ./flood_connected

示例 2：静态淹没（含孤立洼地）

python geoskill-flood-inundation-modeling.py \
    --bbox 116.0 39.0 117.0 40.0 \
    --water-level 18.0 \
    --method static \
    --synthetic \
    --output-dir ./flood_static

示例 3：真实 DEM 淹没

python geoskill-flood-inundation-modeling.py \
    --input dem.tif \
    --water-level 5.0 \
    --method connected \
    --output-dir ./real_flood

示例 4：不同水位情景对比

python geoskill-flood-inundation-modeling.py --bbox 116 39 117 40 --water-level 10.0 --method connected --output-dir ./wl10 --quiet
python geoskill-flood-inundation-modeling.py --bbox 116 39 117 40 --water-level 20.0 --method connected --output-dir ./wl20 --quiet

输出

数据源 / Source

• DEM：本地输入 GeoTIFF（EPSG:4326），可来自 SRTM / ASTER GDEM / Copernicus DEM
• 合成模式：本地生成含河谷洼地与孤立洼地的模拟 DEM，无外部数据源

隐私声明 / Privacy

• 默认完全离线运行，不发起任何网络请求
• --synthetic 模式不读取任何外部数据
• 所有计算在本地完成，不上传用户数据

License

MIT