osm2threejs

Pure-Python Headless 3D City Generator from OpenStreetMap into Three.js WebGL & 3D Assets.

📖 Open Interactive Web Manual (GitLab Pages) • 📦 PyPI Package • 🐛 Issue Tracker

🌟 Overview

osm2threejs is a pure-Python, zero-C-dependency geospatial engine that turns OpenStreetMap data into publication-ready, interactive 60 FPS Three.js 3D WebGL scenes, binary glTF/GLB models, Wavefront OBJ meshes, AutoCAD DXF, and 3D GeoJSON layers.

Designed from the ground up for urban planners, architects, game developers, GIS analysts, and data scientists, osm2threejs runs completely headless across Jupyter Notebooks, Google Colab, FastAPI / Flask microservices, Docker containers, and terminal CLI pipelines.

🔬 Core Capabilities

1. Instant 3D City Generation:
   • Build complete 3D digital twins from place names (from_place("Kadıköy, İstanbul")) or bounding boxes (from_bbox(...)).
2. Procedural Building Extrusions & 6 Roof Topologies:
   • Inferences building heights from building:levels ($levels \times 3.2\text{m}$) or height tags.
   • Generates procedural Flat, Gabled, Hipped, Mansard, Pyramidal, and Dome roof geometries.
3. 12 Curated Visual Themes:
   • Editorial Paper, Cyberpunk Neon, Blueprint Architectural, Anime Pastel, Dark Glow, Warm Sand & Slate, Teal & Salmon, Light Purple & Black, Tinted Gray Teal, Cartoon Stylized, Monochrome Clay, Realistic Satellite.
4. Multi-Format 3D Exporters:
   • 📄 Standalone HTML: Single-file self-contained Three.js 60 FPS viewer with orbit/walk controls, sun elevation slider, and weather effects.
   • 📦 Binary glTF 2.0 (.glb): Ready for direct import into Blender, Unity, Unreal Engine, and WebXR.
   • 📐 Wavefront OBJ + MTL: Universal 3D mesh format.
   • 🗺️ 3D GeoJSON (PolygonZ / LineStringZ): Standard OGC 3D vector geometry.
   • 📐 AutoCAD DXF 3D: 3D Polyline / 3DFace CAD drawing.
5. First-Person Pedestrian Walk Mode:
   • True 1.73m human eye-level navigation with real-time collision detection and keyboard WASD controls.
6. Interactive Jupyter Notebook / Google Colab Widget:
   • Direct inline 3D visualization inside notebook cells via city.show() or _repr_html_().
7. Smart Disk Cache & Multi-Mirror Resilience:
   • SHA-256 disk cache with 7-day TTL and automatic failover across 3 Overpass mirrors.

📦 Installation

pip install osm2threejs

🚀 Quickstart & Python API

1. Build a 3D City from a Place Name

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()

2. Build from Bounding Box Coordinates

import osm2threejs as o3

# Bounding box: (min_lon, min_lat, max_lon, max_lat)
city = o3.from_bbox(
    (27.132, 38.421, 27.155, 38.442),
    theme="Cyberpunk Neon",
    name="Alsancak Downtown",
)

city.to_html("alsancak_cyberpunk.html")

💻 Command Line Interface (CLI)

# 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

🎨 12 Curated Visual Themes

🚶 First-Person Pedestrian Walk Mode

Walk Mode simulates human ground-level perception with realistic eye height (1.73m), dynamic movement velocity (1.8m/s), and real-time obstacle avoidance.

⚡ Performance Benchmarks

🧪 Development & Testing

# Clone the repository
git clone https://gitlab.com/geospacephilo/osm2threejs.git
cd osm2threejs

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run test suite with coverage
pytest tests/ --cov=osm2threejs -v

# Run linter and formatting
ruff check .
ruff format .

📄 Academic Citation

If you use osm2threejs in research, urban planning digital twins, or software applications, please cite:

@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}
}

📜 License

Distributed under the MIT License.