🗂️ VoxCity Data Sources Guide¶

This tutorial provides a comprehensive overview of all data sources available in VoxCity for building 3D urban voxel models.

Overview¶

VoxCity can pull data from multiple global and regional sources:

Category	Sources
Buildings	OpenStreetMap, Overture, EUBUCCO, Open Building 2.5D, Microsoft Building Footprints
Terrain	DeltaDTM, FABDEM, USGS 3DEP
Land Cover	ESA WorldCover, OpenStreetMap
Vegetation	High Resolution Canopy Height Maps, OpenStreetMap
Imagery	Google Earth Engine (Sentinel-2, etc.)

# Setup
from voxcity.geo.utils import get_rectangle_vertices

# Example area: Marunouchi, Tokyo
center = (139.7671, 35.6812)  # (lon, lat)
rectangle_vertices = get_rectangle_vertices(center, 200, 200)

🏢 Building Data Sources¶

1. OpenStreetMap (OSM)¶

Coverage: Global | Cost: Free | Recommended for: General worldwide use

OpenStreetMap provides crowd-sourced building footprints with optional height information.

from voxcity.download.osm import get_building_data_from_osm

# Download building footprints from OpenStreetMap
gdf_buildings_osm = get_building_data_from_osm(rectangle_vertices)
print(f"Downloaded {len(gdf_buildings_osm)} buildings from OSM")
print(f"Columns: {list(gdf_buildings_osm.columns)}")
gdf_buildings_osm.head()

2. Overture Maps¶

Coverage: Global | Cost: Free | Recommended for: High-quality building data

Overture Maps Foundation provides curated building data from multiple sources.

from voxcity.download.overture import get_building_data_from_overture

# Download building footprints from Overture
gdf_buildings_overture = get_building_data_from_overture(rectangle_vertices)
print(f"Downloaded {len(gdf_buildings_overture)} buildings from Overture")
gdf_buildings_overture.head()

3. EUBUCCO v0.1¶

Coverage: Europe only | Cost: Free | Recommended for: European cities

EUBUCCO provides building footprints with height information for European countries.

# EUBUCCO example (European location)
# Note: This only works for European cities
# center_europe = (13.4050, 52.5200)  # Berlin
# rectangle_vertices_europe = get_rectangle_vertices(center_europe, 200, 200)
# gdf_buildings_eubucco = get_building_data_from_eubucco(rectangle_vertices_europe)

print("EUBUCCO is available for European cities only.")
print("Supported countries: Austria, Belgium, Czechia, Denmark, Finland, France,")
print("Germany, Italy, Netherlands, Poland, Slovakia, Slovenia, Spain, Sweden, Switzerland")

4. Open Building 2.5D Temporal¶

Coverage: Global | Cost: Free | Recommended for: Building height estimates

Provides estimated building heights derived from satellite imagery.

# Open Building 2.5D requires Google Earth Engine authentication
# from voxcity.download.gee import get_building_data_from_open_building_2_5d_temporal

# gdf_buildings_ob25d = get_building_data_from_open_building_2_5d_temporal(rectangle_vertices)
print("Open Building 2.5D requires Google Earth Engine authentication.")
print("See: https://developers.google.com/earth-engine/guides/python_install")

🏔️ Terrain Data Sources (DEM/DTM)¶

1. DeltaDTM¶

Coverage: Global | Resolution: 30m | Recommended for: General use

Global Digital Terrain Model derived from multiple sources.

from voxcity.download.dem import get_dem_from_deltadtm

# Download terrain data from DeltaDTM
dem_deltadtm = get_dem_from_deltadtm(rectangle_vertices, meshsize=1.0)
print(f"DeltaDTM shape: {dem_deltadtm.shape}")
print(f"Elevation range: {dem_deltadtm.min():.1f}m to {dem_deltadtm.max():.1f}m")

2. FABDEM¶

Coverage: Global | Resolution: 30m | Recommended for: Building-free terrain

FABDEM removes buildings and trees from Copernicus DEM to provide bare-earth elevation.

# FABDEM requires registration at https://data.bris.ac.uk/data/
# from voxcity.download.dem import get_dem_from_fabdem
# dem_fabdem = get_dem_from_fabdem(rectangle_vertices, meshsize=1.0)
print("FABDEM requires authentication.")

3. USGS 3DEP¶

Coverage: USA only | Resolution: 1m-10m | Recommended for: High-resolution US terrain

# USGS 3DEP - USA only
# from voxcity.download.dem import get_dem_from_usgs_3dep
# center_us = (-122.4194, 37.7749)  # San Francisco
# rectangle_vertices_us = get_rectangle_vertices(center_us, 200, 200)
# dem_usgs = get_dem_from_usgs_3dep(rectangle_vertices_us, meshsize=1.0)
print("USGS 3DEP provides high-resolution elevation data for the USA.")

🌍 Land Cover Data Sources¶

ESA WorldCover¶

Coverage: Global | Resolution: 10m | Recommended for: Land use classification

ESA WorldCover provides global land cover classification at 10m resolution.

from voxcity.download.gee import get_land_cover_data_from_esaworldcover

# Download land cover from ESA WorldCover
# Note: Requires Google Earth Engine authentication
# lc_grid = get_land_cover_data_from_esaworldcover(rectangle_vertices, meshsize=1.0)

print("ESA WorldCover Classes:")
print("10: Tree cover | 20: Shrubland | 30: Grassland")
print("40: Cropland | 50: Built-up | 60: Bare/sparse vegetation")
print("70: Snow and ice | 80: Permanent water | 90: Herbaceous wetland")
print("95: Mangroves | 100: Moss and lichen")

🌳 Vegetation / Canopy Height Data¶

High Resolution 1m Global Canopy Height Maps¶

Coverage: Global | Resolution: 1m | Recommended for: Detailed tree heights

This dataset provides high-resolution canopy height estimates from satellite imagery.

from voxcity.download.gee import get_canopy_height_from_high_resolution_canopy_height_maps

# Download canopy height data
# Note: Requires Google Earth Engine authentication
# chm_grid = get_canopy_height_from_high_resolution_canopy_height_maps(rectangle_vertices, meshsize=1.0)

print("High Resolution Canopy Height Maps provides 1m resolution tree heights.")

🔧 Using Data Sources with `get_voxcity()`¶

The easiest way to use data sources is with the get_voxcity() function. It automatically combines multiple sources:

from voxcity.generator import get_voxcity

# Specify data sources in source_dict
source_dict = {
    'building': 'osm',           # Options: 'osm', 'overture', 'eubucco', 'open_building_2.5d_temporal', 'microsoft_building'
    'dem': 'deltadtm',           # Options: 'deltadtm', 'fabdem', 'usgs_3dep'
    'land_cover': 'esaworldcover',  # Options: 'esaworldcover', 'osm'
    'tree': 'high_resolution_canopy_height_maps',  # Options: 'high_resolution_canopy_height_maps', 'osm'
}

# Generate 3D voxel model using specified sources
# city = get_voxcity(
#     rectangle_vertices,
#     source_dict=source_dict,
#     meshsize=1.0
# )
print("Available building sources:", ['osm', 'overture', 'eubucco', 'open_building_2.5d_temporal', 'microsoft_building'])
print("Available DEM sources:", ['deltadtm', 'fabdem', 'usgs_3dep'])
print("Available land cover sources:", ['esaworldcover', 'osm'])
print("Available tree sources:", ['high_resolution_canopy_height_maps', 'osm'])

📊 Data Source Comparison Table¶

Source	Coverage	Resolution	Authentication	Best Use Case
OSM	Global	Variable	None	General buildings worldwide
Overture	Global	Variable	None	High-quality curated data
EUBUCCO	Europe	~10m	None	European cities with heights
Open Building 2.5D	Global	~1m	GEE	Building height estimates
Microsoft Building	Global	Variable	None	Building footprints
DeltaDTM	Global	30m	None	General terrain
FABDEM	Global	30m	Registration	Bare-earth terrain
USGS 3DEP	USA	1-10m	None	High-res US terrain
ESA WorldCover	Global	10m	GEE	Land use classification
Canopy Height Maps	Global	1m	GEE	Tree height mapping

GEE = Google Earth Engine authentication required

🔑 Google Earth Engine Setup¶

Some data sources require Google Earth Engine authentication:

Create a GEE account at https://earthengine.google.com/
Install the earthengine-api: pip install earthengine-api
Authenticate: earthengine authenticate

See the official guide for details.

📚 Next Steps¶

Now that you understand the data sources, explore these tutorials:

demo_quickstart.ipynb - Quick start with default sources
demo_basic.ipynb - Complete workflow with all options
demo_view.ipynb - Green View Index analysis
demo_solar.ipynb - Solar irradiance simulation

# Setup
from voxcity.generator import get_voxcity, auto_select_data_sources

# Example area for demonstrations
rectangle_vertices = [
    (139.760, 35.680),  # Tokyo area
    (139.760, 35.690),
    (139.770, 35.690),
    (139.770, 35.680)
]

🏗️ Building Data Sources¶

Primary Building Sources¶

Source	Coverage	Heights	Best For
`OpenStreetMap`	Global	Partial	Most locations (default)
`Overture`	Global	Partial	Alternative global coverage
`EUBUCCO v0.1`	Europe	Yes	European cities
`Open Building 2.5D Temporal`	Africa, Asia, Latin America	Yes	Developing regions
`Microsoft Building Footprints`	USA, Europe, Australia	No	Footprint accuracy
`Local file`	Any	Varies	Custom data

Complementary Building Sources¶

When the primary source lacks height data, use a complementary source:

Source	Provides
`Open Building 2.5D Temporal`	Heights from satellite imagery
`Microsoft Building Footprints`	Additional footprints
`England 1m DSM - DTM`	Heights from DSM-DTM difference
`Netherlands 0.5m DSM - DTM`	Heights from DSM-DTM difference
`None`	Use default height

# Example: Using OpenStreetMap with complementary source
city_osm = get_voxcity(
    rectangle_vertices,
    meshsize=10,
    building_source='OpenStreetMap',
    building_complementary_source='None',
    land_cover_source='OpenStreetMap',
    canopy_height_source='Static',
    dem_source='Flat',
    output_dir='output/datasource_demo/osm'
)
print(f"Building grid shape: {city_osm.buildings.heights.shape}")

🌿 Land Cover Sources¶

Land cover classification determines what’s on the ground surface.

Source	Resolution	Coverage	Classes
`OpenStreetMap`	Vector	Global	Roads, grass, water, etc.
`Urbanwatch`	5m	USA	Urban-specific
`OpenEarthMapJapan`	High	Japan	Detailed classification
`ESA WorldCover`	10m	Global	11 classes
`ESRI 10m Annual Land Cover`	10m	Global	10 classes
`Dynamic World V1`	10m	Global	9 classes, time-series

# Land cover classes used in VoxCity
from voxcity.utils.lc import get_land_cover_classes

# OpenStreetMap land cover mapping
osm_classes = {
    0: "Unclassified",
    1: "Building",
    2: "Road/pavement",
    3: "Grass/vegetation",
    4: "Tree",
    5: "Water",
    6: "Railway",
    7: "Bare soil"
}

print("Land cover classes (OSM):")
for code, name in osm_classes.items():
    print(f"  {code}: {name}")

🌳 Canopy Height Sources¶

Tree canopy heights for vegetation modeling.

Source	Resolution	Coverage	Notes
`High Resolution 1m Global Canopy Height Maps`	1m	Global	Meta/WRI, most accurate
`ETH Global Sentinel-2 10m Canopy Height (2020)`	10m	Global	Good alternative
`OpenStreetMap`	Vector	Global	Tree locations only
`Static`	N/A	Any	Fixed height (default 10m)

# Canopy height parameters
canopy_params = {
    "min_canopy_height": 2.0,      # Ignore trees shorter than this (meters)
    "trunk_height_ratio": 0.59,    # Trunk height / total height
    "static_tree_height": 10.0     # Default height for 'Static' source
}

print("Canopy configuration options:")
for param, value in canopy_params.items():
    print(f"  {param}: {value}")

⛰️ DEM (Digital Elevation Model) Sources¶

Terrain elevation data for accurate 3D representation.

Source	Resolution	Coverage	Notes
`DeltaDTM`	~30m	Global	Good default
`FABDEM`	~30m	Global	Forest/building removed
`USGS 3DEP 1m`	1m	USA	Highest quality for USA
`England 1m DTM`	1m	England	High resolution
`DEM France 1m`	1m	France	High resolution
`DEM France 5m`	5m	France	Good coverage
`Netherlands 0.5m DTM`	0.5m	Netherlands	Very high resolution
`AUSTRALIA 5M DEM`	5m	Australia	National coverage
`Flat`	N/A	Any	No terrain (z=0)

# DEM parameters
dem_params = {
    "dem_interpolation": True,  # Smooth DEM when meshsize < DEM resolution
    "flat_dem": 0.0            # Elevation for 'Flat' source
}

print("DEM configuration options:")
for param, value in dem_params.items():
    print(f"  {param}: {value}")

🤖 Automatic Data Source Selection¶

VoxCity can automatically select the best data sources based on location:

# Check what sources would be auto-selected for different locations

locations = {
    "Tokyo, Japan": [(139.76, 35.68), (139.76, 35.69), (139.77, 35.69), (139.77, 35.68)],
    "New York, USA": [(-74.02, 40.70), (-74.02, 40.71), (-74.00, 40.71), (-74.00, 40.70)],
    "London, UK": [(-0.13, 51.50), (-0.13, 51.51), (-0.11, 51.51), (-0.11, 51.50)],
    "Lagos, Nigeria": [(3.38, 6.45), (3.38, 6.46), (3.40, 6.46), (3.40, 6.45)],
}

print("Auto-selected data sources by location:\n")
for city_name, coords in locations.items():
    sources = auto_select_data_sources(coords)
    print(f"📍 {city_name}")
    for source_type, source_name in sources.items():
        print(f"   {source_type}: {source_name}")
    print()

🔧 Custom Configuration Examples¶

Example 1: High-Resolution USA City¶

# High-resolution configuration for US cities
usa_config = {
    "building_source": "OpenStreetMap",
    "building_complementary_source": "Microsoft Building Footprints",
    "land_cover_source": "Urbanwatch",
    "canopy_height_source": "High Resolution 1m Global Canopy Height Maps",
    "dem_source": "USGS 3DEP 1m"
}

print("USA high-resolution configuration:")
for key, value in usa_config.items():
    print(f"  {key}: {value}")

Example 2: European City with EUBUCCO¶

# Configuration for European cities with EUBUCCO building data
eu_config = {
    "building_source": "EUBUCCO v0.1",  # European building footprints with heights
    "building_complementary_source": "None",
    "land_cover_source": "ESA WorldCover",
    "canopy_height_source": "High Resolution 1m Global Canopy Height Maps",
    "dem_source": "FABDEM"
}

print("European city configuration (EUBUCCO):")
for key, value in eu_config.items():
    print(f"  {key}: {value}")

Example 3: Developing Region with Google Open Buildings¶

# Configuration for Africa/Asia/Latin America
developing_config = {
    "building_source": "OpenStreetMap",
    "building_complementary_source": "Open Building 2.5D Temporal",  # Google heights
    "land_cover_source": "ESA WorldCover",
    "canopy_height_source": "High Resolution 1m Global Canopy Height Maps",
    "dem_source": "DeltaDTM"
}

print("Developing region configuration:")
for key, value in developing_config.items():
    print(f"  {key}: {value}")

Example 4: Japan with OpenEarthMapJapan¶

# Optimized configuration for Japan
japan_config = {
    "building_source": "OpenStreetMap",
    "building_complementary_source": "None",
    "land_cover_source": "OpenEarthMapJapan",  # High-quality Japanese land cover
    "canopy_height_source": "High Resolution 1m Global Canopy Height Maps",
    "dem_source": "DeltaDTM"  # or 'FABDEM'
}

print("Japan configuration:")
for key, value in japan_config.items():
    print(f"  {key}: {value}")

📁 Using Local Files¶

You can use your own geospatial files as data sources:

# Example: Using local GeoPackage file for buildings
local_config = {
    "building_source": "Local file",
    "building_path": "path/to/buildings.gpkg",  # GeoPackage, Shapefile, or GeoJSON
    # Building GDF should have columns: 'geometry' (Polygon), 'height' (optional)
}

print("Local file requirements:")
print("  Supported formats: GeoPackage (.gpkg), Shapefile (.shp), GeoJSON (.geojson)")
print("  Required columns: 'geometry' (Polygon/MultiPolygon)")
print("  Optional columns: 'height', 'min_height', 'id'")

🌐 Google Earth Engine Authentication¶

Some data sources require Google Earth Engine. Here’s how to authenticate:

# Google Earth Engine authentication
# Run this if you plan to use GEE-based sources

# Option 1: Notebook authentication (Google Colab)
# import ee
# ee.Authenticate()
# ee.Initialize(project='your-gcp-project-id')

# Option 2: Command line authentication
# !earthengine authenticate

# GEE-dependent sources:
gee_sources = [
    "Open Building 2.5D Temporal",
    "England 1m DSM - DTM",
    "Netherlands 0.5m DSM - DTM",
    "High Resolution 1m Global Canopy Height Maps",
    "ETH Global Sentinel-2 10m Canopy Height (2020)",
    "Urbanwatch",
    "ESA WorldCover",
    "ESRI 10m Annual Land Cover",
    "Dynamic World V1",
    "USGS 3DEP 1m",
    "DeltaDTM",
    "FABDEM",
]

print("Sources requiring Google Earth Engine:")
for src in gee_sources:
    print(f"  • {src}")

📚 Summary¶

Quick Reference¶

Location	Buildings	Land Cover	DEM
USA	OSM + MBFP	Urbanwatch	USGS 3DEP
Europe	OSM/EUBUCCO	OSM/ESA	FABDEM
Japan	OSM	OpenEarthMapJapan	DeltaDTM
Africa/Asia/LatAm	OSM + OB 2.5D	ESA WorldCover	DeltaDTM
Global default	OSM	OSM	DeltaDTM

Tips¶

Start with auto-selection: Let VoxCity choose sources, then customize
Check GEE authentication: Many high-quality sources need Earth Engine
Match resolution: Use higher-res DEM when meshsize is small (<5m)
Local files: Great for custom datasets or offline work