User Manual

A guide to the 3D Digital Twin and 2D Printable Viewer for the Al Karama Urban Digital Twin project.

Table of Contents

Getting Started
Keyboard & Mouse Shortcuts
3D Digital Twin Viewer
Layer Groups
Time Slider & Shadows
Walking Route Planner
View Presets & Basemaps
Clicking Features
2D Printable Viewer
Other Maps
Tips & Troubleshooting

Getting Started

Open viewer.html in a modern browser (Chrome, Firefox, Safari, or Edge). The viewer loads with:

Al Karama, Dubai as the study area
Buildings extruded in 3D with height from Google Earth Engine
Tree canopy shown as green polygons
District boundary as a magenta outline
GPU sun shadows and projected building/tree shadows enabled for the default time (12:00 PM)
The camera tilted at 45° for a 3D perspective

The viewer uses WebGL via deck.gl for GPU-accelerated rendering. If the map appears blank, check that hardware acceleration is enabled in your browser settings.

Keyboard & Mouse Shortcuts

The 3D viewer uses deck.gl + MapLibre GL. The 2D viewer uses Leaflet. Their navigation shortcuts are listed below.

3D Viewer (deck.gl / MapLibre)

Action	Mouse / Trackpad	Keyboard
Pan	Left-click + drag	—
Zoom in	Scroll up, or pinch out on trackpad	`+` or `=`
Zoom out	Scroll down, or pinch in on trackpad	`−`
Rotate (bearing)	Right-click + drag left/right, or `Ctrl` + left-click + drag	—
Tilt (pitch)	Right-click + drag up/down, or `Ctrl` + left-click + drag up/down	—
Zoom to point	Double-click	—
Zoom out from point	Double-click + `Shift`	—
Reset north	Click the compass (if visible)	—
Box zoom	`Shift` + left-click + drag a rectangle	—

2D Viewer (Leaflet)

Action	Mouse / Trackpad	Keyboard
Pan	Left-click + drag	Arrow keys (`←` `→` `↑` `↓`)
Zoom in	Scroll up, double-click, or pinch out	`+` or `=`
Zoom out	Scroll down, or pinch in	`−`
Box zoom	`Shift` + left-click + drag a rectangle	—

Browser Shortcuts (all viewers)

Action	Windows / Linux	macOS
Hard refresh (clear cache)	`Ctrl`+`Shift`+`R`	`Cmd`+`Shift`+`R`
Open dev console	`F12` or `Ctrl`+`Shift`+`I`	`Cmd`+`Option`+`I`
Full screen	`F11`	`Ctrl`+`Cmd`+`F`
Print / export PDF	`Ctrl`+`P`	`Cmd`+`P`

3D Digital Twin Viewer

The 3D viewer is the primary interface. It renders Al Karama as an interactive 3D scene with buildings, tree canopy, shadow projections, thermal overlays, street networks, and points of interest.

Interface layout

Left panel — layer toggles organised in accordion groups, plus the sun position compass
Bottom bar — time-of-day slider (6 AM – 6 PM) with play/pause button
Bottom-right buttons — view presets (Overview, Top-down, Street, South) and basemap switcher
Top nav bar — links to Dashboard, 2D maps dropdown, season selector, and area selector
Dynamic legend — appears bottom-left when a colour-coded layer is active
Info popover — click the i button next to any layer for a description

Season selector

The dropdown in the top nav bar lets you switch between seasonal datasets (e.g., Summer 2025, Winter 2025). Switching seasons reloads shadow projections, satellite grids, heat priority, and combined SVI data for the selected period. Layers marked with a seasonal badge update automatically.

Layer Groups

Urban Form (3 layers)

Layer	Description
Buildings	3D extruded footprints. Colour modes: Default (uniform), Height (blue→red), Land Use (residential, commercial, etc.)
Tree Canopy	Green polygons from satellite-derived canopy data
District Boundary	Magenta outline of Al Karama

Shade & Shadows (4 layers)

Layer	Description
GPU Sun Shadows	Real-time shadow casting from the deck.gl lighting engine based on the time slider
Building Shadows (projected)	Pre-computed shadow polygons from building footprints. Updates with time slider. Seasonal.
Tree Shadows (projected)	Pre-computed shadow polygons from tree canopy. Updates with time slider. Seasonal.
Street Shade %	Street segments coloured by shade coverage percentage. Modes: Shade colour / Neutral. Seasonal.

A shade coverage bar chart also appears in the panel, showing average shade per time slot.

Thermal & Vegetation (7 layers)

Layer	Description
Heat Mitigation Priority	Points scored by combined heat stress factors. Seasonal.
Combined SVI+Satellite	Fused street-view and satellite metrics per point. Colour modes: LST, GVI, SVF. Seasonal.
Climate Clusters	K-means clustered zones by thermal/vegetation profile. Seasonal.
Green Space Access	Walking distance to nearest green space per point
5-Year Change (2020→2025)	Difference in LST, NDVI, or NDBI over 5 years
Seasonal Change	Difference between summer and winter in LST, NDVI, NDBI, or priority score

Mobility & Network (3 layers)

Layer	Description
Street Centrality	Network analysis of street importance. Modes: Betweenness, Closeness
Pedestrian Comfort	Segment-level comfort scores combining shade, LST, and GVI
Walking Network	Routable pedestrian network. Colour modes: PCI (comfort index), Shade, LST. Includes route planning (see below)

Points of Interest (1 layer)

Layer	Description
POIs	1,290 points from OpenStreetMap. Filter by category: Food, Shopping, Hotel, Health, Religious, Services, Leisure, Education

Time Slider & Shadows

The bottom time slider controls the sun position and shadow projections across 7 time slots:

6 AM • 8 AM • 10 AM • 12 PM • 2 PM • 4 PM • 6 PM

Drag the slider or click a time mark to jump to that hour
Click the ▶ Play button to auto-cycle through the day
The sun compass in the left panel updates to show azimuth, altitude, and shadow length
Building and tree shadow polygons update to match the selected time
Street shade percentages update accordingly

Walking Route Planner

When the Walking Network layer is enabled, a route planning interface appears:

Click Set Route
Click on the map to set the start point (snaps to nearest network node)
Click again to set the end point
A route is computed and displayed. Choose the optimisation:
- Comfort — prefers shaded, cooler, greener paths (may be longer)
- Shortest — minimises walking distance
A replay bar appears at the bottom to animate a walk along the route, with speed controls (0.5x–32x)
Click the 🔗 share button to copy a URL that encodes the route
Click Clear or ✕ to dismiss

View Presets & Basemaps

Camera presets (bottom-right)

Preset	Description
Overview	Tilted 45° view of the entire district
Top-down	Bird's-eye (0° pitch) for map-like viewing
Street	Low angle, zoomed in for street-level perspective
South	Looking south to see shadow fall patterns

Basemaps

Style	Description
Map (default)	CARTO Positron — light, clean labels. Good for analysis overlays.
Satellite	Esri World Imagery. Good for comparing with vegetation layers.
Dark	CARTO Dark Matter. Best contrast for thermal/coloured layers.

Clicking Features

Click any visible feature to see a tooltip or popup with details. The information depends on the layer:

Layer	Popup content
Buildings	Name, building type, height (m), height source, land use
Street Shade	Street name, shade %, length
Heat Priority	Priority score, LST, NDVI, SVF, GVI
Combined SVI	Current metric value (LST, GVI, or SVF)
Street Centrality	Road name, betweenness/closeness value
Pedestrian Comfort	Comfort score, shade %, LST, GVI
POIs	Name, category, amenity type
Walking Network	Edge comfort index, shade %, LST

Click on an empty area of the map to dismiss the popup.

2D Printable Viewer

The 2D viewer uses Leaflet and is designed for printable/exportable maps. It provides radio-button layer selection (one analysis layer at a time) with a legend.

Available layers include: Street Centrality, Pedestrian Comfort, Heat Priority, Combined SVI, Satellite Grid, Climate Clusters, and Green Access.

Export: Use Ctrl+P (Cmd+P on Mac) to print or save as PDF. The 2D viewer is styled for clean print output.

Other Maps

Map	Description
GVI Point Map	11,651 Mapillary image locations with Green View Index values and image popups
Segmentation Gallery	Sample semantic segmentation images showing vegetation detection
Network Analysis Comparison	Side-by-side comparison of 5 centrality metrics
OD Betweenness	Origin-destination weighted pedestrian flow analysis
Space Syntax	Angular Choice and Integration analysis
Transit Isochrones	Walking distance from metro and bus stations (5/10/15 min)
Boundary Comparison	Effect of boundary choice on centrality metrics
Satellite Grid (10m)	High-resolution satellite analysis grid
Thermal Sharpening	Downscaled thermal imagery comparison

Tips & Troubleshooting

Issue	Solution
Map appears blank	Check that hardware acceleration is enabled in your browser. Try a hard refresh (`Ctrl`+`Shift`+`R` / `Cmd`+`Shift`+`R`).
Layer not loading	Check the browser console (`F12`) for errors. Data files are lazy-loaded on first toggle.
Shadows not updating	Drag the time slider. Shadow polygons load per time slot; there may be a brief loading delay.
Slow performance	Disable layers you don't need, especially GPU Shadows and Tree Shadows which are rendering-intensive. Closing other browser tabs also helps.
Route not computing	Make sure you click near the road network. The start/end points snap to the nearest walkable node.
Season data missing	Not all seasons may have complete data. Check the season dropdown for available options.
Printing / PDF export	Use the 2D viewer for best print results. Switch to Top-down view and use `Ctrl`+`P`.

Al Karama Urban Digital Twin | Data: Mapillary, Landsat 8/9, Sentinel-2, OpenStreetMap | Generated with ZenSVI + Google Earth Engine