osm2threejs

Figure 1: Live vector animation depicting an OpenStreetMap district rising into procedural 3D LOD2 geometry with procedural roofs, synchronized diurnal solar cycles, and dynamic theme switching.

1. Resilient 4-Step Pipeline Architecture

osm2threejs decouples data harvesting from geometric synthesis. It operates completely headless in Jupyter, microservices, cloud containers, and desktop scripts without requiring a graphical display or native geospatial runtime like GDAL/GEOS.

Figure 2: Resilient four-step execution pipeline featuring multi-mirror Overpass API harvesting, SHA-256 disk caching, native tag preservation, and multi-format 3D serialization.

2. Installation & Python API Quickstart

Install the official zero-dependency package directly from PyPI:

pip install osm2threejs

Generate 3D City from Place Name or Coordinates

import osm2threejs as o3

# 1. Generate 3D City Model from place name query
city = o3.from_place("Kadıköy, İstanbul", theme="Editorial Paper", radius_meters=600)

print(f"Buildings : {city.building_count}")
print(f"Roads     : {city.road_count} ({city.total_road_km:.1f} km)")
print(f"Trees     : {city.tree_count}")

# 2. Export Standalone 60 FPS Three.js HTML Viewer (Offline-ready)
city.to_html("kadikoy_3d.html")

# 3. Export 3D Mesh for Blender, Unity, and Unreal Engine
city.to_glb("kadikoy_city.glb")
city.to_obj("kadikoy_city.obj")

# 4. Export 3D GeoJSON & AutoCAD DXF
city.to_geojson("kadikoy_3d.geojson")
city.to_dxf("kadikoy_3d.dxf")

# 5. Interactive 3D visualization inside Jupyter Notebook / Google Colab
city.show()

Command Line Interface (CLI) Master Reference

The SDK ships with a high-throughput CLI tool for terminal automation, batch city generation, and DevOps pipelines:

# 1. Build from place name and open interactive HTML in browser
osm2threejs build --place "Alsancak, İzmir" --theme cyberpunk --out-html city.html --open

# 2. Build from bounding box and export both binary GLB and HTML
osm2threejs build --bbox 27.13,38.42,27.16,38.45 --theme anime --out-glb izmir.glb --out-html izmir.html

# 3. List all 12 registered visual themes
osm2threejs themes

# 4. Geocode place name to bounding box coordinates
osm2threejs geocode "Eiffel Tower, Paris" --radius 800

3. Procedural 3D Building Extrusions & Roof Topologies

Building heights are dynamically inferred using an academic hierarchy of OSM tags:

6 Supported Procedural Roof Topologies

4. Road Network Ribbons & Hierarchy

Roads in OpenStreetMap are centerline linestrings. osm2threejs converts linestrings into metric 3D ribbons using normal offsetting:

5. Public Realm, Water & Tree Scattering

Green spaces, urban parks, rivers, and coastal lines are automatically extracted. Foliage is generated using Poisson-disc stochastic distribution over park polygons, preventing unnatural tree overlaps while maintaining authentic canopy density.

6. Curated 12 Visual Themes Matrix

Every generated city model can be dynamically recoloured using 12 harmonious aesthetic palettes calibrated for academic presentations, cinematic renderings, and game design:

Figure 3: Animated matrix of curated aesthetic palettes transitioning across building walls, roofs, roads, and landscape features.

7. First-Person Pedestrian Walk Mode & Physics

Unlike standard orbit controls, Walk Mode simulates an actual human observer walking through the city streets. The viewpoint is placed at genuine adult human eye height:

Figure 4: First-person pedestrian physics model featuring eye-level camera placement, continuous raycast collision prevention against building walls, and keyboard (WASD / Arrows) street navigation.

8. Multi-Format 3D Exporters

1. Standalone Single-File Three.js HTML Viewer

Produces a zero-dependency, self-contained HTML file bundling geometry, textures, camera controls, sun position slider, and theme dock:

city.to_html("output_viewer.html")

2. Binary glTF 2.0 (.glb) for Blender, Unity & Unreal

Exports optimized binary meshes with separate material slots for walls, roofs, roads, and water:

city.to_glb("output_model.glb")

3. Wavefront OBJ, 3D GeoJSON & AutoCAD DXF

city.to_obj("model.obj")
city.to_geojson("layers_3d.geojson")
city.to_dxf("cad_drawing.dxf")

4. Jupyter Notebook & Google Colab Widget

# Renders responsive 3D WebGL canvas directly inside notebook cell
city.show(height=500)

9. Performance Benchmarks

10. Academic Citation & License

Released under the open-source MIT License.

@software{eminoglu2026osm2threejs,
  author    = {Emino{\u{g}}lu, Yusuf},
  title     = {{osm2threejs: Pure-Python 3D City Generator from OpenStreetMap into Three.js WebGL and 3D Assets}},
  year      = {2026},
  publisher = {PyPI - Python Package Index},
  version   = {0.1.0},
  url       = {https://gitlab.com/geospacephilo/osm2threejs}
}