# buildings

**Repository Path**: mirrors_microsoft/buildings

## Basic Information

- **Project Name**: buildings
- **Description**: A global building density and height dataset.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Microsoft Building Density & Height Dataset

**Quick links:** [Paper](https://arxiv.org/abs/2511.12104) | [Web visualizer](#open-web-visualizer) | [Setup](#setup) | [Tutorial notebooks](#tutorial-notebooks) | [Datasets](#datasets) | [Model training](#model-training)

Quarterly, global estimates of **building density** and **building height** generated by running machine learning models on Planet's [quarterly PlanetScope basemaps](https://www.planet.com/products/planet-imagery/).

Specifically, we provide:
- **Global public layer (~100 m/px):** 2023 Q4 density & height for the world, distributed as Cloud-Optimized GeoTIFFs (COGs) referenced by a **GeoPackage tile index**.
- **Five high-growth locations (public, ~40 m/px):** quarterly density & height from **2020 Q2 through 2025 Q2** (see table with direct download links below).

For questions or feedback, contact: <a href="mailto:buildings@microsoft.com"><strong>buildings@microsoft.com</strong></a>. We would love to hear from you!


<p align="center">
    <img src="images/building_density.jpg" alt="Building Density & Height Dataset Overview" width="800"/><br/>
    <b>Figure 1.</b> Global building density 2023q4.
</p>


See our [visualizer](https://visualizers.aiforgood.ai/buildings/index.html) for an interactive exploration of the dataset.

<p align="center">
    <img src="images/lusaka_district_density_evolution.gif" alt="Quarterly building density evolution for Lusaka District" width="800"/><br/>
    <b>Figure 2.</b> Quarterly building density evolution for Lusaka District in Zambia.
</p>


---

## Repository Overview

This repository serves **two purposes**:

1. **Data Exploration** (main README): Access and work with our public building density & height datasets through tutorial notebooks and programmatic access.
2. **Model Training** ([TRAINING.md](TRAINING.md)): Reproduce the training pipeline from our paper to train your own model using Planet imagery.

**Most users** will be interested in the data exploration tutorials below. If you want to train the model yourself, see [TRAINING.md](TRAINING.md).

---

## Open web visualizer

[Click here](https://visualizers.aiforgood.ai/buildings/index.html) to explore the dataset in your browser.

## Setup

We provide a small conda environment file to help you get started with programmatic access to the dataset using Python.

```bash
conda env create -f env.yml
conda activate buildings
pip install -r requirements-data.txt
```

Download the tile index GeoPackage to the `data/` directory.
```bash
mkdir -p data/
wget -O data/planet_index.gpkg https://opendata.aiforgood.ai/building-density/tile_index.gpkg
```

## Tutorial notebooks

Two example Jupyter notebooks are included in the `tutorials/` folder to help you get started working with the data:

| Notebook | Description |
| --- | --- |
| [`building-volume-tutorial.ipynb`](tutorials/building-volume-tutorial.ipynb) | Walks through loading tiles via the GeoPackage index, computing aggregate building volume (density * height), and summarizing results for an area of interest. |
| [`working-with-temporal-raster-data.ipynb`](tutorials/working-with-temporal-raster-data.ipynb) | Shows how to identify patterns of urban growth. |

Open them in Jupyter / VS Code after creating the environment to explore typical data access and visualization workflows.

## Datasets

Our data is distributed via direct download links and a tile index for programmatic access. In both cases the files are Cloud-Optimized GeoTIFFs (COGs) with two bands: building density and building height.
- **Band 1** = building density (0 to 1, fraction of pixel covered by buildings)
- **Band 2** = building height (0 to 1, multiply by 100 to get meters)
- **NoData** = −1 in both cases.

### Global data (100 m for 2023 Q4)

We provide a **GeoPackage tile index** referencing Cloud-Optimized GeoTIFFs (COGs) for the entire world at ~100 m/px for the 2023 Q4 quarter of imagery. Use the index to spatially query and stream only the tiles you need: [https://opendata.aiforgood.ai/building-density/tile_index.gpkg](https://opendata.aiforgood.ai/building-density/tile_index.gpkg)

---

### Quarterly high-resolution (40 m) time-series data

The higher resolution quarterly building density & height COGs for five select locations can be directly downloaded via links in the table below. The COGs follow the naming convention: `https://opendata.aiforgood.ai/building-density/locations/{location}/{quarter}_cog.tif`

Where `{location}` is one of: `bamako`, `guangdong_province`, `guatemala_department`, `lusaka_district`, `nakuru` and `{quarter}` is one of: `2020q2` through `2025q2`.

| Quarter | Bamako | Guangdong Province | Guatemala Department | Lusaka District | Nakuru |
|---|---|---|---|---|---|
| 2020q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2020q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2020q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2020q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2020q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2020q2_cog.tif) |
| 2020q3 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2020q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2020q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2020q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2020q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2020q3_cog.tif) |
| 2020q4 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2020q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2020q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2020q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2020q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2020q4_cog.tif) |
| 2021q1 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2021q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2021q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2021q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2021q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2021q1_cog.tif) |
| 2021q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2021q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2021q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2021q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2021q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2021q2_cog.tif) |
| 2021q3 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2021q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2021q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2021q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2021q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2021q3_cog.tif) |
| 2021q4 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2021q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2021q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2021q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2021q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2021q4_cog.tif) |
| 2022q1 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2022q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2022q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2022q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2022q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2022q1_cog.tif) |
| 2022q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2022q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2022q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2022q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2022q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2022q2_cog.tif) |
| 2022q3 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2022q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2022q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2022q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2022q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2022q3_cog.tif) |
| 2022q4 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2022q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2022q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2022q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2022q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2022q4_cog.tif) |
| 2023q1 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2023q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2023q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2023q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2023q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2023q1_cog.tif) |
| 2023q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2023q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2023q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2023q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2023q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2023q2_cog.tif) |
| 2023q3 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2023q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2023q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2023q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2023q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2023q3_cog.tif) |
| 2023q4 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2023q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2023q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2023q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2023q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2023q4_cog.tif) |
| 2024q1 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2024q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2024q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2024q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2024q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2024q1_cog.tif) |
| 2024q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2024q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2024q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2024q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2024q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2024q2_cog.tif) |
| 2024q3 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2024q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2024q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2024q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2024q3_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2024q3_cog.tif) |
| 2024q4 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2024q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2024q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2024q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2024q4_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2024q4_cog.tif) |
| 2025q1 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2025q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2025q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2025q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2025q1_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2025q1_cog.tif) |
| 2025q2 | [COG](https://opendata.aiforgood.ai/building-density/locations/bamako/2025q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guangdong_province/2025q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/guatemala_department/2025q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/lusaka_district/2025q2_cog.tif) | [COG](https://opendata.aiforgood.ai/building-density/locations/nakuru/2025q2_cog.tif) |

---

## Model Training

Want to train the model yourself? See **[TRAINING.md](TRAINING.md)** for:
- Complete training pipeline reproduction
- Data preparation (Overture priors, Google 2.5D labels)
- Training configuration
- Inference on new imagery

**Note:** Requires access to Planet imagery quarterly mosaics.

---

## Citation

Please cite our [paper](https://arxiv.org/abs/2511.12104) if you use this code or dataset:
```
@misc{microsoftbuildings,
      title={TEMPO: Global Temporal Building Density and Height Estimation from Satellite Imagery}, 
      author={Tammy Glazer and Gilles Q. Hacheme and Akram Zaytar and Luana Marotti and Amy Michaels and Girmaw Abebe Tadesse and Kevin White and Rahul Dodhia and Andrew Zolli and Inbal Becker-Reshef and Juan M. Lavista Ferres and Caleb Robinson},
      year={2025},
      eprint={2511.12104},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2511.12104}, 
}
```


---

## Contributing

Contributions to this project are welcome. Please fork the repository and submit a pull request with your changes.

## License

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

The building density & height dataset (all Cloud-Optimized GeoTIFFs and the GeoPackage tile index described above) is licensed under the **Community Data License Agreement (CDLA) Permissive 2.0**. You may use, modify, and redistribute the data under the terms of that license, with appropriate attribution. Full text: https://cdla.dev/permissive-2-0/