## 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.

Presentation rule of thumb: use a DEM when terrain matters, use a wide DEM when nearby topography matters, and allow the flat fallback when the plan itself is the main subject.

## 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.

Layer | Geometry | Vector Plan Mode | Notes
--- | --- | --- | ---
DEM | Raster | Recommended, not required | If missing, the viewer creates a flat presentation plane.
ROI | Polygon | Optional | Used to clip the active texture. Wide DEM outside ROI remains visible with a blank color.
Blocks / Islands | Polygon | Optional | Blocks are draped or plateaued over the visible terrain. Use them for planning islands, parks, and large land-use polygons.
Parcels | Polygon | Optional | Drawn as boundary lines above blocks.
Buildings | Polygon | Optional | Extruded by floor count or height fields. Facade textures are assigned by theme or feature attribute.
Roads | Line | Optional | Road widths are estimated or read from a mapped width field. Vehicle access can be controlled with road class values.
Hardscape | Polygon | Optional | Plazas, paved courtyards, squares, pedestrian surfaces, and other firm ground surfaces.
Sidewalks | Polygon | Optional | If absent, sidewalks can be generated along roads in the viewer.
Trees / Lights / Benches / Bins / Bus stops | Point | Optional | Point assets are placed on the final visible terrain surface.

### 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.

When terrain looks unstable: keep island plateau enabled, increase smooth passes to 2 or 3, keep smooth strength around 0.35 to 0.55, and use a 6 to 12 metre plateau edge ramp.

## 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

Symptom | Likely cause | Fix
--- | --- | ---
Viewer opens but terrain is flat | No DEM was exported, or the DEM failed to load | This is allowed in Vector Plan Mode. Select a DEM if real topography is needed.
Blocks or hardscape shimmer | Layer offsets are too close to terrain, a previous scene rebuild is stale, or the DEM has abrupt jumps | Keep island plateau enabled, increase smoothing slightly, and avoid very noisy DEM exports. Use the Layers panel to hide blocks or buildings when reviewing DEM plus basemap only.
Roads appear low after OSM import | OSM geometry is outside the DEM or the scene is using fallback terrain | Re-export with wider DEM context, or use the flat fallback; roads are placed on the final visible terrain cache.
Texture appears only inside ROI | ROI texture clipping is active | This is intentional for wide DEM context. Change terrain outside color if needed.
Quality report marks layers missing | Recommended layers are absent | Vector Plan Mode can still export. Missing optional layers are written as empty GeoJSON and skipped by the viewer.
Buildings have no height | No floor count or height field is mapped | Map `katadedi` or a height field, or let the viewer use fallback height rules.
Browser shows an older viewer | Browser cache kept an old module | Hard refresh the browser or re-open from QGIS after publishing.