# zhu-xlab/globalbuildingatlas architecture

> Architecture diagram of the GitHub repository zhu-xlab/globalbuildingatlas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhu-xlab/globalbuildingatlas
- Repository: https://github.com/zhu-xlab/globalbuildingatlas

## Overview

GlobalBuildingAtlas provides global building footprints, estimated heights and LoD1 models. Its documented development workflow covers satellite-image building-map extraction and polygon refinement, height inference, footprint fusion, and LoD1 generation; users can then derive final LoD1 GeoJSON from released polygon and model data. The repository also includes a geospatial dataset/transform library and plotting utilities. Several implementation stages are documented but not sampled, so those links are labeled from the README; source-level edges are limited to relationships visible in excerpts or the SOURCE INDEX.

Main entry points: [`infer_height/utils.py`](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/utils.py) (Inference utilities), [`make_lod1/main.py`](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/make_lod1/main.py) (LoD1 generation), [`im2bf/GBA_Poly/rsipoly/apis/inference.py`](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/apis/inference.py) (Segmentation inference), [`im2bf/GBA_Poly/rsipoly/models/segmentors/encoder_decoder.py`](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/models/segmentors/encoder_decoder.py) (Segmentation model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_poly["Building polygons"]
  node_seg_infer["Segmentation inference<br/>[inference.py]"]
  node_seg_model["Segmentation model<br/>[encoder_decoder.py]"]
  node_poly_simplify["Polygon simplification"]
  node_fusion["Footprint fusion<br/>[main.py]"]
  node_fusion_utils["Source queries and fusion<br/>[utils.py]"]
end

subgraph group_height["Height inference"]
  node_height_infer["Height inference runner<br/>[main.py]"]
  node_height_utils["Inference utilities<br/>[utils.py]"]
  node_height_models["Height models<br/>[adabins_htc.py]"]
  node_unet["UNet baseline<br/>[unet.py]"]
end

subgraph group_lod["LoD1 generation"]
  node_lod1["LoD1 generation<br/>[main.py]"]
  node_final_geojson["LoD1 GeoJSON"]
end

subgraph group_data["Dataset tooling"]
  node_dataset4eo["EO datasets<br/>[_api.py]"]
  node_augment["Image augmentation<br/>[_auto_augment.py]"]
end

subgraph group_viz["Visualization"]
  node_plots["Publication plots"]
end

node_user(("Data user"))
node_imagery(("Satellite imagery"))
node_footprint_sources[("Footprint sources")]
node_released_data[("Released datasets")]
node_plot_user(("Research user"))

node_imagery -.->|"provides imagery"| node_seg_infer
node_seg_infer -->|"runs model"| node_seg_model
node_seg_model -.->|"supports refinement"| node_poly_simplify
node_dataset4eo -.->|"supports training"| node_augment
node_user -.->|"runs fusion"| node_fusion
node_fusion -->|"queries and processes"| node_fusion_utils
node_fusion_utils -->|"queries footprints"| node_footprint_sources
node_imagery -.->|"provides imagery"| node_height_infer
node_height_infer -->|"calls utilities"| node_height_utils
node_height_utils -->|"uses model"| node_height_models
node_height_utils -->|"uses baseline"| node_unet
node_user -.->|"runs generation"| node_lod1
node_released_data -.->|"supplies polygons and models"| node_lod1
node_lod1 -.->|"writes models"| node_final_geojson
node_user -->|"downloads tiles"| node_released_data
node_plot_user -->|"reproduces figures"| node_plots

click node_seg_infer "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/apis/inference.py"
click node_seg_model "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/models/segmentors/encoder_decoder.py"
click node_poly_simplify "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/models/segmentors/poly_simplifier_v15.py"
click node_dataset4eo "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/Dataset4EO/Dataset4EO/datasets/_api.py"
click node_augment "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/Dataset4EO/Dataset4EO/transforms/_auto_augment.py"
click node_fusion "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/fuse_bf/main.py"
click node_fusion_utils "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/fuse_bf/utils.py"
click node_height_infer "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/main.py"
click node_height_utils "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/utils.py"
click node_height_models "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/baselines/adabins_htc.py"
click node_unet "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/baselines/unet.py"
click node_lod1 "https://github.com/zhu-xlab/globalbuildingatlas/blob/main/make_lod1/main.py"
click node_plots "https://github.com/zhu-xlab/globalbuildingatlas/tree/main/make_plots"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_seg_infer,node_seg_model,node_poly_simplify,node_fusion,node_fusion_utils,node_user,node_plot_user toneBlue
class node_height_infer,node_height_utils,node_height_models,node_unet,node_footprint_sources,node_released_data toneAmber
class node_lod1,node_final_geojson toneMint
class node_dataset4eo,node_augment toneRose
class node_plots,node_imagery toneIndigo
```

## Components

### Building polygons

- [Segmentation inference](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/apis/inference.py): `im2bf/GBA_Poly/rsipoly/apis/inference.py`
- [Segmentation model](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/models/segmentors/encoder_decoder.py): `im2bf/GBA_Poly/rsipoly/models/segmentors/encoder_decoder.py`
- [Polygon simplification](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/GBA_Poly/rsipoly/models/segmentors/poly_simplifier_v15.py): `im2bf/GBA_Poly/rsipoly/models/segmentors/poly_simplifier_v15.py`
- [Footprint fusion](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/fuse_bf/main.py): `fuse_bf/main.py`
- [Source queries and fusion](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/fuse_bf/utils.py): `fuse_bf/utils.py`

### Height inference

- [Height inference runner](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/main.py): `infer_height/main.py`
- [Inference utilities](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/utils.py): `infer_height/utils.py`
- [Height models](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/baselines/adabins_htc.py): `infer_height/baselines/adabins_htc.py`
- [UNet baseline](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/infer_height/baselines/unet.py): `infer_height/baselines/unet.py`

### LoD1 generation

- [LoD1 generation](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/make_lod1/main.py): `make_lod1/main.py`
- **LoD1 GeoJSON**

### Dataset tooling

- [EO datasets](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/Dataset4EO/Dataset4EO/datasets/_api.py): `im2bf/Dataset4EO/Dataset4EO/datasets/_api.py`
- [Image augmentation](https://github.com/zhu-xlab/globalbuildingatlas/blob/main/im2bf/Dataset4EO/Dataset4EO/transforms/_auto_augment.py): `im2bf/Dataset4EO/Dataset4EO/transforms/_auto_augment.py`

### Visualization

- [Publication plots](https://github.com/zhu-xlab/globalbuildingatlas/tree/main/make_plots): `make_plots`

### Other components

- **Data user**
- **Satellite imagery**
- **Footprint sources**
- **Released datasets**
- **Research user**

## Connections

- Satellite imagery → Segmentation inference: provides imagery (evidence: `README.md`)
- Segmentation inference → Segmentation model: runs model (evidence: `im2bf/GBA_Poly/rsipoly/apis/inference.py`)
- Segmentation model → Polygon simplification: supports refinement (evidence: `README.md`)
- EO datasets → Image augmentation: supports training (evidence: `README.md`)
- Data user → Footprint fusion: runs fusion (evidence: `README.md`)
- Footprint fusion → Source queries and fusion: queries and processes (evidence: `fuse_bf/main.py`)
- Source queries and fusion → Footprint sources: queries footprints (evidence: `fuse_bf/utils.py`)
- Satellite imagery → Height inference runner: provides imagery (evidence: `README.md`)
- Height inference runner → Inference utilities: calls utilities (evidence: `infer_height/main.py`)
- Inference utilities → Height models: uses model (evidence: `infer_height/utils.py`)
- Inference utilities → UNet baseline: uses baseline (evidence: `infer_height/utils.py`)
- Data user → LoD1 generation: runs generation (evidence: `README.md`)
- Released datasets → LoD1 generation: supplies polygons and models (evidence: `README.md`)
- LoD1 generation → LoD1 GeoJSON: writes models (evidence: `README.md`)
- Data user → Released datasets: downloads tiles (evidence: `README.md`)
- Research user → Publication plots: reproduces figures (evidence: `README.md`)
