UrbanControlNet

October 15, 2025 · View on GitHub

Introduction

The repository contains the code implementation of the paper: Envisioning Global Urban Development with Satellite Imagery and Generative AI.

Introduction
Installation
Dataset Preparation
Model Training
Model Testing
Model evaluation
Acknowledgements
Citation
License
Contact Us

Installation

Download or clone the repository.

git clone https://github.com/kailaisun/UrbanControlNet.git
cd UrbanControlNet

We recommend using Conda (Miniconda) for installation.

Environment Installation

Create a virtual environment named mambacontrol and activate it.

conda env create -f environment.yaml
conda activate mambacontrol

Dataset Preparation

The dataset is built from publicly available global sources:

Urban boundaries — GHS Urban Centre Database (2023), covering 500 metropolitan areas with 400 m × 400 m grids.
Satellite imagery — Mapbox Static Tiles API.
Population and building data — GHSL P2023A (2020): GHS-BUILT-S, GHS-BUILT-V, GHS-POP.
Environmental constraints — OpenStreetMap, including major roads, water bodies, and railways.

Dataset Download

Download land use, building, and basemap data:

cd dataset
python download_mapbox_tiles.py  
python download_osm_landuse_building.py

Create DEM, hint, and satellite images:

python create_dem_image.py  
python create_hint_image.py  
python create_satellite_image.py

Compute grid density and land use–road metrics:

python compute_grid_density_gee.py  
python create_landuse_road_metrics.py

Model Training

Finetuning

cd Urbancontrolnet
python train_density.py

Finetuning decoder

Set sd_locked = False, then

python train_density.py

Model Testing

Checkpoints:

-We provide two checkpoints (one is finetuned on 100 cities with better performance; another is finetuned on 500 cities with larger coverage):Download

Urban Satelliate Image Generation:

Download checkpoints, make a new folder (checkpoints_density), and change the lines at results_view_loop_density.py:

ckpt_directory = f'./checkpoints_density'
ckpt_epoch_list = ['100'] 
output_file_dir = f'./output_image/city_'

python results_view_loop_density.py

Metric Prediction Model

Training

python prediction_train.py

Model evaluation

For computing metric (e.g., FID, ID, SSIM, FSIM, PSNR, etc.), please see our another repo: Evaluation-Metrics