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.
Model details
| Field | Value |
|---|
| Task | Binary semantic segmentation |
| Output classes | other (0), water (1) |
| Architecture | FastAI ResNet34 U-Net |
| 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 |
| Checkpoint | models/s1aef_bottleneck_resnet34_best.pth |
| Normalization | band_stats.npz, containing 67-band mean and standard deviation arrays |
| Native output | Georeferenced float32 GeoTIFF containing P(water) |
The checkpoint SHA-256 is 3b89c5b768be8d8b5a00260693ca5d2a051ec63969234702903677b9e326138f.
Installation
Python 3.10+ is recommended. A CUDA-capable GPU makes inference substantially faster, but CPU inference is supported.
1hf download rohitm9/surfaceWaterGlobal --local-dir surfaceWaterGlobal
2cd surfaceWaterGlobal
3python -m venv .venv
4source .venv/bin/activate
5python -m pip install --upgrade pip
6python -m pip install -r requirements.txt
Input contract
Inference requires:
- One or more three-band Sentinel-1 GeoTIFFs named
s1_YYYY-MM-DD.tif. Band order must be VV, VH, angle.
- One 64-band AlphaEarth Foundations annual embedding GeoTIFF in the original band order.
- 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 bundled band_stats.npz.
Inference
1python src/infer.py \
2 --model-kind s1aef \
3 --scenes-root /path/to/s1/scenes \
4 --aef-path /path/to/alphaearth_2025.tif \
5 --run-dir . \
6 --output-root outputs \
7 --tile 512 \
8 --overlap 64 \
9 --batch-size 4
The default inference procedure averages four flip-based test-time augmentation passes. Use --no-tta for faster inference. Use --device cpu to force CPU execution.
To validate the files and raster contract before a full run:
1python src/infer.py \
2 --model-kind s1aef \
3 --scenes-root /path/to/s1/scenes \
4 --aef-path /path/to/alphaearth_2025.tif \
5 --run-dir . \
6 --validate-only
Outputs are written below outputs/s1_aef_tta/probabilities/ by default. They are continuous water probabilities, not thresholded binary masks.
Evaluation
The training run's formal evaluation summary and selected decision threshold are temporarily unavailable. They will be added when the original NERSC training artifacts are accessible. aef_bottleneck_report.json analyzes the learned 64-to-16 projection but is not a performance evaluation.
Until evaluation results are published, do not treat the probability values as calibrated or assume a universal threshold. Validate the model independently for the target geography, season, sensor preprocessing, and application.
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 67-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.
- AlphaEarth embeddings must correspond to a suitable year and be spatially aligned with the Sentinel-1 scenes.
- The current release does not include a validated probability threshold or complete quantitative evaluation summary.
- 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 binary water targets derived from Dynamic World. 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.
License
The original code and released checkpoint 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.
