GitHub-style model card: architecture figure + results table

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 examples/sample_tile.tif filter=lfs diff=lfs merge=lfs -text
+figure_01_architecture.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -11,33 +11,70 @@ pipeline_tag: image-segmentation
 
 # FloodDuo
 
-Dual foundation-encoder (DINOv3-L + Clay v1.5) binary water segmentation for
-4-band (B/G/R/NIR) PlanetScope imagery at 3 m resolution. See the
-[paper](https://github.com/Sk-2103/FloodDuo) (ISPRS Journal of Photogrammetry
-and Remote Sensing, 2026) and [code](https://github.com/Sk-2103/FloodDuo) for
-the full architecture, training protocol, and benchmark results.
+**A Dual Foundation-Encoder Architecture for Generalizable High-Resolution Flood Mapping**
 
-## Files
+Saurabh Kaushik, Beth Tellman, Qihao Weng — *ISPRS Journal of Photogrammetry and Remote Sensing*, 2026
+· [Code](https://github.com/Sk-2103/FloodDuo) · [Paper](https://github.com/Sk-2103/FloodDuo#citation)
 
-- `floodduo_full.pt` — self-contained checkpoint (model config + full state
-  dict, frozen backbones included), 1.36 GB. Load with
-  [`src/inference.py`](https://github.com/Sk-2103/FloodDuo/blob/main/src/inference.py)
-  from the GitHub repo, or see the inference notebook there for a complete
-  walkthrough.
-- `examples/sample_tile.tif`, `examples/sample_mask.tif` — one held-out test
-  tile (FloodPlanet, Oklahoma) for a no-setup demo. From the public
-  [FloodPlanet benchmark](https://zenodo.org/records/19698577).
+FloodDuo maps open water in high-resolution (3 m, 4-band B/G/R/NIR PlanetScope)
+imagery by pairing two **frozen** vision foundation-model encoders that carry
+complementary information:
+
+- **DINOv3-L** (RGB) — sharp spatial / boundary detail.
+- **Clay v1.5** (all four bands) — wavelength-conditioned spectral discrimination.
+
+Convolutional networks preserve fine boundary detail but generalize poorly to
+unseen regions; geospatial foundation models supply global context but, at
+standard patch sizes, lose the detail that distinguishes a flooded street from
+a dry one. FloodDuo keeps both: the frozen encoders are adapted with
+lightweight trainable modules (an in-block frequency-domain Earth-Adapter,
+plus post-hoc atrous-convolution and pyramid-pooling adapters), and their
+branch predictions are merged by a **disagreement-gated fusion** whose
+per-pixel Jensen-Shannon divergence doubles as a label-free reliability map,
+before a LinkNet decoder produces the full-resolution mask. Only ~65M
+parameters are trained against ~614M frozen.
+
+![FloodDuo architecture](figure_01_architecture.png)
+
+## Results (leave-one-region-out, region-mean water IoU)
+
+| Model | FloodPlanet | UFO |
+|---|---|---|
+| **FloodDuo (ours)** | **0.728** | **0.819** |
+| TerraMind-L | 0.700 | 0.789 |
+| Prithvi-EO-2 | 0.678 | 0.774 |
+| DOFA-L | 0.687 | 0.766 |
+| Clay v1.5-L | 0.675 | 0.773 |
+| CROMA-L | 0.672 | 0.715 |
+| SSL4EO-S12 DINO | 0.650 | 0.767 |
+| U-Net (from scratch) | 0.648 | 0.782 |
+
+FloodDuo significantly outperforms U-Net (+8.0 / +3.7 pp) and the strongest
+single-encoder foundation model (+2.8 / +3.0 pp, paired Wilcoxon on both).
+Every table (matched single-encoder controls, the fusion ablation,
+boundary-resolved analysis, D-reliability calibration) is in
+[results.md](https://github.com/Sk-2103/FloodDuo/blob/main/results.md) in the
+code repo.
 
-## This checkpoint vs. the paper's reported numbers
+## This checkpoint vs. the numbers above
 
 This is the **release model**: trained on all FloodPlanet + UFO data pooled
 together (not held out by region), for actual use on new imagery. Its
-validation IoU (0.80, on a random held-out 15% of tiles) is **not** the same
-number as the paper's headline result. The paper's 0.728 / 0.819 region-mean
-IoU figures come from leave-one-region-out cross-validation, a much stricter
-protocol specifically designed to measure generalization to unseen regions —
-see the paper and `results.md` in the GitHub repo. This release checkpoint is
-the practical model to run on your own data, not the benchmark artifact.
+validation IoU (0.80, on a random held-out 15% of tiles) is a different
+measurement from the table above — that table is leave-one-region-out
+cross-validation, a much stricter protocol specifically designed to measure
+generalization to *unseen* regions. This release checkpoint is the practical
+model to run on your own data, not the benchmark artifact; don't quote its
+validation score as the paper's headline result.
+
+## Files
+
+- `floodduo_full.pt` (1.36 GB) — self-contained: model config + full state
+  dict, frozen DINOv3-L and Clay v1.5 backbones included. One download, no
+  other weights needed.
+- `examples/sample_tile.tif`, `examples/sample_mask.tif` — one held-out
+  FloodPlanet test tile (Oklahoma) for a no-setup demo, from the public
+  [FloodPlanet benchmark](https://zenodo.org/records/19698577).
 
 ## Quick start
 
@@ -47,18 +84,33 @@ from src.inference import load_model, predict_file  # from the GitHub repo
 
 ckpt = hf_hub_download("Sk-21/FloodDuo", "floodduo_full.pt")
 model = load_model(ckpt)
-prob, mask, profile = predict_file(model, "your_tile.tif")  # 4-band B,G,R,NIR reflectance
+prob, mask, profile = predict_file(model, "your_tile.tif")  # 4-band B,G,R,NIR
 ```
 
-Full walkthrough, including a no-setup example: `notebook/inference_demo.ipynb`
-in the [GitHub repo](https://github.com/Sk-2103/FloodDuo).
+`predict_file` auto-detects and converts scaled integer DN (e.g. Planet's own
+Surface Reflectance product or Sentinel-2 L2A, both uint16 x10000) to
+reflectance automatically. Full walkthrough, including a no-setup example and
+an explicit normalization step:
+[`notebook/inference_demo.ipynb`](https://github.com/Sk-2103/FloodDuo/blob/main/notebook/inference_demo.ipynb)
+in the code repo.
 
 ## Input format
 
-4-band (B, G, R, NIR) surface reflectance GeoTIFF, float32, values roughly in
-[0, 0.5+] (PlanetScope-style). No manual normalization needed — the model
-normalizes internally. Evaluated at 512-1024 px tiles; larger scenes should
-be tiled by the caller.
+4-band (B, G, R, NIR) PlanetScope-style imagery, single tile, roughly
+512-1024 px per side (the size the model was evaluated at in the paper;
+larger scenes should be tiled by the caller). Raw DN or reflectance both
+work — see above.
+
+## Citation
+
+```bibtex
+@article{kaushik2026floodduo,
+  title   = {FloodDuo: A Dual Foundation-Encoder Architecture for Generalizable High-Resolution Flood Mapping},
+  author  = {Kaushik, Saurabh and Tellman, Beth and Weng, Qihao},
+  journal = {ISPRS Journal of Photogrammetry and Remote Sensing},
+  year    = {2026}
+}
+```
 
 ## License