xbd-s12

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 21 Open GitHub ↗

xBD-S12: Building damage assessment from Copernicus Sentinel-1 and Sentinel-2 satellite imagery.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# The Potential of Copernicus Satellites for Disaster Response: Retrieving Building Damage from Sentinel-1 and Sentinel-2

[![Paper](https://img.shields.io/badge/arXiv-PDF-b31b1b)](https://arxiv.org/abs/2511.05461)
[![Hugging Face](https://img.shields.io/badge/🤗%20-Models-yellow)](https://huggingface.co/collections/prs-eth/xbd-s12)
[![Zenodo](https://img.shields.io/badge/Zenodo-link-green)](https://zenodo.org/records/18960454)
![MIT](https://img.shields.io/badge/License-MIT-929292.svg)

This repository contains the offical code and dataset for the paper "The Potential of Copernicus Satellites for Disaster Response: Retrieving Building Damage from Sentinel-1 and Sentinel-2". The dataset, referred to as **xBD-S12**, is derived from the original [xBD dataset](https://xview2.org/) and includes co-registered Sentinel-1 and Sentinel-2 imagery.

# Setup

## Environment
We use [uv](https://docs.astral.sh/uv/) to manage the Python environment. Simply install uv and run the following command to create and activate the environment with all necessary dependencies:
```bash
uv sync
source .venv/bin/activate
```

## Dataset

The original xBD VHR images and labels cannot be redistributed here due to licensing restrictions. Please download them directly from [xView2](https://xview2.org/) by following their instructions. Place the resulting, extracted dataset in the `data/` folder, e.g. in `data/original_xbd` folder. The expected structure after extraction should be:

```
data/
└── original_xbd/
    ├── hold/
    ├── test/
    ├── tier1/
    └── tier3/
```

From there, the xBD-S12 dataset can be generated by running the following command. [Optional:] Add the `--create_hdf5` flag if you also want to create the HDF5 file for faster loading during training.

```bash
bash setup_dataset.sh --original_xbd_path="data/original_xbd" --num_workers=8 [--create_hdf5]
```

Alternatively, you can follow the steps below to create the dataset manually.

1. Download the xBD-S12 dataset from Zenodo at this [URL](https://zenodo.org/records/18960454).

```bash
cd data/
curl -L -O "https://zenodo.org/records/18960454/files/xbd_s12.tar.gz?download=1"
tar -xvzf xbd_s12.tar.gz # remove the v flag if you don't want to see the list of extracted files
rm xbd_s12.tar.gz
```

2. Create lightweight vrt files to wrap up the original raster files with corrected metadata under `data/xbd_s12/xbd`.

```bash
python src/data/create_aligned_vrt.py --original_xbd_path="data/original_xbd" --num_workers=8
```

3. Create the masks from the original xBD labels and store them under `data/xbd_s12/masks/`.

```bash
python src/data/create_masks.py --original_xbd_path='data/original_xbd'
```

4. [Optional] Create the HDF5 files for faster loading during training and inference. This will create one single HDF5 file containing all the Sentinel-1, Sentinel-2, and mask data chunked and compressed.

```bash
python src/data/create_hdf5.py --num_workers=8
```

The final dataset structure should look like this:

```
data/
└── xbd_s12/
    ├── masks/
    ├── s1/
    ├── s2/
    ├── s2_tci/
    ├── xbd/ # only contains the .vrt files, which reference the original .tif files in data/original_xbd
    ├── normalization.json
    └── xbd_s12_metadata.geojson
```

For a detailed description of the dataset, please refer to [DATASET.md](DATASET.md). To quickly explore it, refer to the notebook [`xbd-s12_exploration.ipynb`](notebooks/xbd-s12_exploration.ipynb).

---

# Models & Inference

We provide the checkpoints of our best models trained on xBD-S12 on the Hugging Face Hub at this [URL](https://huggingface.co/collections/prs-eth/xbd-s12). The models can be easily loaded and used for inference using the `InferenceFromHub` class in `src/inference/inference_from_hub.py`. For example:

```python
from src.inference.inference_from_hub import InferenceFromHub

inferor = InferenceFromHub()
preds = inferor.infer(
    fp_s1_pre='path/to/s1_pre.tif',
    fp_s1_post='path/to/s1_post.tif',
    fp_s2_pre='path/to/s2_pre.tif',
    fp_s2_post='path/to/s2_post.tif',
)
```

For a complete example, including how to download and prepare Sentinel data, please refer to the notebook [`inference_palisades_wildfires.ipynb`](notebooks/inference_palisades_wildfires.ipynb).

# Training

To train a model yourself, run the following command:

```bash
python src/training/main.py run_name="my_run_name"
```

All training artifacts, including model checkpoints and logs, will be saved under `logs/my_run_name/`. We use [Hydra](https://hydra.cc/docs/intro/) to manage the training configuration. To change the default configuration, you can either modify the config files under `src/configs/` or override specific config values directly from the command line. For example:

```bash
python src/training/main.py run_name="my_run_name" data.which_split=xview2 data.modalities='[s1, s2_tci]' data.pixels_buffer_around_buildings=2 training.max_epochs=30 model=unet model.encoder_name=resnet50 model.encoder_depth=4
```

# Citation
If you use this code or dataset in your research, please cite the paper as follows:

```
@misc{2511.05461,
Author = {Olivier Dietrich and Merlin Alfredsson and Emilia Arens and Nando Metzger and Torben Peters and Linus Scheibenreif and Jan Dirk Wegner and Konrad Schindler},
Title = {The Potential of Copernicus Satellites for Disaster Response: Retrieving Building Damage from Sentinel-1 and Sentinel-2},
Year = {2025},
Eprint = {arXiv:2511.05461},
}
```
Note: The paper will be presented at the ISPRS Congress 2026 and published in the ISPRS Annals. We will update the citation information once the proceedings are published.

# License
The code in this repository is licensed under the MIT License. See [LICENSE](LICENSE) for details.

xbd-s12

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README