geoskill-flood-inundation-modeling

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

ruiduobao@ruiduobao

Install

openclaw skills install @ruiduobao/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 / 依赖

bash

pip install numpy rasterio scipy

Usage / 使用方法

Basic usage (synthetic data, offline)

bash

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)

bash

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)

bash

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

bash

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

bash

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 / 输出

File	Format	Description
`inundation_mask.tif`	GeoTIFF (uint8)	Inundation extent, 1=flooded 0=not flooded, EPSG:4326
`water_depth.tif`	GeoTIFF (float32)	Water depth (m); flooded area = water level − DEM, non-negative
`flood_stats.json`	JSON	Number of inundated pixels, area (m²/km²), volume (m³), mean/max water depth
`output-manifest.json`	JSON	Run manifest (inputs/outputs/QA/software versions)

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，无需网络和真实数据即可验证流程并对比两种模式差异。

依赖

bash

pip install numpy rasterio scipy

使用方法

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

bash

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

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

bash

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：静态淹没（含孤立洼地）

bash

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 淹没

bash

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

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

bash

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

输出

文件	格式	说明
`inundation_mask.tif`	GeoTIFF (uint8)	淹没范围，1=淹没 0=未淹没，EPSG:4326
`water_depth.tif`	GeoTIFF (float32)	水深（m），淹没区 = 水位−DEM，非负
`flood_stats.json`	JSON	淹没像元数、面积（m²/km²）、体积（m³）、平均/最大水深
`output-manifest.json`	JSON	运行清单（输入/输出/QA/软件版本）

数据源 / Source

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

隐私声明 / Privacy

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

License

MIT