CHRIS-PROBA1 — Cloud and shadow segmentation

Cloud and cloud-shadow segmentation for CHRIS/PROBA-1 imagery. The model is a two-network ensemble (RegNetY-004 + ConvNeXtV2-nano, U-Net heads) finetuned on RGBN bands and unified so the same weights handle both DN and TOA inputs.

Install

pip install mlstac
# runtime dependencies for this model:
pip install torch segmentation-models-pytorch pytorch-lightning timm rasterio numpy

Usage

import mlstac

# 1. Load the metadata and download the model files
model = mlstac.load(
    "https://huggingface.co/isp-uv-es/CHRIS-PROBA1/resolve/main/mlm.json"
)
local = model.download("CHRIS-PROBA1")

# 2. Build the ensemble (loads both checkpoints)
net = local.compiled_model(device="cuda")

# 3a. Segment a raw CHRIS GeoTIFF end to end.
#     mode_n is the CHRIS acquisition mode; source is 'dn' or 'toa'
#     (or None to guess it from the file name).
mask = local.module.predict_chris(
    "image_mode_1/scene_DN.tif", model=net, mode_n=1, source="dn"
)

# 3b. Mode 6 is CHRIS mode 20: 4 raw bands, DN only (no TOA).
mask20 = local.module.predict_chris(
    "image_mode_20/scene_DN.tif", model=net, mode_n=6, source="dn"
)

If you already have a 4-band RGBN array (4, H, W), you can skip the CHRIS preprocessing and call the model directly:

mask = local.module.predict_large(rgbn_array, model=net)

Output classes

Value	Class
0	clear
1	thick cloud
2	thin cloud
3	shadow
99	nodata

Supported CHRIS modes

The loader builds the RGBN stack (Red, Green, Blue, NIR) from the raw cube according to the acquisition mode. Modes 1-5 average several bands per channel and exist in both DN and TOA. Mode 6 is CHRIS mode 20: it has 4 bands used directly (no averaging) and DN only.

mode_n	CHRIS mode	DN	TOA
1	1	✓	✓
2	2	✓	✓
3	3	✓	✓
4	4	✓	✓
5	5	✓	✓
6	20	✓	—

DN and TOA use different radiometric scales before a fixed clip, so passing the correct source matters. Pass source='dn' or source='toa', or leave it as None to infer it from the file name.

Example scenes

The examples/ folder holds one paired scene per mode (image_mode_1 ... image_mode_5 with DN and TOA, image_mode_20 with DN only) to try the model.

Citation

If you use this model, please cite the CHRIS/PROBA-1 cloud segmentation work from the Image and Signal Processing (ISP) group, Universitat de València.

License

MIT