OSM Quick 3D

Boundary Sources and Shapes

Two area sources: Visible map extent (canvas) or Selected features (active layer, dissolved via unaryUnion()). Five boundary shapes: Rectangle (raw bounding box), Rounded rectangle (corners at ~18% of short side via double-buffer technique: buffer(-corner, 12) then buffer(+corner, 12)), Circle (inscribed, radius = min(width, height) / 2, 64 segments), Hexagon (pointy-top orientation, 6 points at 60° intervals starting at −30°, inscribed), and Polygon (user-selected feature, dissolved if multiple).

The area is auto-projected to its local UTM zone via utm_epsg_for(): zone = \(\lfloor(\lambda + 180)/6\rfloor + 1\), clamped 1–60, EPSG = 32600 + zone (north) or 32700 + zone (south). Area is clamped to a configurable maximum in square kilometres (default 6 km²) by shrinking uniformly around the centroid.

Overpass API Pipeline with Multi-Mirror Fallback

The plugin constructs a single Overpass QL query requesting all features within the WGS84 bounding box: ways and relations with building, highway, waterway (river/stream/canal/drain/ditch/riverbank), leisure (park/garden/playground/pitch/nature_reserve/common/dog_park/golf_course), landuse (forest/grass/meadow/recreation_ground/cemetery/reservoir/basin/village_green/orchard/vineyard/farmland/allotments/greenfield), natural (wood/scrub/water/grassland/heath), amenity (parking/marketplace), and place=square; plus nodes for trees, bus stops (also public_transport=platform), benches, street lamps, and waste baskets. The query uses out body geom; for full geometry, with a 60-second timeout.

Multi-mirror fallback: Three endpoints are tried in order (overpass-api.de, overpass.kumi.systems, overpass.private.coffee) with a 10-second additional HTTP read timeout. HTTP 429 (rate-limited) triggers the next mirror. The first endpoint returning valid, non-empty JSON wins. Feedback messages distinguish first query from mirror fallback.

Twelve Layer Types

The plugin creates 12 in-memory vector layers (all Multi* geometry for features potentially split by clipping):

Layer	Geometry	Key Attributes
OSM Buildings	MultiPolygon	osm_id, building, building_levels, height, footprint_m2, gfa_m2, name
OSM Roads	MultiLineString	osm_id, highway, width, name
OSM Bike lanes	MultiLineString	osm_id, highway, width, name
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
OSM Base (optional)	Polygon	Ground plinth extruded from -2 m below terrain to -0.15 m

Each layer is clipped against the valid study boundary (geom.makeValid() if needed, then intersection(clip_boundary)). Multipolygon assembly handles OSM relations with outer/inner ring roles for buildings with courtyards. Geometry classification follows a priority order: tree nodes → water areas → parking lots → paved squares → buildings → roads (with cycleway deduplication) → waterways → greens.

Three-Tier Fallback with 57 Type-Specific Defaults

Height is derived per-building by _building_levels():

1. Parse building:levels or levels tag, rounded to integer, clamped to ≥1. Handles semicolons ("3;4") and unit suffixes ("m", "ft", etc.).
2. If no floor count: parse height tag in metres, divide by 3.0, round, clamp to ≥1.
3. Function-based default from a 57-entry dictionary keyed by OSM building type: apartments=4, residential=4, detached=2, house=2, bungalow=1, office=5, commercial=3, school=3, university=4, hospital=5, church/mosque/temple/synagogue/chapel=1 (cathedral=2), warehouse=1, garage=1, shed=1, unknown=3.
4. Add roof:levels if present. Final: max(1, base + roof_levels).

For the 3D extrusion expression: coalesce(to_real("height"), to_int("building_levels") × 3, 9). The nine-metre default (3 floors at 3 m/floor) serves as the ultimate fallback when neither OSM height tag nor building:levels tag is present and the building type is unrecognised.

Function-Based and Height-Based Schemes

Mode	2D Renderer	Description
By function (OSM use)	QgsCategorizedSymbolRenderer	6 categories: residential, commercial, industrial, civic, worship, other. Static palette per theme.
Graduated by height	Data-defined fill colour	3 classification methods: Continuous (10-step color_rgb(scale_linear(...))), Discrete (5 equal-interval classes), Quantile (5 classes at 20/40/60/80th percentiles).
Soft tinted gray	Data-defined fill	Ramp: #e8e9e8 → #6e746f
Soft tinted warm	Data-defined fill	Ramp: #ede2d4 → #8a7460
Soft teal	Data-defined fill	Ramp: #dbeae7 → #3c7c77
Soft salmon	Data-defined fill	Ramp: #f1ded7 → #b9776a
Soft purple	Data-defined fill	Ramp: #e4dded → #6f5c86
Soft sand	Data-defined fill	Ramp: #ece6d6 → #9a8a63

The height expression reads actual layer values: coalesce(to_real("height"), to_int("building_levels") × 3, 9.0). Break values and 5 interpolated colours are cached per layer ID for performance.

Coordinated Colour Palettes

Theme	Background	Character
Muted Planning	#ffffff	Professional muted european tones; default
Tokyo Cyber	#0a0b10	Dark, neon purples/oranges/cyans on near-black
Editorial Paper	#fdfbf7	Warm ivory paper with sepia-brown accents
Nordic Frost	#f5f7fa	Cool minimal blues on clean white
Monochrome Noir	#1e1e1e	High-contrast grayscale from near-white to near-black
Civic Atlas	#f7f8f2	Clean survey tones: muted greens, blues, greys
Mediterranean Survey	#fbf4e6	Warm sun/sea palette: terracotta, olive, turquoise
Night Print	#11161a	Dark cartographic: gold roads, dark greens, light buildings
Anime Cel	#dff3ff	Bright cartoon pastels: candy pink, lime, sky blue
Desert Dunes	#f6e7c8	Warm arid: sand beige, rust orange, olive green
Pastel Candy	#fff5fb	Soft kawaii: lavender pinks, mint greens, baby blues
Vaporwave	#2a1a4a	Neon retro: deep purple base + hot pink/cyan/mint

Each theme sets: background colour, 6 building function colours, building height ramp (low→high), major road colour (motorway/primary/secondary/tertiary), minor road colour (residential/service/foot/other), greens colour (park/forest/pitch/cemetery/water category), water colour, and tree colour. Theme changes are live: they update the canvas background, recolour all layers, and refresh the 3D view without re-downloading data.

Rule-Based 3D Renderer with Phong Materials

Building 3D extrusion uses QgsRuleBased3DRenderer with per-function or per-height-class child rules:

• Function mode: 6 rules (residential, commercial, industrial, civic, worship, other ELSE) each filtering by OSM building tag via a SQL-like expression: lower("building") IN ('apartments', 'residential', 'house', ...).
• Ramp modes: 10 continuous-height rules or 5 discrete/quantile rules, each filtering by EXTRUSION_EXPRESSION range.
• Each rule has a QgsPolygon3DSymbol with: data-defined extrusion height (QgsProperty.fromExpression(extrusion_expression × scale)), back faces enabled, rendered facades = walls+roofs (value 3), edge rendering (colour #2b3436, width 0.15), altitude clamping to terrain.
• QgsPhongMaterialSettings with per-rule colour, plus data-defined diffuse colour for graduated modes.

Ground base plinth: QgsPolygon3DSymbol extruded from -2.0 m below terrain to -0.15 m (prevents Z-fighting with terrain mesh). Theme-harmonised colour. Data-defined properties for height, extrusion depth, and offset.

Tree canopies: QgsPoint3DSymbol with Sphere shape (2.5 m radius). Transformed with QMatrix4x4().translate(0, 0, 2.5) so spheres rest on the surface. Phong material with theme tree colour.

Managed 3D canvas: Reuses a named Qgs3DMapCanvas ("OSM Quick 3D Scene") via iface.createNewMapCanvas3D(). Flat terrain with configurable tile resolution. Camera: distance = max(width, height, 100) × 1.35, pitch = 45°, zero bearing. Basemap clipping via QgsMapClippingRegion in ClipPainterOnly mode.

Deterministic Procedural Tree Placement

Procedural trees are placed inside wooded green polygons (forest, wood, park, garden, etc.) using a deterministic seeded RNG:

Green Type	Spacing (m2/tree)	Height Range (m)
Forest / Wood	75	7–13
Orchard	110	4–7
Park	170	5–9
Garden	210	4–7
Nature Reserve	180	5–10
Village Green	220	4–8
Recreation Ground	230	4–8
Cemetery	260	5–9
Scrub	280	2.5–4.5
Allotments	320	3–5
Grass	400	3–6
Meadow	440	3–6

RNG: A Knuth MMIX linear congruential generator seeded from the polygon's bounding box coordinates, area, and green type code: seed = (bbox_minX × 73856093) XOR (bbox_minY × 19349663) XOR (area × 83492791) XOR (kind_code × 2654435761), masked to 32 bits. This ensures that re-running the same area produces identical tree placement every time.

Global cap: 500 total trees; per-polygon cap: 130. Target per polygon: min(130, remaining_cap, floor(polygon_area / spacing)). Rejection sampling: random points within the bounding box, accepted if geom_utm.contains(pt), up to 8× target attempts.

QGIS Expressions for Data-Driven Rendering

The plugin uses QGIS expression strings extensively, avoiding per-feature Python loops:

• BUILDING_CLASS_EXPR: Maps 40+ OSM building tag values into 6 categories (residential, commercial, industrial, civic, worship, other) via nested CASE WHEN ... THEN 'category' ... END.
• ROAD_CLASS_EXPR: Maps 18+ highway tag values into 8 hierarchy levels (major, primary, secondary, tertiary, residential, service, foot, other).
• ROAD_WIDTH_M_EXPR: coalesce(to_real("width"), CASE ...) with defaults from 24 m (motorway) down to 2.5 m (footway).
• ROAD_RENDER_WIDTH_EXPR: Clamps road width between 1.5 m and 30 m for rendering.
• GREEN_CLASS_EXPR: Maps leisure/landuse/natural/amenity/highway/place tags into 8 green categories.
• building_color_expression(): Returns either hex-literal CASE expressions (function/discrete modes) or color_rgb(scale_linear(...)) expressions (continuous ramp).
• EXTRUSION_EXPRESSION: coalesce(to_real("height"), to_int("building_levels") × 3, 9) multiplied by height exaggeration factor.

All colour and width properties are applied as data-defined overrides (QgsProperty.fromExpression()) rather than fixed renderer values, enabling live retuning without rebuilding the renderer.

Post-Build Live Retuning

The Theme & Style tab operates on an existing OSM Quick 3D layer group. Controls: group selector, theme combo with preview swatches, six colour pickers (major roads, minor roads, greens, water, trees, scene background), building colour mode, classification method (continuous/discrete/quantile), height exaggeration (0.5–5.0x), building opacity (0–100%), tree canopy size, tree colour, 3D view controls (Open/Refresh/Focus/Close), per-layer 3D visibility checkboxes, scene resolution selector, and basemap clip region management.

The key design pattern: _apply_changes() freezes the canvas, applies all current state in one batch, unfreezes, and refreshes—avoiding intermediate redraws. The 3D view is refreshed via _refresh_3d_view() with delayed retry timers (600 ms, 1500 ms, 3000 ms). A scene info panel shows real-time stats: 3D canvas open/closed, visible layer count, basemap clip status, and resolution.

SHA-256 Disk Cache with 7-Day TTL

Responses are cached as JSON files in %TEMP%/osm_quick_3d_cache/. The cache key is SHA-256 of the full Overpass query string (truncated to 40 hex characters). TTL: 604800 seconds (7 days). On cache miss: fetch from Overpass, write back. On cache hit: validate payload structure; if corrupt, discard and re-fetch. A "Clear cache" button reports files removed and bytes freed. The "Use OSM cache" checkbox allows users to bypass the cache for fresh data.