🏙️ VoxCity Quick Start Guide¶

Welcome to VoxCity — a Python package for generating and analyzing 3D voxel-based urban models.

This notebook will get you up and running in under 5 minutes with automatic data source selection.

What You’ll Learn¶

✅ Install VoxCity
✅ Define your area of interest
✅ Generate a 3D city model automatically
✅ Visualize the result
✅ Export to common formats

📦 Step 1: Installation¶

Run the cell below to install VoxCity. Skip if already installed.

# Uncomment and run if you need to install VoxCity
# %pip install voxcity

🌍 Step 2: Define Your Area of Interest¶

VoxCity needs a rectangular area defined by 4 corner coordinates in (longitude, latitude) format.

Here’s an example for Tokyo, Japan. Replace with your own coordinates!

# Define the area of interest as a rectangle
# Format: (longitude, latitude) for each corner
rectangle_vertices = [
    (139.760, 35.680),  # Southwest corner
    (139.760, 35.690),  # Northwest corner
    (139.770, 35.690),  # Northeast corner
    (139.770, 35.680)   # Southeast corner
]

# Set the voxel resolution in meters
meshsize = 5  # 5m resolution - smaller = more detail but slower

print(f"Area defined: ~{abs(rectangle_vertices[2][0] - rectangle_vertices[0][0]) * 111320:.0f}m x {abs(rectangle_vertices[1][1] - rectangle_vertices[0][1]) * 111320:.0f}m")
print(f"Voxel size: {meshsize}m")

💡 Tip: Interactive Area Selection¶

If you want to draw a rectangle on an interactive map instead:

from voxcity.geoprocessor.draw import draw_rectangle_map_cityname

cityname = "Tokyo, Japan"
m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)
m  # Display the map, then draw a rectangle

🚀 Step 3: Generate the 3D City Model¶

VoxCity will automatically select the best data sources for your location!

from voxcity.generator import get_voxcity

# Generate the city model with AUTO data source selection
city = get_voxcity(
    rectangle_vertices,
    meshsize=meshsize,
    output_dir='output/quickstart'  # Where to save intermediate files
)

# Show what we got
print(f"\n✅ City model generated!")
print(f"   Voxel grid shape: {city.voxels.classes.shape}")
print(f"   (rows × cols × height levels)")

What’s in the VoxCity object?¶

The city object contains several data grids:

Attribute	Description
`city.voxels.classes`	3D voxel grid (0=air, 1=ground, 2=tree, 3=building)
`city.buildings.heights`	2D grid of building heights
`city.buildings.ids`	2D grid of building IDs
`city.land_cover.classes`	2D land cover classification
`city.dem.elevation`	2D digital elevation model
`city.tree_canopy.top`	2D canopy height grid

# Quick look at the data
import numpy as np

voxels = city.voxels.classes
print("Voxel statistics:")
print(f"  Air cells:      {np.sum(voxels == 0):,}")
print(f"  Ground cells:   {np.sum(voxels == 1):,}")
print(f"  Tree cells:     {np.sum(voxels == 2):,}")
print(f"  Building cells: {np.sum(voxels == 3):,}")

👁️ Step 4: Visualize the 3D Model¶

from voxcity.visualizer import visualize_voxcity

# Static visualization (saves an image)
visualize_voxcity(
    city,
    mode="static",  # 'static' for image, 'interactive' for 3D viewer
    output_directory="output/quickstart"
)

Interactive 3D Visualization¶

For an interactive view you can rotate and zoom:

# Interactive visualization using Plotly
# (Requires plotly: pip install plotly)
fig = visualize_voxcity(city, mode="interactive", show=False, return_fig=True)
fig.show()

💾 Step 5: Export the Model¶

VoxCity supports multiple export formats for different use cases.

# Export to OBJ (for Blender, Rhino, 3D viewers)
from voxcity.exporter.obj import export_obj

export_obj(city, output_dir='output/quickstart', file_name='my_city')
print("✅ Exported: output/quickstart/my_city.obj")

# Export to MagicaVoxel VOX format (for voxel art editors)
from voxcity.exporter.magicavoxel import export_magicavoxel_vox

export_magicavoxel_vox(city, "output/quickstart")
print("✅ Exported: output/quickstart/voxcity.vox")

# Save/Load VoxCity object for later use
from voxcity.generator import save_voxcity, load_voxcity

save_voxcity('output/quickstart/city.pkl', city)
print("✅ Saved city object")

# Later, load it back:
# city = load_voxcity('output/quickstart/city.pkl')

🎉 You’re Done!¶

You’ve successfully:

Generated a 3D voxel city model
Visualized it in 2D and 3D
Exported it to multiple formats

What’s Next?¶

Explore more advanced features in other tutorials:

Notebook	Description
`demo_basic.ipynb`	Complete guide to all data sources and options
`demo_view.ipynb`	Green View Index & Sky View Index analysis
`demo_solar.ipynb`	Solar irradiance simulation
`demo_landmark.ipynb`	Landmark visibility analysis
`demo_3d_visualization.ipynb`	Advanced 3D visualization options
`demo_envi-met.ipynb`	Export for ENVI-met CFD simulations