egyx/hydroflow-water-segmentation

HydroFlow: 12-Channel Sentinel-2 Multispectral Water Segmentation Model

HydroFlow is a production-grade deep learning model for high-resolution surface water extraction from 12-band Sentinel-2 multispectral satellite observations. Based on a transfer-learning U-Net architecture with an ImageNet-pretrained ResNet-34 backbone adapted for 12 spectral input channels, HydroFlow achieves 81.66% Global Pixel IoU (and 82.10% Peak Validation IoU) on strictly unseen satellite scenes.

---

Verified Project Resources & Official Links

Resource	Access URL	Description
🌐 Interactive Web Platform	Launch Platform	Hosted on GitHub Pages: Earth Explorer, Satellite Raster Upload, and In-Browser AI Engine
📊 Research Benchmark Analytics	View Dashboard	Standalone interactive dashboard: dynamic loss curves, Pareto efficiency frontier, NDWI calculator
⚡ Cloud Inference Engine	Render API Service	Hosted on Render: High-performance ONNX Runtime inference server (/predict, /predict_geo)
💻 GitHub Repository	Source Code	Complete reproducible research codebase, modular pipelines, training CLI, and tests
📦 Hugging Face Model Hub	Model Weights	Official PyTorch state dicts, standard ONNX graph, and INT8 quantized edge models
📓 Kaggle Research Collection	Explore 6 Notebooks	Full scientific reproducibility suite (EDA, Scratch, Ablation, Flow Matching, Transfer Learning)

---

Model Checkpoint Files

File Name	Format	Size	Target Environment & Description
best_model_quant.onnx	ONNX (INT8)	24.6 MB	Edge & Browser Production Runtime: Dynamic INT8 quantized ONNX graph. 44ms CPU latency, 0.03% IoU drop, 75% memory savings.
best_model.onnx	ONNX (FP32)	97.8 MB	Standard Server Production: Full-precision dynamic-batch ONNX graph for ONNX Runtime (CPU/CUDA/TensorRT).
best_model.pth	PyTorch State Dict	98.0 MB	PyTorch Fine-Tuning: Raw PyTorch weights compatible with segmentation-models-pytorch.
config.json	JSON	1.2 KB	Architectural configuration, Sentinel-2 band mappings, and physical calibration min-max constants.
samples/	GeoTIFF & PNG	~3.2 MB	8 diverse, verified validation scenes with ground truths, RGB composites, and overlays.

---

Official Master 6-Way Comparative Benchmark

All experiments evaluated under strict scientific parity on 62 strictly unseen validation scenes (1,015,808 pixels):

Experiment ID	Architecture & Paradigm	Backbone	Input Bands	Params	Global Pixel IoU	Precision	Recall	F1-Score
W1-Scratch-12ch	Custom U-Net (Scratch)	Scratch Baseline	12 Bands	7.77M	73.33%	86.85%	82.50%	84.62%
W1-Scratch-6ch	Custom U-Net (Scratch)	Scratch Baseline	6 Golden Bands	7.76M	64.92%	84.81%	73.47%	78.73%
W2-Pretrained-ResNet34-12ch	SMP U-Net (Transfer)	ResNet-34	12 Bands	24.46M	81.66%	91.48%	88.39%	89.91%
W2-Pretrained-ResNet34-6ch	SMP U-Net (Transfer)	ResNet-34	6 Golden Bands	24.46M	79.80%	91.83%	85.89%	88.75%
W2-Pretrained-EffNetB0-12ch	SMP U-Net (Transfer)	EfficientNet-B0	12 Bands	6.25M	76.56%	86.73%	86.72%	86.72%
W2-Pretrained-EffNetB0-6ch	SMP U-Net (Transfer)	EfficientNet-B0	6 Golden Bands	6.25M	74.82%	83.61%	87.68%	85.60%

---

Prepackaged Diverse Validation Suite (8 Hydrological Regimes)

Included directly in samples/ for rapid reproducibility:

Scene ID	Hydrological Category	Physical Regime Description	GT Water	Pred Water	Validation IoU
sample_1_lake	Inland Lake / Reservoir	Expansive open reservoir with sharp littoral boundaries	76.90%	78.26%	93.94%
sample_2_river	Meandering River & Shoreline	High-curvature river channel with vegetative bank transitions	35.28%	34.38%	96.15%
sample_3_stream	Narrow Streams & Wetland	Fine marshland tributaries near the 10m spatial resolution limit	8.02%	9.13%	87.21%
sample_4_deepwater	Open Deep Water Basin	Vast open water body with deep optical absorption & low noise	89.38%	89.29%	98.26%
sample_5_estuary	Coastal Bay & Estuary	Dynamic tidal flats, shallow lagoons, and brackish shorelines	57.26%	57.72%	96.14%
sample_6_oasis	Arid Reservoir & Oasis	Desert reservoir with high-contrast dry sand and rocky topography	24.70%	24.87%	89.99%
sample_7_canal	Agricultural Canal Network	Geometric irrigation channels intersecting cultivated cropland	17.61%	16.37%	90.55%
sample_8_creek	Thin Creek & Riparian Tributary	Sub-kilometer meandering stream through dense canopy & alluvium	3.89%	4.04%	83.99%

---

Quickstart: Python Inference (3 Lines)

Using ONNX Runtime (Ultra-Fast CPU/GPU)

import onnxruntime as ort
import tifffile as tiff
import numpy as np

# 1. Initialize ONNX Runtime session
session = ort.InferenceSession("best_model_quant.onnx", providers=["CPUExecutionProvider"])

# 2. Load and calibrate Sentinel-2 12-band raster
band_mins = np.array([69.0, 100.0, 233.0, 104.0, 127.0, 14.0, 11.0, 64.0, 17.0, 17.0, 10.0, 0.0], dtype=np.float32)
band_maxs = np.array([941.0, 1143.0, 1733.0, 2478.0, 4046.0, 4453.0, 3761.0, 224.0, 1902.0, 1907.0, 80.0, 98.0], dtype=np.float32)

raw = tiff.imread("samples/sample_1_lake.tif").astype(np.float32)
norm = np.clip((raw.transpose(2, 0, 1) - band_mins[:, None, None]) / (band_maxs[:, None, None] - band_mins[:, None, None] + 1e-6), 0.0, 1.0)

# 3. Predict binary water mask (< 25 ms)
logits = session.run(None, {"input": norm[np.newaxis, ...]})[0]
water_mask = (1.0 / (1.0 + np.exp(-logits[0, 0]))) >= 0.50
print(f"Surface water pixels: {water_mask.sum()} / {water_mask.size} ({water_mask.mean()*100:.2f}%)")

---

Citation & Attribution

@misc{elbasyouni2026hydroflow,
  author = {Mohamed Mostafa Elbasyouni},
  title = {HydroFlow: Multispectral 12-Channel Satellite Water Segmentation, Optimal Transport Flow Matching, and Transfer Learning},
  year = {2026},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/egyx/hydroflow-water-segmentation}}
}