---
license: mit
library_name: mlstac
tags:
  - earth-observation
  - remote-sensing
  - cloud-segmentation
  - chris-proba
  - semantic-segmentation
---

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

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1ydANmqaFExOGghxXqupnOQvbro7RFsd7?usp=sharing)

## Install

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

## Usage

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

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