OSM 3D Model

Ten-Step Export Pipeline

1. Area resolution: User selects canvas extent or polygon features. Returns (QgsGeometry, QgsCoordinateReferenceSystem).
2. Study area preparation: Reproject to WGS84 for Overpass, UTM for geometry. compute_study_area() applies shape (circle/rounded/extent/polygon) and area clamp (1–300 ha, default 150 ha). Circle uses pole-of-inaccessibility algorithm. Creates model base by buffering 5 m outward.
3. OSM download: QgsTask background thread fetches from Overpass API with multi-mirror fallback.
4. Parse and build: Iterates every OSM element, clips to study boundary, builds 11 in-memory vector layers with computed attributes.
5. GeoJSON export: Writes each layer to GeoJSON via QgsVectorFileWriter.writeAsVectorFormatV3().
6. Atomic publish: Staging directory → web/data/yerlesim/ with backup on failure. Every GeoJSON validated as valid FeatureCollection.
7. Optional DEM export: gdal:warpreproject, bounded to ~512 px max dimension, output as web/data/dem/mydem.tif.
8. Optional basemap export: QgsMapRendererCustomPainterJob at max 2048 px, transparent PNG, output as web/data/basemap/basemap.png.
9. Manifest: Writes planx_manifest.json with schema, field mappings, theme colours, and viewer defaults.
10. Viewer launch: HTTP server starts on a free port (8120–8139), browser opens http://127.0.0.1:{port}/src/.

Area Sources and Boundary Shapes

Two area sources: Current map extent (canvas) or Selected polygon features (active layer, dissolved via unaryUnion()). Four boundary shapes: Circle (pole of inaccessibility algorithm, largest inscribed circle, clamped to max area, default), Rounded rectangle (corners at ~16% of short side via double-buffer technique), Extent (plain bounding box), and Polygon (exact selected geometry). Area is auto-reprojected to local UTM zone: \(\mathrm{zone} = \lfloor(\lambda + 180)/6\rfloor + 1\), EPSG = 32600 + zone (north) or 32700 + zone (south). Clamped to a configurable maximum (1–300 ha, default 150 ha). Study area inherits a 5 m presentation platform extending beyond the clip boundary with rounded corners.

Overpass API Pipeline with Multi-Mirror and Cache

Queries Overpass API for buildings, highways (including cycleway deduplication), waterways, water areas, green spaces (parks, forests, pitches, cemeteries, parking lots, pedestrian squares), trees, bus stops, benches, street lamps, and waste baskets within the WGS84 bounding box. Uses out body geom; suffix for full geometry with 60-second timeout.

Multi-mirror: Three endpoints tried in order: overpass-api.de, overpass.kumi.systems, overpass.private.coffee. HTTP 429 triggers next mirror. First valid non-empty JSON wins.

Cache: SHA-256 of query string, first 40 chars, stored in %TEMP%/osm_3d_model_cache/. TTL: 7 days (604800 s). Cache validation checks payload structure for corrupt files.

Exported GeoJSON Layers

Layer	Geometry	Key Attributes
OSM Buildings	MultiPolygon	osm_id, building, building_levels, height, roof_shape, roof_height, name
OSM Roads	MultiLineString	osm_id, highway, width, name
OSM Bike lanes	MultiLineString	osm_id, highway, width, name, road_width, side
OSM Greens	MultiPolygon	osm_id, leisure, landuse, natural, amenity, highway, place, name
OSM Waterlines	MultiLineString	osm_id, waterway, width, name
OSM Water areas	MultiPolygon	osm_id, natural, waterway, landuse, name
OSM Trees	Point	osm_id, natural, height
OSM Bus stops	Point	osm_id, highway, name
OSM Benches	Point	osm_id, amenity
OSM Street lights	Point	osm_id, highway
OSM Trash bins	Point	osm_id, amenity

Export uses QgsVectorFileWriter.writeAsVectorFormatV3() with GeoJSON driver and UTF-8. Atomic publish: staging directory → target via Path.replace() with backup on failure. Each GeoJSON validated as a non-empty FeatureCollection.

Three-Tier Fallback with 57 Type-Specific Defaults

1. Parse building:levels or levels tag, rounded to integer, clamped to ≥1.
2. If absent: parse height tag (supports m, cm, km, ft, feet, inch units), divide by 3.0, round, clamp to ≥1.
3. Function-based default from 57-entry dictionary: apartments=4, residential=4, house/detached/terrace=2, bungalow=1, office=5, retail/supermarket/kiosk=1, commercial=3, industrial=1, school=3, university/college=4, hospital=5, church/mosque/temple/synagogue/chapel=1 (cathedral=2), warehouse/hangar/manufacture=1, garage/shed/hut/roof/carport=1, unknown=3.
4. Add roof:levels if present. Final: max(1, base + roof_levels).

Additional columns: height (OSM height tag, float metres), roof_height (OSM roof:height tag), footprint_m2 (computed), gfa_m2 (computed = footprint × building_levels).

Scene Composition and Rendering

The viewer (web/src/app.js, ~9500+ lines) is a single-page Three.js application. Core rendering: WebGLRenderer with antialiasing, PCFSoftShadowMap shadows, ACES filmic tone mapping (exposure 1.32). Post-processing: EffectComposer chain: RenderPass → SSAOPass (optional) → UnrealBloomPass (optional, strength 0.3, radius 0.4, threshold 0.85) → OutputPass. CSS2DRenderer for 2D labels overlaid on 3D.

Lighting: DirectionalLight (intensity 1.38, shadow map 2048x2048, position 200,450,150) + AmbientLight (intensity 1.18). Procedural sky dome with ShaderMaterial (horizon #f6fbff to zenith #9ed8ff), star field (pseudo-random hash) at night.

Camera: PerspectiveCamera (45° FOV, near 1, far 10000). OrbitControls (damping 0.05, max polar angle ~90°). Also supports PointerLockControls for first-person walk mode (WASD, Shift sprint, C crouch). Fit algorithm: distance = max(220, min(maxDim × 2.4, 320, 1800)).

Boot sequence: loadManifest → applyManifestDefaults → loadGeoJson (all layers) → loadProjectDem → loadBaseMapTexture → buildTerrain → buildIslandLayer → building/road/sidewalk/waterline/fences/trees/furniture/traffic layers all rebuilt based on settings → loading screen fades out.

Eight Dockable Panels with Toolbar Tray

Panel	Controls
Dashboard	Scene metrics (building count, green area, avg floors, population, dwellings, vehicles), project metadata, area statistics
Layers	Per-category visibility: buildings, roads, bike lanes, waterways, greens, trees, sidewalks, furniture, cars, cyclists, pedestrians, outside-ROI terrain
Style	Block texture/transparency, road colour/texture, ground texture, terrain tile size, asset theme, tree render mode/variant/height, building mode/facade scale/floor height/roof shape/height/texture, procedural rules (ledges, storefronts, setback, ledge projection), per-category block styles
Scene & Sun	Time-of-day slider (6:00–22:00), solar animation, weather presets, fog density, SSAO/Bloom toggles, traffic/pedestrian density, model base controls, camera bookmarks
Basemap & Texture	Show basemap toggle, opacity, blend mode (Normal/Multiply/Screen/Add/Difference), shadow catching, drape height, brightness/contrast/saturation/tint
Model Studio	Upload custom GLB models per furniture category, library management, tree model pool (random selection), per-category transforms (position/scale/rotation)
Export Studio	PNG/JPEG/WebP/PDF/SVG/HTML stills, WebM/MP4 screen recording (30/60 fps, standard/high/ultra bitrate), clipboard copy
Walk Mode	First-person WASD navigation at pedestrian eye height, Shift sprint, C crouch

All settings are persisted to localStorage under the key planx_3d_city_settings (schema v13) with migration logic. Scene rebuild tokens abort stale rebuilds when settings change rapidly.

Coordinated Palettes for Island, Terrain, Roads, Parks, Water, Roofs

Theme	Character	Island Base
Editorial Paper	Warm ivory; default	#e6dfd3
Plugin Tones	Salmon and grey	#d4c5c0
Tinted Gray Teal	Muted cool grey-green	#c8d6d2
Teal & Salmon	Warm-cool contrast	#c8c0b8
Light Purple & Black	Elegant purple accents	#d8d5e0
Warm Sand & Slate	Natural earth tones	#ddd5c8
Anime (Anime Cel)	Bright cel-shaded pastels	#9fb6c4
Cartoon	Bold primary colours	#c4c8c0
Pixar	Warm creams and oranges	#e8dcc8
Futuristic City	Dark neon, cyan/violet glass	#121420
Classic Era	Vintage sepia, terracotta roofs	#d4c8b0

QGIS parallel styling: qgis_styling.py applies a categorised symbol renderer to buildings (6 function categories), roads (8 hierarchy levels with metric width expressions), and greens (8 categories including water, parking, pedestrian squares). Point layers receive single-symbol renderers. Theme palette is mirrored in both the QGIS project layers and the viewer manifest, ensuring visual consistency across environments.

Canvas-Drawn Textures and Parametric Roofs

Facade textures: Canvas-drawn at runtime using FACADE_RECIPES with a storey-based window grid. Ground floor: shopfronts for Commercial/Mixed-Use (light blue glazing), entrance doors for Residential/Civic. Upper floors: coloured window rectangles, ~48% randomly lit (warm gold, amber/orange, cool blue, soft teal). A separate emissive map texture enables night glow when the day/night cycle enters night mode. 17 procedural roof texture variants (tile patterns, standing seam, shingle, solar, ceramic).

Roof geometry: Flat (with penthouse, HVAC, helipad/solar panels), Pyramid (concave-footprint-aware), Hip (ridge line at mid-height), Gable (ridge along OBB long axis), Shed (single slope).

Building setback: offsetRing() performs iterative vertex offset with hole detection, producing the footprint available for building generation. perBuildingColorVariation adds HSL lightness variation seeded by OSM ID for visual distinction.

Procedural ground textures: Asphalt, water, island block, and fence materials all generated via canvas drawing routines with configurable colours from the active theme.

Road Surfaces, Sidewalks, Bike Lanes, and Animated Traffic

Roads: buildRoadLayer() constructs ribbon meshes along OSM way linestrings, extruded with configurable width per road class (motorway, trunk, primary, secondary, tertiary, residential, service, footway, cycleway). Lane markings: procedural dashed centre/side lines.

Sidewalks: Kerbed sidewalk ribbons on both sides, width scaled by road class. Placed via offset from road centrelines. Streetlights and trees alternate along sidewalks.

Bike lanes: Green ribbon strips offset to road-relative sides, using the OSM cycleway side tag when available.

Traffic: Instanced meshes for cars, vans, buses, and trucks with wheels and lights. Spawned on car-capable roads (excludes footways, cycleways). Frame-rate independent motion controlled by settings.trafficSpeed. Pedestrians keep to sidewalks with sidewalk-relative positioning. Cyclists ride on bike lanes when present. Night mode activates vehicle headlights/taillights and streetlight bulbs.

Optional DEM and Raster Underlay

DEM: Warped via gdal:warpreproject to the model base extent, bounded to ~512 px maximum dimension to keep file size manageable. The viewer loads GeoTIFF via the geotiff.js library and constructs a height-mapped terrain mesh. Terrain resolution is configurable.

Basemap: Rendered via QgsMapRendererCustomPainterJob at max 2048 px to transparent PNG. In the viewer, it appears as a flat underlay beneath the city with configurable opacity, blend mode (Normal/Multiply/Screen/Add/Difference), brightness, contrast, saturation, and tint. Shadow catching can be enabled to project building shadows onto the basemap surface. Drape height controls the vertical offset between basemap and city features.

Stills, Video Recording, and Clipboard

Still formats: PNG, JPEG (quality slider), WebP, PDF (raw PDF 1.4 from JPEG with proper cross-reference table), SVG (embeds JPEG as href), HTML (self-contained page). Size options: viewport, Full HD (1920x1080), QHD (2560x1440), 4K (3840x2160), custom. Video recording: WebM or MP4, 30 or 60 fps, standard/high/ultra bitrate. Filename sanitisation and timestamped generation. Clipboard copy via navigator.clipboard.write().

Atomic Data Publish with Security Headers

Cache: SHA-256 of Overpass query (first 40 chars), stored as JSON in %TEMP%/osm_3d_model_cache/. TTL: 7 days. On-hit validation: corrupt files are discarded and re-fetched. Cache management UI exposes clear-cache button with count and byte-freed report.

HTTP server: ThreadingTCPServer on 127.0.0.1, ports 8120–8139, daemon threads. QuietHandler adds security headers: Cache-Control: no-store, Cross-Origin-Resource-Policy: same-origin, Referrer-Policy: no-referrer, X-Content-Type-Options: nosniff, X-Frame-Options: DENY. Custom MIME types: application/json (.geojson), image/tiff (.tif), image/webp (.webp), application/javascript (.js).