rohitm9/surfaceWaterGlobal

Surface Water Global

surfaceWaterGlobal predicts a per-pixel probability of surface water from co-registered Sentinel-1 SAR and AlphaEarth Foundations annual embeddings.

This is a custom FastAI/PyTorch checkpoint rather than a Transformers-native model. Use the bundled inference program; AutoModel.from_pretrained() is not supported.

Version 2 (label class)

This revision replaces the checkpoint released in August 2026. The earlier model was trained on a mixture of two Dynamic World (DW) water products: about 65% of its tiles used a binarized water probability (>= 0.5) and about 35% used the DW label band. The two products agree on 63-76% of water pixels. All models in this revision are trained on the DW label class only, which is the definition the paper describes. The earlier release is kept at tag v1-mixed-labels; this revision is tagged v2-labelclass.

Compared with the earlier checkpoint on the paper's 53-scene PlanetScope reference set, pooled water IoU is 0.851 against 0.849, precision decreases from 0.915 to 0.892 and recall rises from 0.921 to 0.948. This revision also ships the validation summary and the decision thresholds, which were missing from version 1.

Models

Directory	Model	Input	Checkpoint SHA-256
repository root	S1 + acquisition-year AEF (k=16, seed 42), the paper's primary model	3 S1 bands + 64 AEF bands	dd0252e2d08c693e3f88949a0a34a846f91dc7ab1668d91ba7ac0ddb688b06ec
variants/s1_only_k0_seed42/	S1-only control (k=0, seed 42)	3 S1 bands	a5eab4f07d68256d5a7922a8943efb1b0a14cbc0a513315aff737426a57b6e68
variants/s1_aef_previous_year_k16_seed42/	S1 + previous-year AEF (k=16, seed 42), trained with t-1 embeddings	3 S1 bands + 64 AEF bands	5bd312409fcf86e0a49258c37aa95a53867a5a6b2cef4f73d2e527a3d6fb2717

All checksums, including band_stats.npz for each model, are in checksums.sha256.

Field	Value
Task	Binary semantic segmentation
Output classes	other (0), water (1)
Architecture	FastAI ResNet-34 U-Net, Mish activations
Sentinel-1 input	3 bands: VV, VH, angle, in that order
AlphaEarth input	64 annual embedding bands, in source order
AEF bottleneck	Learned 1x1 convolution, 64 to 16 channels
U-Net input	19 channels: 3 S1 + 16 projected AEF (3 channels for the S1-only model)
Training data	5,278 Sentinel-1 / AEF / DW triplets, 4,222 training and 1,056 validation
Training target	Dynamic World label band, class 0 (water)
Normalization	band_stats.npz, 67-band mean and standard deviation (3-band for the S1-only model)
Native output	Georeferenced float32 GeoTIFF containing P(water)

Thresholds

Threshold	Where it comes from	Use
0.50	Selected on the DW validation split by every run, of the two values evaluated (0.30 and 0.50)	Default operating point of the checkpoints
0.30	Fixed operating point of the paper's reference-set evaluation	Reproduces the published tables

Probabilities are not calibrated. Validate the threshold for the target geography, season, sensor preprocessing and application.

Evaluation

Validation split (1,056 DW-labelled tiles, four-flip TTA, threshold 0.50): water IoU 0.698 (precision 0.767, recall 0.885) for the primary model, 0.690 for the previous-year model and 0.620 for the S1-only control.

Independent reference set of 53 PlanetScope-annotated scenes, threshold 0.30 (evaluation/planetscope_53_scenes_main_table.csv):

Method	Precision	Recall	Pooled water IoU	Per-scene mean IoU
S1 + AEF (acquisition year)	0.892	0.948	0.851	0.756
S1 + AEF (previous year, applied at inference)	0.882	0.946	0.840	0.741
S1-only control	0.933	0.582	0.558	0.443
OPERA DSWx-S1	0.858	0.852	0.746	0.591

Independent S1S2-Water benchmark (Wieland et al., 2024), 15 test scenes on a 30 m grid, all methods scored on the same pixels (evaluation/s1s2water_pooled.csv). Pooled water IoU, mean over three training seeds:

Method	Threshold 0.50	Threshold 0.30
S1 + AEF	0.953	0.941
OPERA DSWx-S1 (v1.2 with the upstream boundary fix)	0.869	0.869
S1-only control	0.822	0.794

No S1S2-Water data were used for training, model selection or threshold selection. Per-scene values are in evaluation/s1s2water_per_scene.csv; the threshold sweep on the reference set is in evaluation/planetscope_53_scenes_threshold_sweep.json.

Installation

Python 3.10+ is recommended. A CUDA-capable GPU makes inference substantially faster, but CPU inference is supported.

hf download rohitm9/surfaceWaterGlobal --local-dir surfaceWaterGlobal
cd surfaceWaterGlobal
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Input contract

Inference requires:

1. One or more three-band Sentinel-1 GeoTIFFs named s1_YYYY-MM-DD.tif. Band order must be VV, VH, angle. The models were trained on Earth Engine COPERNICUS/S1_GRD imagery (dB) at 10 m; a different Sentinel-1 processing chain changes the results, and the S1-only model is the more sensitive of the two.
2. One 64-band AlphaEarth Foundations annual embedding GeoTIFF in the original band order (not needed for the S1-only model).
3. S1 scenes in one run must share the same CRS, affine transform, width, and height. The inference program reprojects AEF windows onto the S1 grid when necessary.

Do not provide PCA-reduced AEF data. Normalization is checkpoint-specific and requires the band_stats.npz next to the checkpoint.

Inference

python src/infer.py \
  --model-kind s1aef \
  --scenes-root /path/to/s1/scenes \
  --aef-path /path/to/alphaearth_2025.tif \
  --run-dir . \
  --output-root outputs \
  --tile 512 \
  --overlap 64 \
  --batch-size 4

For a variant, point --run-dir at its directory, for example the S1-only control:

python src/infer.py \
  --model-kind s1 \
  --scenes-root /path/to/s1/scenes \
  --run-dir variants/s1_only_k0_seed42 \
  --output-root outputs

The default inference procedure averages four flip-based test-time augmentation passes. Use --no-tta for faster inference and --device cpu to force CPU execution. Add --validate-only to check the files and the raster contract before a full run.

Outputs are written below outputs/s1_aef_tta/probabilities/. They are continuous water probabilities, not thresholded masks.

Intended uses

• Research on surface-water mapping from Sentinel-1 and AlphaEarth inputs.
• Producing candidate water-probability rasters for subsequent validation and analysis.
• Reproducible comparison with other geospatial segmentation approaches.

Limitations

• Inputs must follow the exact band contract and training-time normalization.
• Performance may degrade outside the geographic, seasonal, hydrological, or preprocessing distributions represented during training.
• Radar layover, shadow, speckle, ice, wet soil, flooded vegetation, and artificial surfaces may cause errors. On arid terrain the S1-only control labels radar-dark ground as water; the fused model does not.
• AlphaEarth embeddings must correspond to a suitable year and be spatially aligned with the Sentinel-1 scenes.
• The training targets are Dynamic World predictions, not field observations, and carry the errors of that product.
• Outputs should not be used as the sole basis for emergency response, navigation, safety-critical, regulatory, or legal decisions.

Training data and attribution

Training used Sentinel-1 inputs, AlphaEarth Foundations annual embeddings, and water targets derived from the Dynamic World label band. Required third-party notices and source links are recorded in THIRD_PARTY_NOTICES.md.

Source code

The maintained project source and data-preparation guidance are available at Rohit18/surfaceWaterMappingGlobal. src/train.py here is the exact trainer that produced these checkpoints.

License

The original code and released checkpoints are provided under Apache License 2.0. Third-party software and datasets remain subject to their respective licenses and attribution requirements. See LICENSE and THIRD_PARTY_NOTICES.md.