/swmm-gis

name: swmm-gis
description: GIS/DEM preprocessing for SWMM experiments using the user's own QGIS/GRASS layers. Use when the user asks to (1) delineate subcatchments through QGIS/GRASS (standard or entropy-guided), (2) preprocess QGIS-derived subcatchment polygons into builder-ready CSV, (3) identify high-entropy hotspot subcatchments, or (4) expose QGIS/GRASS-backed preprocessing as MCP tools for reproducible workflows. For bbox-only inputs WITHOUT real pipe data, use `swmm-anywhere` instead (it synthesises a plausible network from OSM streets + DEM).

SWMM GIS / Preprocess

Part of [Agentic SWMM](https://github.com/Zhonghao1995/agentic-swmm-workflow) — install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

Before calling any watershed delineation tool — ask the user

When the user triggers watershed delineation (`qgis_raw_to_entropy_partition` or equivalent), **always ask these questions first** before making the tool call:

1. **Delineation mode** — Standard (fast, direct GRASS basins, no entropy) or Entropy-guided (paper WJE/NWJE/WFJS split-lump with sensitivity figures)? 2. **Stream threshold** — How many upslope cells define a stream? Default 100. Smaller = more streams = finer subcatchments. 3. **If entropy mode** — Delta threshold (default 0.015) and WFJS similarity threshold (default 0.95)? Use defaults unless doing sensitivity exploration. 4. **Purpose** — Planning / calibration exploration / sensitivity analysis / paper reproduction? This affects how strictly to apply paper-only splits and whether sensitivity figures are needed. 5. **CRS normalization needed?** — Are all input layers already in the same projected CRS? If uncertain, check first with `qgis_load_layers` + `qgis_validate_crs`.

Do not assume entropy mode. Do not skip the stream threshold question — it directly controls subcatchment count.

Default CRS policy: if source layers already share the same projected CRS, do **not** run `normalize-layers`. The normalization bridge reprojects, clips, and may resample raster grids, so it can change watershed structure. Only use it when layer CRS/raster alignment actually needs preprocessing. If CRS differs but geometry should be preserved, prefer a reproject-only step over clipping/resampling.

Choosing the right delineation mode

| | Standard | Entropy-guided | |---|---|---| | **Speed** | Fast (~minutes) | Slow (~10–30 min, 5 sensitivity variants) | | **Output** | GRASS basin polygons only | WJE/NWJE/WFJS partition + sensitivity figures + entropy hotspot ranking | | **Use when** | Quick first look, simple watersheds, testing pipeline connectivity | Research, paper reproduction, heterogeneous land-use/soil, need to justify subcatchment count | | **MCP flag** | `mode: "standard"` | `mode: "entropy"` (default) |

Entropy hotspot ranking

After an entropy run, `audit/entropy_hotspot_ranking.json` ranks subcatchments by WJE descending. Rank 1 = highest spatial heterogeneity = candidate for finer delineation in calibration. Surface this to the user if they ask "which subcatchments matter most" or "where should I refine."

What this skill provides

• Subcatchment polygon preprocessing (MVP):
• ingest polygon GeoJSON
• estimate area/width/slope with deterministic fallback and optional DEM-assisted metrics
• link each subcatchment outlet to a network node ID
• export builder-ready CSV for `swmm-builder`
• QGIS-oriented raw-data entrypoint:
• validate raw/QGIS-exported layer paths and shapefile sidecars
• inspect CRS hints from `.prj` and GeoJSON metadata
• run QGIS Processing / GRASS hydrology for flow accumulation, drainage direction, stream network, and basin labels
• compute paper-consistent WJE/NWJE/WFJS entropy diagnostics along the longest D8 flow path
• generate entropy-guided subcatchment partitions and threshold sensitivity figures
• extract QGIS overlay attributes into `swmm-params` CSV inputs
• export standard Agentic SWMM intermediates under `runs/<case>/01_gis/`, `02_params/`, and `04_network/`
• Clean final layer packaging:
• keep detailed audit artifacts in `00_raw/`, `01_gis/`, `02_params/`, `audit/`, and `memory/`
• also create a user-facing `final_layers/` folder with the SWMM/GIS layers the user needs next
• include `subcatchments.shp`, `flow.shp`, `slope_percent.tif`, `outfall.shp`, `overview.png`, and `manifest.json`

Scripts

• `scripts/preprocess_subcatchments.py`
• `--subcatchments-geojson <file>`
• `--network-json <file>` (from `swmm-network` schema)
• `--out-csv <file>` (builder-ready CSV)
• `--out-json <file>` (assumptions + detailed metrics)
• optional DEM mode: `--dem-stats-json <file>`, `--dem-stats-id-field <field>`
• optional helpers: `--id-field`, `--outlet-hint-field`, `--default-slope-pct`, `--min-width-m`, `--max-link-distance-m`

• `scripts/qgis_prepare_swmm_inputs.py`
• `load-layers`: validate source paths and shapefile sidecars
• `validate-crs`: write a CRS consistency report from a layer manifest
• `normalize-layers`: use QGIS Processing to reproject DEM, boundary, land-use, and soil layers to one CRS and clip them by the boundary
• `overlay-landuse-soil`: convert a QGIS overlay GeoJSON into `landuse.csv` and `soil.csv`
• `export-swmm-intermediates`: produce the standard data-side outputs for the modular path:
• `runs/<case>/00_raw/qgis_layers_manifest.json`
• `runs/<case>/00_raw/qgis_crs_report.json`
• `runs/<case>/01_gis/subcatchments.{geojson,csv,json}`
• `runs/<case>/02_params/{landuse.csv,soil.csv,landuse.json,soil.json,merged_params.json}`
• `runs/<case>/04_network/{network.json,network_qa.json}`
• `runs/<case>/qgis_export_manifest.json`
• `import-drainage-assets`: copy a prepared network JSON into `04_network` and run network QA
• `export-swmm-intermediates` and `import-drainage-assets` accept `--skills-root <dir>` to relocate the sibling `swmm-params`/`swmm-network` scripts they subprocess-shell i