https://github.com/prs-eth/ukraine-damage-mapping-tool
An Open-Source Tool for Mapping War Destruction at Scale in Ukraine using Sentinel-1 Time Series
https://github.com/prs-eth/ukraine-damage-mapping-tool
Last synced: about 1 year ago
JSON representation
An Open-Source Tool for Mapping War Destruction at Scale in Ukraine using Sentinel-1 Time Series
- Host: GitHub
- URL: https://github.com/prs-eth/ukraine-damage-mapping-tool
- Owner: prs-eth
- License: mit
- Created: 2024-11-14T13:46:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-26T09:40:33.000Z (over 1 year ago)
- Last Synced: 2025-06-08T19:06:55.447Z (about 1 year ago)
- Language: Jupyter Notebook
- Size: 3.97 MB
- Stars: 21
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# An Open-Source Tool for Mapping War Destruction at Scale in Ukraine using Sentinel-1 Time Series
**Olivier Dietrich*,1**, **Torben Peters1**, **Vivien Sainte Fare Garnot2**, **Valerie Sticher2**, **Thao Ton-That Whelan3**, **Konrad Schindler1**, **Jan Dirk Wegner2**
1 ETH Zurich
2 University of Zurich
3 International Committee of the Red Cross
*Corresponding author: [Olivier Dietrich](mailto:odietrich@ethz.ch)
[](https://arxiv.org/abs/2406.02506)
[](https://olidietrich.users.earthengine.app/view/rapid-damage-assessment-sentinel1)
[](https://olidietrich.users.earthengine.app/view/ukraine-damage-explorer)
[](https://zenodo.org/records/15088349)
## 🇺🇦 Results
The results, including heatmaps and building footprints, can be found [here](https://zenodo.org/records/14811504).
## 🎮 Dashboards
We provide two Google Earth Engine dashboards:
|[](https://olidietrich.users.earthengine.app/view/rapid-damage-assessment-sentinel1)
[Damage Mapping Tool](https://olidietrich.users.earthengine.app/view/rapid-damage-assessment-sentinel1)|[](https://olidietrich.users.earthengine.app/view/ukraine-damage-explorer)
[Ukraine Damage Explorer](https://olidietrich.users.earthengine.app/view/ukraine-damage-explorer)|
|:-:|:-:|
## 🌲 Repository Structure
```
notebooks/ # Jupyter notebooks to reproduce results
├── classification.ipynb
├── country_stats.ipynb
└── evaluation.ipynb
src/ # Source code for data processing, model training, and inference
├── classification/ # Classification script to train and evaluate models
│ ├── dataset.py
│ ├── main.py
│ ├── metrics.py
│ ├── models.py
│ ├── reducers.py
│ └── utils.py
│
├── data/ # Scripts for data processing and handling
│ ├── overture/
│ ├── sentinel1/
│ ├── sentinel2/
│ ├── quadkeys.py
│ ├── unosat.py
│ └── utils.py
│
├── inference/ # Script for inference over entire country
│ ├── dense_inference.py
│ └── full_ukraine.py
│
├── postprocessing/ # Download from drive and postprocess results
│ ├── drive_to_results.py
│ └── utils.py
│
├── utils/ # Utils functions
| ├── gdrive.py
| ├── gee.py
| ├── geo.py
| └── time.py
│
├── constants.py
└── __init__.py
```
## 🛠️ Setup
*This was tested on Ubuntu 22.04 LTS with Python 3.12.7 and 64GB RAM*
### 🐑 Clone the repository
```bash
git clone https://github.com/odietric/ukraine-mapping-tool.git
cd ukraine-mapping-tool
```
### 🐍 Python Environment
To create the environment, run the following command:
```bash
conda create -p ./ukraine_env python=3.12 geopandas gdal -c conda-forge --strict-channel-priority --yes
conda activate ./ukraine_env
python -m pip install uv
python -m uv pip install -r requirements.txt
```
or simply:
```bash
make env
```
### 💾 Data
All project data is publicly available:
- [UNOSAT](https://unosat.org/products/)
Preprocessed UNOSAT labels and AOIs are stored in `data/unosat_labels.geojson` and `data/unosat_aois.geojson`, respectively.
- [Sentinel-1](https://scihub.copernicus.eu/)
Sentinel-1 images are processed in the cloud via Google Earth Engine.
- [Overture Maps Building Footprints](https://docs.overturemaps.org/guides/buildings/#14/32.58453/-117.05154/0/60)
To obtain the preprocessed Overture Maps Building Footprints in Ukraine, you can either download the file `ukraine_buildings.parquet` from the link above and place it in the `data/overture_buildings` folder, or compute it yourself by running the following command:
```bash
bash src/data/overture/download_and_preprocess.sh
```
### 💽 Google Drive Access Configuration
To download the results from Google Drive, you need to configure the Google Drive API and add the files `pydrive_settings.yaml` and `pydrive_credentials.json` to the `secrets` folder.
1. **Create Google API Credentials:**
* Go to Google Cloud Console: API & Services > Credentials > Create Credentials > OAuth client ID > Desktop app.
2. **Download and Configure Credentials:**
* Download the .json credentials file.
* Store the `client_id` and `client_secret` values from this file in pydrive_settings.yaml as follows:
```yaml
client_config_backend: 'settings'
client_config:
client_id:
client_secret:
save_credentials: True
save_credentials_backend: 'file'
save_credentials_file: secrets/pydrive_credentials.json
get_refresh_token: True
oauth_scope:
- "https://www.googleapis.com/auth/drive"
```
* Replace `` and `` with values from your credentials JSON file.
* Replace `/path/to/project/secrets/pydrive_credentials.json` with the full path to the `pydrive_credentials.json` file within your project.\
* The pydrive_credentials.json file will be automatically created upon the first authentication attempt.
3. **Example usage in code:**
```python
from pydrive2.auth import GoogleAuth
from pydrive2.drive import GoogleDrive
from src.constants import SECRETS_PATH
# Initialize authentication
GoogleAuth.DEFAULT_SETTINGS["client_config_file"] = SECRETS_PATH / "pydrive_credentials.json"
gauth = GoogleAuth(settings_file=SECRETS_PATH / "pydrive_settings.yaml")
drive = GoogleDrive(gauth)
```
## Citation
```bibtex
@article{Dietrich2025,
author={Dietrich, Olivier and Peters, Torben and Sainte Fare Garnot, Vivien and Sticher, Valerie and Ton-That Whelan, Thao and Schindler, Konrad and Wegner, Jan Dirk},
title={An open-source tool for mapping war destruction at scale in Ukraine using Sentinel-1 time series},
journal={Communications Earth {\&} Environment},
year={2025},
doi={10.1038/s43247-025-02183-7},
url={https://doi.org/10.1038/s43247-025-02183-7}
}
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.