FIMbox- A Testbed for Flood Inundation Mapping Experimentation

A modular open source testbed framework to standardize Flood Inundation Mapping (FIM) simulations and evaluation with custom datasets and hydrologic parameters in reproducible workflows. fimbox provides a streamlined, user friendly and cloud enabled pipeline to generate operational flood inundation maps using the NOAA Office of Water Prediction (OWP) Height Above Nearest Drainage (HAND) FIM framework, driven by National Water Model retrospective and forecasted streamflow. It is developed under the Surface Dynamics Modeling Lab (SDML) at The University of Alabama.

High-level workflow

---

fimbox implements an extensive Height Above Nearest Drainage (HAND) based flood inundation mapping workflow. It offers great flexibility to change datasets (e.g. resolution and source of river networks, catchments, DEMs) and to investigate different research questions (e.g. changing Manning's n, better representation of the synthetic rating curve, stream network segmentation, slope improvement and many more terrain conditioning options) to improve FIM extents and depths. The HAND preprocessing logic follows the NOAA OWP HAND FIM framework, whose reference implementation lives at https://github.com/NOAA-OWP/inundation-mapping. Ongoing work expands the modeling capability beyond a single model, integrating different models to enable multimodel FIM extents, and more.

Every module shown above ships its own README with a detailed workflow diagram and step by step usage: what the module does, every class and parameter it exposes, and runnable examples (see the Module documentation table below). Worked end to end examples for each stage live in tests/ and the package documentation in docs/.

Install

---

fimbox targets Python 3.10–3.12.

git clone https://github.com/sdmlua/fimbox.git
cd fimbox

# uv-based environment (recommended)
pip install uv
uv venv
uv pip install -e .

Activate the virtual environment before running any commands:

Mac / Linux

source .venv/bin/activate

Windows (Command Prompt)

.venv\Scripts\activate.bat

Windows (PowerShell)

.venv\Scripts\Activate.ps1

If you prefer Conda, create and activate the environment first, then run uv pip install -e . inside it.

Quick start: from boundary polygon to flood map

---

1. Stage AOI inputs

Download the DEM, NHD/NWM hydrography, FEMA NFHL, NLD levees, OSM bridges/roads, and USGS gages into an AOI working directory.

from fimbox import getAllInputData

getAllInputData(
    boundary="path/to/aoi_boundary.gpkg",
    aoi_id="my_basin",
    out_dir="out/my_basin",
)

See the tests/ folder for further detailed steps including HAND processing, SRC generation, calibration, and FIM generation. Users can change different parameters based on requirements.

Module documentation

---

Each module has its own README documenting what it contains, the full parameter surface (including optional parameters), and usage examples:

Module	Documentation	Purpose
fimbox.preprocessing	README	Overview of the preprocessing stages and the combined getAllInputData pipeline.
fimbox.preprocessing.download_data	README	Download and standardize AOI inputs (DEM, hydrography, NFHL, levees, OSM, gages).
fimbox.preprocessing.huc_test	README	Validate HUC8 codes against the packaged acceptable lists.
fimbox.preprocessing.process_bridgedem	README	Per-bridge LiDAR rasters and the bridge/DEM difference raster.
fimbox.preprocessing.calculate_branch	README	Branch derivation, HAND generation, crosswalk, and SRC/hydroTable build.
fimbox.preprocessing.calibrate_ratingcurve	README	SRC calibration (bathymetry, bankfull, subdivision, USGS/spatial/manual).
fimbox.streamflow	README	NWM retrospective/forecast, GEOGLOWS, and USGS retrieval, plots, statistics.
fimbox.fimgeneration	README	Per-branch inundation and AOI mosaicking from discharge CSVs.
fimbox.fimevaluation	README	Benchmark FIM query/download (FIMbench) and candidate-vs-benchmark evaluation (FIMeval).
Tests	README	What each test file demonstrates and how to run the suite.
Workflow diagrams	README	Editable Mermaid sources + generator script for every module workflow SVG (make workflows).

For more usage notes refer to the tests or docs for the fimbox python package.

Contribution

---

For contribution guidelines see CONTRIBUTING.md.

Acknowledgements

---

	Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama (NA22NWS4320003).

Contact

---

fimbox is developed at the Surface Dynamics Modeling Lab (SDML) at The University of Alabama.

Sagy Cohen (sagy.cohen@ua.edu), Supath Dhital (sdhital@ua.edu)

NOTE- This repository is still in active development and might contain bugs. Please let us know or create a pull request if you have better ideas. THANK YOU.