[general]
name=3D OSM Model
qgisMinimumVersion=3.28
description=Create a styled OSM map and procedural 3D city, then export publication-ready images, PDF, SVG, HTML, or video.
version=1.2.5
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, car parks, pedestrian squares, 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. A coordinated "Map & web theme" picker styles both the native QGIS layer group and the exported city, with Editorial Paper active by default plus the existing calm and stylised palettes. Native layers arrive categorized by building/ground function, roads use hierarchy-aware metric widths, and water, trees and furniture have coordinated cartographic symbols. A single click adds the live OpenStreetMap tile layer to your project so an empty map can be navigated and framed before exporting, and that same layer is offered as the ground underlay. 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; parks, woods and forests are planted with procedural trees so green areas read as wooded rather than flat; buildings are coloured by OSM function - with a subtle per-building shade variation so blocks read as many individual buildings - and default to a function-aware floor count when no level data exists. Pyramid, hip, gable, shed and flat roof controls are supported, including standard OSM roof-shape tags. 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. Online User Manual & Documentation: https://yusufeminoglu.github.io/osm_3d_model/ | If you find this plugin helpful, please consider starring the repository on GitHub (https://github.com/YusufEminoglu/osm_3d_model)!
tracker=https://github.com/YusufEminoglu/osm_3d_model/issues
repository=https://github.com/YusufEminoglu/osm_3d_model
category=Web
homepage=https://yusufeminoglu.github.io/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 1.2.0 - One-click OSM basemap and QGIS 4 dialog fixes.
        - New "Add OSM basemap to the map" button adds the live OpenStreetMap tile layer at the bottom of the layer tree, so an empty project can be navigated and framed before exporting; a second click reuses it instead of stacking copies, and it is offered to the 3D export as the ground underlay when no other basemap has been chosen.
        - Fixed unreadable dialog text under QGIS 4 and Qt 6: the light card design inherited check-box, spin-box and label foreground colours from the application palette, which could be light on light, hiding the "Open the 3D viewer automatically after export" option and the "Max study area" value. The dialog now pins its own light palette.
        - Fixed the overlapping dialog under QGIS 4 when Advanced was opened. QGIS 4 needs more height than QGIS 3 for the same content, and once the window reached the screen ceiling the layout compressed the cards into each other. The dialog body now scrolls, so every control keeps its full size at any window height, and the window fits itself to the content when Advanced opens or closes.
        - The run button now displays the ampersand in "Create OSM layers and export 3D viewer" instead of consuming it as a keyboard mnemonic.
    3D OSM Model 1.1.3 - Security and packaging hardening.
        - Resolved every remaining Bandit warning in the source code instead of relying on a scan-skip file, so the local scan and the QGIS Plugin Hub scan now match exactly.
        - Replaced try/except/pass wrappers with contextlib.suppress, swapped the tree-scatter RNG for a self-contained deterministic generator, and open the data folder through the cross-platform Qt desktop service.
    3D OSM Model 1.1.2 - Stable viewer lighting during idle.
        - Removed the camera-idle SSAO switch that made the map suddenly appear dark after interaction stopped.
        - SSAO is now opt-in, remains consistent during movement and idle, and older saved viewer settings are migrated automatically.
    3D OSM Model 1.1.1 - QGIS 4 event-loop compatibility hotfix.
        - Fixed the export startup crash caused by PyQt6 moving ExcludeUserInputEvents under QEventLoop.ProcessEventsFlag.
        - The same code path remains compatible with QGIS 3/PyQt5 and was verified in QGIS 3.44 and QGIS 4.2.
    3D OSM Model 1.1.0 - Export Studio, roof fixes and native-map styling.
        - The web viewer now exports PNG, JPEG, WebP, PDF, SVG and self-contained HTML snapshots at viewport, Full HD, QHD, 4K or bounded custom sizes.
        - Live scene recording supports the WebM/MP4 codecs available in the embedded browser, 30/60 fps and selectable bitrate; clipboard PNG export is also included.
        - Exported media contains the clean 3D scene while orbit, walk, traffic, weather and solar animation remain live.
        - Fixed Pyramid roofs, including concave footprints and standard OSM roof-shape aliases.
        - Native QGIS layers now use categorized buildings/ground, hierarchy-aware metric road widths, coordinated water/tree/furniture symbols and correct draw order.
        - Editorial Paper is now the default theme for both the QGIS map and web viewer.
    3D OSM Model 1.0.1 - Citation metadata.
        - Added the Zenodo DOI citation metadata used by the repository and release archive.
    3D OSM Model 1.0.0 - Verified 1.0.
        - The complete pipeline (download with mirror fallback and cache, OSM parsing including multipolygon relations, all boundary shapes, GeoJSON export, manifest, optional DEM and basemap, local viewer server) now runs end-to-end in a real headless QGIS on both QGIS 3.44 LTR and QGIS 4.0 before every release, alongside a dialog GUI check and headless-browser renders of the exported city.
        - Clipping dense areas is faster: the study boundary is prepared once for the thousands of per-feature tests, and tree scattering uses the same prepared test.
        - Features that only graze the study boundary can no longer leave invisible degenerate slivers in the export.
        - When Overpass returns zero elements because of a server-side problem (query timeout, memory limit), the error message now includes the server's own remark.
    3D OSM Model 0.18.0 - Five stylised look themes (final stable release).
        - The "Web theme" picker gains five playful new palettes alongside the five calm ones: Anime (bright cel-shaded pastels), Cartoon (bold primary colours), Pixar (warm and friendly), Futuristic (dark neon and glass towers) and Classic era (vintage sepia). Like the existing themes they recolour the city content only - buildings, roads, base and roofs - and never the viewer toolbar or panels.
        - This is the final planned feature release; the plugin is now considered stable.
    3D OSM Model 0.17.0 - Subtle per-building colour variation.
        - Buildings of the same function are no longer drawn in the exact same shade. Each building now gets a small, consistent lightness variation, so a block of housing or offices reads as many individual buildings instead of one flat mass. The variation is deterministic - the same area always looks the same - costs nothing (building materials are already per-building), and respects the chosen web theme.
    3D OSM Model 0.16.0 - Pedestrian squares and plazas.
        - Pedestrian and footway areas, town squares (place=square) and marketplaces are now drawn as flat paved stone squares. Previously a pedestrian area was treated as a road and drawn as a thin ring tracing its outline; it now reads as a proper filled plaza. Ordinary pedestrian streets (without an explicit area) stay roads as before.
    3D OSM Model 0.15.0 - More complete ground: car parks and more green types.
        - Car parks (OpenStreetMap amenity=parking) are now downloaded and drawn as flat paved asphalt-grey areas - a common part of real cities that was previously missing from the ground.
        - More green and natural land types are now imported and shown green: orchards, vineyards, farmland, allotments, village greens, grassland, heath, nature reserves, golf courses and commons. Previously they were skipped or rendered an arbitrary colour. Orchards, nature reserves and village greens are also planted with trees.
    3D OSM Model 0.14.0 - Greener parks, woods and forests.
        - Parks, woods, forests and other wooded green areas are now planted with procedural trees, scattered inside each polygon. OpenStreetMap usually maps these as plain areas with no individual tree points, so they previously rendered as flat green patches; they now read as genuinely wooded. The tree count is capped for performance and is identical every time you re-run the same area.
    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.
