[general]
name=3D OSM Model
qgisMinimumVersion=3.28
description=Pick an area, download OpenStreetMap data, and instantly view it as a procedural 3D city in the browser.
version=0.13.0
author=Yusuf Eminoglu
email=yusuf.eminoglu@deu.edu.tr
about=3D OSM Model is a fast, single-button companion to PlanX 3D City. Select a small area (up to ~300 ha), and the plugin downloads OpenStreetMap buildings, roads, cycleways, waterways, lakes and ponds, greens, trees and street furniture (bus stops, benches, lamps, bins) using their native OSM tags, builds the study boundary as the shape you choose - inscribed circle, rounded rectangle, rectangle or the exact selected polygon (the model base extends 5 m beyond it with softly rounded corners), and opens an interactive, English-only Three.js 3D city viewer. An easy "Web theme" picker recolours the city content - buildings, roads, base and roofs - with a handful of ready palettes (salmon and grey, gray-teal, teal and salmon, light purple, warm sand), leaving the viewer chrome untouched. A basemap layer (raster, satellite/XYZ tiles or vector) can optionally be draped under the city and restyled live - opacity, blend mode, brightness, contrast, saturation and tint - in the viewer's Basemap and Texture panel; procedural kerb sidewalks line both sides of every street. Roads, sidewalks and bike lanes are drawn procedurally with lane markings; pedestrians keep to the sidewalks and cars to the carriageway; buildings are coloured by OSM function and default to a function-aware floor count when no level data exists. An external DEM can optionally be added. Built on the PlanX 3D City viewer engine at Dokuz Eylul University, Department of City and Regional Planning.
tracker=https://github.com/YusufEminoglu/osm_3d_model/issues
repository=https://github.com/YusufEminoglu/osm_3d_model
category=Web
homepage=https://github.com/YusufEminoglu/osm_3d_model
tags=osm,openstreetmap,3d city,three.js,procedural,massing,urban planning,geojson,QGIS
icon=icons/icon.png
qgisMaximumVersion=4.99
experimental=False
deprecated=False
hasProcessingProvider=no
plugin_dependencies=
license=MIT
changelog=
    3D OSM Model 0.13.0 - Water areas: lakes, ponds, rivers and the sea.
        - Lakes, ponds, reservoirs, river polygons (riverbanks) and bays are now downloaded from OpenStreetMap and drawn as flat blue water surfaces, clipped to the study boundary. Previously only linear waterways (streams and narrow rivers) were shown, so any river, lake or coastline mapped as an area - which is the common case - was silently dropped.
        - The export result message no longer shows "r=None m" for rectangle or polygon boundaries; it now reports the footprint size, and water areas are included in the waterways total.
    3D OSM Model 0.12.3 - New, clearer plugin icon.
        - The toolbar and Plugin Manager icon is now a crisp PNG (an isometric 3D city on a salmon tile) that renders reliably, replacing the SVG that could show blank in some QGIS builds.
    3D OSM Model 0.12.2 - Smarter, more urban roof shapes.
        - Buildings no longer get a pyramid roof by default. Houses and other small, low buildings get a pitched (gable) roof, while apartments, commercial, industrial, civic blocks and larger buildings get a flat roof - which reads far more like a real city. An explicit OSM roof shape, or a roof shape you set per function in the Style dock, still takes priority.
    3D OSM Model 0.12.1 - Realistic road widths by class.
        - Roads are now drawn at a width that matches their OSM class - motorways and primary roads read wider than residential streets, service ways and footpaths - instead of every road being a flat 8 m. The "Road width" control still works as a global multiplier.
        - When a road carries an explicit OSM width tag, that real carriageway width is now used (it was previously ignored).
        - Pedestrians now keep to the sidewalk edge of the actual road they are on, so they stay off wide roads and hug narrow ones correctly.
    3D OSM Model 0.12.0 - Faster re-runs and more complete OSM coverage.
        - OSM downloads are now cached on disk for a week, keyed by the exact area query. Re-running the same area (or just nudging a shape/theme option) reuses the cached data and skips the network entirely, which dodges the public Overpass API's frequent rate limiting.
        - Multipolygon buildings, parks, forests and other green areas mapped as OSM relations are now imported. Previously only simple closed ways were read, so large building complexes (with inner courtyards) and relation-mapped parks/woods were silently dropped.
        - New "Clear OSM download cache" button in the dialog's Advanced section forces a fresh fetch when the area's OSM data has changed.
    3D OSM Model 0.11.3 - Smaller model base buffer.
        - The model base now extends 5 m beyond the study boundary instead of 10 m, for a tighter platform margin around the city.
    3D OSM Model 0.11.2 - Consistent traffic and pedestrian speed (frame-rate independent).
        - Cars, cyclists and pedestrians moved too slowly (almost stopped) on some machines because their motion was tied to the frame rate. It is now frame-rate independent (calibrated to 60 fps), so their speed stays consistent regardless of the frame rate.
        - The kerb sidewalks no longer cast shadows (a flat ground strip casts none anyway), which restores some frame rate.
    3D OSM Model 0.11.1 - Road-class sidewalk widths.
        - Sidewalk width now scales with the OSM road class, clamped to a realistic 0.5 to 2.5 m (wide along main and pedestrian streets, narrow along service ways and paths), instead of a fixed 1.6 m on every road.
    3D OSM Model 0.11.0 - Two-sided kerb sidewalks and a stylable basemap underlay.
        - Sidewalks now render as raised kerbs on BOTH sides of every road, with a double-sided material so a road's geometry winding can no longer hide the sidewalk on one side. They are slightly wider and lighter for clarity.
        - New optional basemap: pick a layer (raster, XYZ/satellite tiles, or vector) in the dialog's Advanced section and it is rendered to an image and draped under the city, clipped to the study boundary.
        - New "Basemap and Texture" panel in the viewer styles the basemap live: opacity, blend mode (Normal, Multiply, Screen, Add, Difference), brightness, contrast, saturation, tint, drape height, and building-shadow catching.
    3D OSM Model 0.10.2 - Critical viewer fix for returning users.
        - Fixed a crash ("persisted is not defined") that left the browser viewer stuck on an empty "Waiting for project metadata" scene for anyone whose browser had saved viewer settings from a previous session. The colour-theme code added in 0.10.0 referenced a variable scoped to a try block; it is now function-scoped. A first-time browser was not affected, which is why earlier testing missed it.
    3D OSM Model 0.10.1 - Themes now colour the buildings too.
        - Each non-default colour theme now uses a set of light, tintable facades (limestone, stucco, glass, off-white) so the building colour palette shows clearly, with slightly more saturated building tints. The default Plugin tones theme is unchanged.
    3D OSM Model 0.10.0 - Easy colour themes for the 3D city.
        - New "Web theme" option in the dialog sets the colour palette of the exported 3D city: Plugin tones (salmon and grey, the default), Tinted gray and teal, Teal and salmon, Light purple and soft black, or Warm sand and slate.
        - Themes recolour the city content only - buildings, roads, the base/island and its skirt, greens and the roof texture - and never the viewer's toolbar or panels.
        - The chosen theme is written into the export and applied automatically when the browser viewer opens; re-opening the same export keeps any manual colour tweaks you made in the Style dock.
        - The viewer's building palette is now theme-driven, with the default theme reproducing the previous muted greys exactly.
    3D OSM Model 0.9.0 - Choose your study-area boundary shape.
        - New "Boundary shape" option in the dialog: inscribed circle (default, the classic look), rounded rectangle, rectangle (extent), or the exact selected polygon. The bundled Three.js viewer renders any of them; earlier versions always used the inscribed circle.
        - The model base still extends 10 m beyond the boundary, now with softly rounded corners on every shape, so a plain rectangle reads as a gently rounded presentation platform in the viewer.
        - Rectangle and polygon boundaries are area-clamped about their centre, so the OSM download stays within your maximum study area just like the circle did.
        - Internal cleanup: removed the unused road snap-and-dissolve helper and renamed the circle-specific export internals to be shape-agnostic; synced the viewer manifest and Overpass User-Agent to 0.9.0.
    3D OSM Model 0.8.2 - Residential facades restored, raw OSM roads, smaller base buffer.
        - Restored the six apartment/residential facade textures (renamed from the old region-specific set) and made them the default building facade, kept together with the new grey massing colours.
        - Roads are now used exactly as OpenStreetMap provides them: the snap-and-dissolve "connect roads" step was removed because it produced fragmented geometries without improving the network.
        - The model base buffer around the study circle is now 10 m (was 20 m).
        - Changed the dashboard toggle button icon.
    3D OSM Model 0.8.1 - Hub fix, dissolved-road sidewalks, European massing & quality pass.
        - Fixed the QGIS Plugin Hub upload error: a literal percent sign in the changelog was read as a config interpolation token; reworded so the metadata parses.
        - Roads exported as MultiLineString (after the connectivity dissolve) are now drawn with full procedural carriageways and sidewalks on BOTH sides; previously the viewer skipped any non-LineString road, so those streets lost their road surface and one or both sidewalks.
        - Default building colours are now muted greys and slates (European / North-American massing) instead of sandy pastels, and the default facades and roofs lead with stone, glass and charcoal rather than terracotta brick.
        - Roof texture options now have systematic, descriptive names (e.g. "Slate tile", "Standing-seam metal", "Asphalt shingle") instead of RoofA / RoofB.
        - Cyclists now ride automatically whenever a bike-lane layer is present.
        - Procedural building setback now defaults to 0.
        - Trucks and lorries are now about 1 percent of traffic and buses about 2 percent; the rest are city cars and vans.
        - Removed the redundant top-level "Block color" control (block colours live in the Block Categories section).
    3D OSM Model 0.8.0 - Elite unified viewer toolbar.
        - The viewer's floating circular toolbar buttons were absolutely positioned at fixed pixel offsets, which left visible dead gaps where the old language and advanced buttons used to sit. They are now a single self-packing glass tray with even spacing and hairline separators that group the dashboard, dock toggles, walk mode and tools.
        - Dock toggle buttons (Layers, Style, Scene & Sun, Model Studio) now light up with an active state so it is always clear which panel is currently open.
        - Removed the stale "Switch language (TR/EN)" row from the Help & shortcuts overlay; the viewer has been English-only since 0.7.0.
    3D OSM Model 0.7.0 - Fully OpenStreetMap-native schema, procedural roads & bike lanes, simpler English viewer.
        - The export now carries raw OpenStreetMap columns (building, building_levels, highway, waterway, leisure/landuse/natural, width) instead of a translated schema; the viewer maps these straight to floors, function colours, road hierarchy and widths.
        - Roads, sidewalks and bike lanes are fully procedural again (per-road ribbons with lane markings, sidewalks on both sides, green cycleway strips from OSM highway=cycleway), matching the PlanX 3D City engine; the dissolved-canvas road surface was removed.
        - Pedestrians keep to the sidewalks and cars to car-capable roads (footways/paths/cycleways carry no cars); cars no longer spawn on tiny disconnected stubs, which reduces jams.
        - The model base/island is now the study circle buffered by +20 m, so the city sits on a small platform margin while OSM data stays clipped to the circle.
        - The viewer is fully English (language toggle removed) and simpler: the "Urban Controls" advanced panel was deleted and the dashboard lists only OSM-derived layers (no parcels/hardscape/paths rows).
        - Removed tumulus and all of its controls, and dropped ~5 MB of region-specific facade textures the global tool did not need.
    3D OSM Model 0.6.0 - Water, street furniture & smarter building heights.
        - New OSM water layer: rivers, streams, canals, drains and ditches are downloaded, clipped to the study circle and drawn as flowing water ribbons whose width scales with the waterway class; the viewer's water layer is now on by default.
        - New OSM street furniture: bus stops, benches, street lamps and waste baskets are downloaded and placed in the scene aligned to the nearest road; street lamps glow after dark. The furniture layer is on by default.
        - Smarter default building heights: when OpenStreetMap has no floor or height data, the default floor count now depends on the building's function (housing reads taller than retail, light industry lower), and tagged roof levels are added to the massing.
        - The bundled sample city now showcases a stream plus bus stops, benches, lamps and bins on first open, before any export.
        - Synced the internal viewer manifest version and the Overpass User-Agent to the plugin version.
    3D OSM Model 0.5.0 - Dissolved roads with clean intersections; crosswalks removed.
        - Roads now render as a single dissolved surface drawn with rounded joins and flat end caps, so streets merge cleanly and intersections no longer show leftover ribbon edges, z-fighting or lane lines crossing the junction.
        - Removed crosswalks entirely (layer, default and toggle).
        - Removed the procedural lane markings that produced the stray lines through intersections; the road surface reads as one continuous carriageway.
        - Procedural sidewalks are confirmed on both sides of every road.
    3D OSM Model 0.4.0 - Connected road network, calmer traffic, stable release.
        - Roads are welded into a connected network on export: segment ends are snapped to nearby roads and dissolved by class, so streets flow continuously even where OpenStreetMap left small gaps between ways (best-effort; skipped safely if Processing is unavailable).
        - Reduced the default on-screen traffic to about one fifth for a calmer, faster scene; the car-count formula no longer collapses to zero at low densities.
        - Added the required LICENSE file (MIT) and switched all Qt enums to Qt6-safe scoped forms so the package validates for QGIS 4.
        - Marked the plugin as stable (experimental=False).
    3D OSM Model 0.3.0 - Critical viewer fix, measurement, screenshots & resilient download.
        - Fixed a critical bug that left the web viewer stuck on an endless loading spinner: a stray quote inside the Turkish interface strings raised a syntax error that crashed the entire 3D module before it could start. The viewer now boots reliably.
        - The viewer now ships with a small bundled sample city, so it opens as a populated 3D scene before you run any export (great for a first look and for offline demos).
        - New distance measurement tool: pick two points on the ground to read the distance, with a live dashed preview and stackable segments.
        - New one-click screenshot button saves a clean PNG of the current view (UI hidden).
        - New in-app Help & shortcuts overlay listing the mouse and keyboard controls (bilingual).
        - Added the required OpenStreetMap attribution credit ("© OpenStreetMap contributors").
        - More resilient OSM download: Overpass requests now fall back across mirror servers automatically when the main endpoint is rate-limited or slow.
        - The plugin dialog remembers your last study-area source and maximum area, and adds an "open viewer automatically after export" toggle.
        - Fixed 2D overlay labels that never appeared because the label layer was created but never drawn each frame.
    3D OSM Model 0.2.0 - Unified salmon identity, golden hour & richer dialog.
        - One cohesive salmon-tinted grey theme now spans the QGIS dialog, the web toolbar/panels and the 3D scene; the viewer chrome was previously teal.
        - Restored the Scene & Sun controls behind their own toolbar button: time of day with quick presets, weather, light/dark theme, bloom and shadow quality, camera bookmarks, plus a Life & traffic section (traffic speed, car and pedestrian density).
        - Leaner, OSM-focused interface: the Layer and Style docks now list only what OpenStreetMap produces; removed the unused Mobility, Street furniture, Fences, Analysis and Narrative panels and fixed the toolbar button spacing.
        - The scene opens at golden hour for warm, flattering massing.
        - Redesigned the plugin dialog: header banner, grouped cards, a live study-area estimate, a collapsible Advanced (DEM) section, and a last-run summary with Open viewer and Open data folder buttons.
    3D OSM Model 0.1.2 - Independent, decluttered interface.
        - Rebranded the viewer as "3D OSM Model" with its own salmon-tinted grey theme, separate from PlanX 3D City.
        - Trimmed the toolbar to the essentials: Layers, Style, Model Studio, Walk mode and Advanced; kept the minimap. Removed Scene, Mobility, Street furniture, Fences, Analysis, Narrative, Slingshot and Camera/recording controls.
    3D OSM Model 0.1.1 - Lively scene defaults.
        - Realistic trees, animated pedestrians and mixed traffic are now on by default.
        - Added a procedural vehicle factory with cars, vans, buses and trucks (wheels, windows, head/brake lights); buses and trucks move a little slower.
    3D OSM Model 0.1.0 - Initial release.
        - One-button workflow: select an area, download OSM, and open an interactive 3D city viewer.
        - Largest inscribed circle of the selection becomes the study boundary with a solid base; extent capped at ~300 ha.
        - Procedural roofs and facades (extra detail off by default), procedural road traces, default 3 floors when level data is missing, optional external DEM, salmon-tinted grey theme.
