---
license: apache-2.0
library_name: fastai
pipeline_tag: image-segmentation
tags:
- pytorch
- fastai
- geospatial
- remote-sensing
- semantic-segmentation
- sentinel-1
- alphaearth
- surface-water
---

# 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.

```bash
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

```bash
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:

```bash
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`](THIRD_PARTY_NOTICES.md).

## Source code

The maintained project source and data-preparation guidance are available at [Rohit18/surfaceWaterMappingGlobal](https://github.com/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`](LICENSE) and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).