S-EO Shadow Detection

Research code for shadow detection in satellite imagery from:

S-EO: A Large-Scale Dataset for Geometry-Aware Shadow Detection in Remote Sensing Applications

Paper (IEEE Xplore)
Paper (arXiv)
Project page
Dataset creation repository
Hugging Face collection (model weights + dataset)

The main public portability target in this repository is the released UNet checkpoint. The Hugging Face collection contains the S-EO dataset and the released model weights. The uploaded best model corresponds to the UNet defined in this repository.

Quickstart

Create an environment and install the public dependencies:

conda create -n shadow-eo python=3.11
conda activate shadow-eo
pip install -r requirements.txt

Run inference with a released UNet checkpoint:

python inference.py \
  --checkpoint /path/to/model.ckpt \
  --input /path/to/image.png \
  --output /path/to/prediction.png

The inference script:

• loads the Lightning checkpoint
• pads the image to a multiple of 32
• runs the UNet
• applies sigmoid and thresholding
• crops back to the original image size

Using The Trained Model

CLI

python inference.py \
  --checkpoint /path/to/model.ckpt \
  --input /path/to/image.tif \
  --output outputs/example_mask.png \
  --threshold 0.5 \
  --device auto \
  --save-probability

Python

from inference import load_unet_checkpoint, predict_image

model, device = load_unet_checkpoint("/path/to/model.ckpt", device="auto")
prediction = predict_image(model, "/path/to/image.png", threshold=0.5, device=device)
mask = prediction["mask"]  # uint8 numpy array with values 0 or 255

Supported Workflows

1. Train on S-EO

python main.py \
  --pansharpened-dir /path/to/pansharpened_he \
  --shadows-dir /path/to/shadows \
  --val-aois JAX_341 JAX_342 JAX_335 JAX_334 UCSD_353 UCSD_573 \
  --train-aois-csv /path/to/JAX.csv \
  --train-aois-csv /path/to/UCSD.csv \
  --train-aois-limit 50 \
  --model-type unet \
  --experiment-root-dir experiments \
  --experiment-name seo_unet

If --train-aois-csv is omitted, the script uses all AOIs under --pansharpened-dir except those assigned to validation.

2. Evaluate on S-EO

python eval.py \
  --checkpoint /path/to/model.ckpt \
  --model-type unet \
  --pansharpened-dir /path/to/pansharpened_he \
  --shadows-dir /path/to/shadows \
  --test-aois JAX_341 JAX_342 JAX_335 JAX_334 UCSD_353 UCSD_573 \
  --output-dir eval_outputs

3. Fine-tune on AISD

python finetune_aisd.py \
  --train_dir /path/to/AISD/Train412 \
  --val_dir /path/to/AISD/Val51 \
  --model_path /path/to/model.ckpt \
  --save_dir finetune_checkpoints

4. Evaluate on AISD

python eval_aisd.py \
  --test_dir /path/to/AISD/Test51 \
  --model_path /path/to/model.ckpt \
  --pred_dir finetune_evals \
  --model_type unet

Models

This repository contains two model paths:

• UNet Recommended path for public use and released checkpoint inference.
• FSDNet Included as a baseline and training option.

model.py now lazy-loads the vendored FSDNet code so UNet users do not need the FSDNet stack just to run inference.

FSDNet still has an additional environment requirement beyond requirements.txt: install a CuPy build compatible with your CUDA setup. Follow the upstream CuPy installation guidance and the vendored FSDNet README if you intend to use that model path.

Repository Layout

• main.py: S-EO training CLI
• eval.py: S-EO evaluation CLI
• finetune_aisd.py: AISD fine-tuning CLI
• eval_aisd.py: AISD evaluation CLI
• inference.py: lightweight UNet inference CLI and Python helper API
• model.py: Lightning modules for UNet and FSDNet
• dataset.py: S-EO datasets and dataloading
• plots_notebooks/: notebooks used for paper figures and analysis

Notes

• This is research code and is provided as-is.
• The current evaluation behavior is kept close to the research workflow in this repository.
• The S-EO dataset mainly serves as a large-scale training resource rather than a clean benchmark validation set.

Citation

If you use this code or dataset in your research, please cite:

@inproceedings{masquil2025shadoweo,
  title={S-EO: A Large-Scale Dataset for Geometry-Aware Shadow Detection in Remote Sensing Applications},
  author={Masquil, El\'{i}as and Mar\'{i}, Roger and Ehret, Thibaud and Meinhardt-Llopis, Enric and Mus\'{e}, Pablo and Facciolo, Gabriele},
  booktitle={Proceedings of the 2025 IEEE/CVF Conference on Computer Vision and Pattern Recognition Workshops (CVPRW)},
  year={2025}
}