Street Map

Pick a region on a map and import real-world terrain, roads, trees, buildings, and optional projected imagery into the scene as meshes. The default flow uses OpenStreetMap plus open elevation tiles and does not require API keys.

How It Works

web/ Leaflet picker
  -> drag a bounding box -> witwin.request({ action: "import", bbox, layers })
  ->
controller.py
  -> background import thread
  ->
map_service.py
  -> terrain: AWS open Terrarium elevation tiles -> height-field mesh with UVs
  -> roads: OSM highway ways via Overpass -> ribbon mesh with repeating UVs
  -> trees: OSM natural=tree nodes via Overpass -> low-poly tree layer
  -> buildings: OSM footprints via Overpass -> extruded solids with UVs
  -> optional imagery: raster tile mosaic -> terrain Material.color_map
  ->
SceneObject(mesh_type="Custom").set_mesh_data(verts, faces, normals=..., uvs=...)
  -> meshbin.v1 binary transport -> Three.js PBR viewport

Terrain, roads, trees, and buildings are separate SceneObjects so they can be selected, hidden, assigned materials, or deleted independently.

Data Sources

Layer	Source	Notes
Map picker tiles	tile.openstreetmap.org	Proxied through the backend for desktop CSP compatibility.
Terrain elevation	s3.amazonaws.com/elevation-tiles-prod/terrarium	Terrarium PNG, decoded as (R*256 + G + B/256) - 32768 metres.
Roads	Overpass API	OSM highway ways; width and lanes influence ribbon width.
Trees	Overpass API	OSM natural=tree nodes.
Buildings	Overpass API	OSM height / building:levels, else 6 m.
Optional imagery	server.arcgisonline.com or OSM raster provider	Written under assets/textures/streetmap/... and assigned through the PBR texture-slot material system.

Dependencies

requests, Pillow, shapely, trimesh, mapbox-earcut, numpy.

Usage

Open Tools / Street Map, pan to a place, click Select area, drag a rectangle, choose Terrain / Roads / Buildings / Trees / Imagery, then Import. Progress is reported through notifications. The bounding box limit remains 0.25 degrees per side to keep downloads bounded.

AI Integration

The plugin exposes witwin.streetmap.import_map via contributes.tools. The tool accepts location or explicit bbox, plus terrain, roads, buildings, trees, imagery, and radius_km options. The panel and agent tool both call scene_import.build_and_add, so they create the same layer structure.

Limits

• Buildings use OSM way footprints only; multipolygon relations are still skipped.
• Roads are clipped to the selected bbox and generated as joined ribbons. Lane markings, curbs, and sidewalks are future refinements.
• Trees are a lightweight low-poly layer from OSM point data, not species-aware vegetation.
• Optional imagery is enabled by default and can be turned off per import. Provider terms and availability may still vary by deployment.
• Terrain grid is 128 x 128 by default.
• Overpass requests use a combined query first, then retry alternate endpoints and fall back to per-layer queries on retryable service errors such as 429 or 504. Override endpoints with WT_STREETMAP_OVERPASS_URLS if needed.