PlanX 3D City Viewer User Guide

1. Quick Start

1. Open QGIS and load the layers you want to present. For Vector Plan Mode, every vector layer is optional; the viewer can also run with only a DEM or without a DEM.
2. Open PlanX 3D City Publisher from the QGIS plugin menu.
3. Use Auto-match layers first. The plugin searches common Turkish and English layer names such as roads, buildings, blocks, parcels, hardscape, sidewalks, trees, benches, and bus stops.
4. If you do not have project data yet, click Try with sample data or Import from OpenStreetMap.
5. Click Generate quality report. Required issues stop export; recommended issues are guidance only.
6. Click Export and open 3D Viewer. The plugin writes the web data package and launches the local browser viewer.

2. Data Layers

The publisher supports two workflows. Vector Plan Mode builds the scene from GIS layers. Raster Plan Texture Mode uses a raster plan image as the main surface texture.

Useful building fields

katadedi controls floor count. Height can also be read from common height fields. Optional fields such as population, dwellings, total floor area, vehicle count, roof type, roof color, facade texture, and planning function improve dashboards and thematic styling.

Coordinate systems

Projected CRS data in metres gives the best result. The plugin can reproject OpenStreetMap imports to a local UTM CRS. Avoid mixing layers with unknown or incorrect CRS definitions.

3. Terrain Strategy

DEM, flat fallback, and wide terrain

If a DEM is present, the viewer builds a mesh from the raster extent. If no DEM is exported, the viewer creates a dummy flat terrain plane so available roads, buildings, blocks, trees, and furniture still render.

For context presentations, export a DEM that is wider than the plan area. Add an ROI polygon for the actual project boundary. With Outside ROI terrain enabled, the terrain remains visible outside the ROI, but the active pavement, basemap, or plan texture is shown only inside the ROI and the outside area uses a clean blank terrain color. Disable Outside ROI terrain when you want the terrain surface clipped to the ROI for a pure model-only presentation.

DEM smoothing

Real DEMs can contain abrupt pixel jumps, nodata halos, clipped export edges, or locally noisy elevation values. The viewer runs boundary cleanup, median repair, and optional smoothing before other layers are placed. The Style or Terrain panel exposes:

• Smooth passes: number of repeated smoothing passes.
• Smooth strength: how strongly each pass moves a vertex toward the local robust surface.
• Max slope clamp: limits extreme height jumps between neighbouring terrain vertices.
• Flatten DEM under blocks: creates a stable plateau under each block or island polygon.
• Plateau edge ramp: blends the plateau back to surrounding terrain over a configurable distance.

4. Import from OpenStreetMap

The Import from OpenStreetMap button fetches a bounded package of roads, buildings, parks or blocks, and point assets where available. Imported layers are added to QGIS and can be exported like normal project layers.

1. Use a moderate bounding box first. Very large OSM requests can be slow or incomplete.
2. Run Auto-match after import so the new layers fill the Data page automatically.
3. If no DEM is available, export anyway. The viewer will use the flat plane fallback.
4. Inspect roads after export. Roads should sit above the visible terrain surface; if imported geometry is far outside the current DEM, either export a wider DEM or rely on the flat fallback.

5. Styling and Presets

The Style page controls the asset theme, terrain behavior, island and pavement materials, and the procedural city palette. Use Save preset to store the current layer mappings and style defaults as a reusable .planx JSON file. Use Load preset on another project to restore the same setup.

Facade textures

Facade materials are generated procedurally or loaded from bundled PNG assets depending on the selected theme. Theme facades include floor lines, window grids, ground-floor variation, and per-theme wall patterns. Building facades use a presentation-scale UV repeat so windows remain readable from normal review-camera distance. Use the viewer's Facade scale control when a project needs denser or larger window modules.

Hardscape, parks, and streets

Hardscape polygons are rendered as subdivided thin slabs above islands and below roads. Roads, sidewalks, crosswalks, trees, furniture, and buildings clamp to the final terrain surface cache, which keeps layer placement consistent after DEM smoothing and island plateau passes.

6. Web Viewer Controls

The viewer opens as a browser-based city cockpit. Use the left and right docks to tune display, theme, terrain, analysis, mobility, weather, camera, and narrative tools.

• Scene and camera: orbit, fly-to selected building, walk mode, field of view, time of day, auto orbit, and camera bookmarks.
• Terrain: texture source, ROI texture clipping, outside ROI color, terrain sides, smoothing, island plateau, topographic tint, and slope tint.
• Layers: basemap texture, plan texture, outside-ROI terrain, blocks, buildings, roads, sidewalks, parks, parcels, hardscape, trees, furniture, cars, pedestrians, and ROI outline.
• Analysis: building metrics, shadow heatmap, urban comfort, wind plume, minimap, and function filters.
• Narrative Studio: save keyframes, build presentation tours, and export portable viewer packages.

7. Publishing and Portable Handoff

Export writes a local web data package under the plugin's web/data folder and opens the viewer through a local HTTP server. Portable export copies the viewer, vendor libraries, and latest data into a standalone folder. Portable ZIP creates a single handoff archive for another computer.

After each publish, check the Publish page for the viewer URL, file count, empty optional layers, and portable export commands.

8. Troubleshooting