# Hong Kong Island: coastline, terrain and sand

Geographic data copyright HKSAR Government, Lands Department. Source rights are separate from the engine software licences.

## Coastline

Source: [CSDI Portal, 1:50 000 Topographic Map](https://portal.csdi.gov.hk/csdi-webpage/dataset/landsd_rcd_1637221775627_85634), HYDRLINE, CLASS=SLN / TYPE=COA. Reuse under [CSDI Portal terms](https://portal.csdi.gov.hk/csdi-webpage/doc/TNC).

The 2026-11-04 extract joins matching coastline endpoints into Hong Kong Island's closed ring, with 2,553 original vertices. It uses no administrative or sea-area boundary. The retained source is `data/hong-kong-island.geojson`; source hashes, origin and projection are in `island-provenance.json`. North is -Z, east +X; scale is 0.085 world units per metre. Coast simplification tolerance is about 8.3 metres.

## Real elevations

Source: [Lands Department 5m Digital Terrain Model](https://data.gov.hk/en-data/dataset/hk-landsd-openmap-5m-grid-dtm), downloaded 2026-11-09. [Product details](https://www.landsd.gov.hk/en/spatial-data/open-data/kf_dtm.html): 5m cells, +/-5m accuracy at 90% confidence, Hong Kong 1980 Grid (EPSG:2326), heights in metres above Hong Kong Principal Datum. The published product is based on historical aerial imagery; it can include vegetation, elevated roads and bridges.

The generator transforms WGS84 positions into HK1980 Grid before bilinear sampling from the original ASC cell centres. It retains a 513 x 513 extract on the scene grid (about 55.1m sample spacing); the terrain mesh uses the same grid and about 55.1m spacing. These are rendering resolutions, not a claim to show every original 5m cell. Source heights use the same 0.085 scale vertically, with no vertical exaggeration. Local beach grading is described separately below. The highest retained island sample is about 548m HKPD; individual unsampled summits may be higher.

`data/dtm-provenance.json` and `island-provenance.json` record the archive SHA-256, ASC header, coordinate operation, extract hash and geographic height probes. The retained extract is `data/hong-kong-island-dtm.npz`. The scene water plane is zero; no tide or mean-sea-level correction is applied. A two-metre coastal join connects land to the illustrative seabed. Terrain, shoreline foam, camera collision and buoyancy use this same height field. Height queries interpolate the actual mesh triangles. Zero-height land stays land in the wave mask; the ocean surface is clipped on land while wet run-up is shaded on the ground.

## Sand only in mapped sand areas

Source: the same official 1:50 000 map, LANDPOLY, CLASS=BRL / TYPE=SAN. The [official data dictionary](https://www.landsd.gov.hk/landsd_psi_data/SMO/data/iB50000_Data_Dictionary-GMLv.1.1.pdf) defines SAN as Sand. The retained GeoJSON contains 13 source polygons within the island's bounding region, with their official IDs and update dates. Source: `data/hong-kong-sand.geojson`; distributed copy: `hong-kong-sand.geojson`.

The sand material and sand ripples use a 4096 x 4096 signed-distance field over a 1600-world-unit square (about 4.6m sample spacing), measured from the original polygon segments and holes. Linear reconstruction and inward edge antialiasing remove square mask steps. Dry sand follows the mapped polygons. A shallow-water continuation extends at most about 28m beyond their edges so the dry coastline does not create a brown stripe underwater; that continuation is illustrative. The coastline clips visible land; polygons on nearby islets do not create new land. `sand-provenance.json` records the exact query, IDs, source hash and raster resolution. This is the map's sand classification, not the list of managed swimming beaches.

## Beach geometry and surface

Ten official sand polygons intersect Hong Kong Island. Their local terrain windows use 8x mesh refinement, about 6.9m spacing, in seven merged patches. The dry foreshore rises gently at 5.5%, with a small 0.35m berm; the shallow underwater shelf uses a 4% slope. These are illustrated beach profiles, not measured beach elevations. A smooth join extends up to 40m onto neighbouring land and 180m offshore. Dry sand follows the official polygons, with the shallow-water continuation described above.

The outer collar of each patch retains the original terrain heights exactly. Inland hills outside those coastal joins keep the sourced DTM. Rendered ground, collision and buoyancy use the same triangles; the water shader receives the exact fine beach height grids in its existing shore texture. Sand grain and ripples use physical metre coordinates, with a damp lower foreshore and matte dry sand. `beach-provenance.json` records source polygon IDs, mesh spacing, transition distances and the illustrated profile. The Beach camera starts within mapped polygon 809.

## Buildings and matching city ground

Source: [Lands Department 3D Visualisation Map, non-textured models](https://data.gov.hk/en-data/dataset/hk-landsd-openmap-3d-visualisation-map-non-textured-models), CSDI `landsd_rcd_1742809441342_98380`, retrieved 2026-11-09. The full-island extract includes 21,602 building parts and 732 infrastructure parts in 187 neighbourhood sheets. Parts include separate podiums, roof structures and ancillary objects; this is not a count of individual buildings. The island coastline filters the source, with a narrow northern harbour allowance for piers. Four invalid all-zero source GLTF files are omitted and recorded in the manifest.

The GLTF node transforms encode Hong Kong 1980 Easting, HKPD height and negative Northing. Conversion uses EPSG:2326 to WGS84, then the exact same local projection and 0.085 scale as the island. Buildings are not raised, flattened or stretched. Source triangles preserve the supplied roofs, podiums and silhouettes. Meshoptimizer, using its bundled WASM at build time, produces three display levels with maximum requested geometric error of 3m, 1.2m and 0.15m. Compressed local GLBs load progressively, with finer geometry near the camera and a bounded detail cache. `buildings/manifest.json` records hashes, geometry counts, dates and tolerances. No government API key is sent to visitors.

The matching `TERRAIN(TB)` geometry from those same neighbourhood packages supplies the ground beneath the city. Actual source triangles are sampled at about 13.8m, or 6.9m where city and beach patches meet. A shared ground surface joins across blocks; there are no individual excavations under buildings. Source coverage blends to the existing DTM over 35m at its outside edge. The sea and the mapped beach grades are preserved. The lowest vertex of a building can be a basement, rooftop component or downhill facade, so it is not used to set the whole site's ground level. `buildings/foundations.json` records the matching terrain sources and treatment.

Building palettes are interpreted from each building's own source photographs as described below. Facade window layouts and sparse night lighting are illustrated, not measured occupancies, signs or advertising. The models and source terrain have different revision dates and can contain omissions or errors.

## Inland water, woodland and urban ground

The same Lands Department 1:50 000 map supplies HYDRPOLY reservoir/pond boundaries, LANDPOLY woodland, FACIPOLY parks and sports grounds, and TSPTLINE road centre lines. Twelve inland water bodies are rendered: seven reservoirs and five ponds. One coastal pond at sea level retains the existing ocean treatment. `land-provenance.json` records source hashes, feature counts, omitted water and the chosen display levels. Geographic layers are retained under `data/hong-kong-land-*.geojson`.

Each inland water body has one horizontal surface with restrained sky reflections and no animated waves. Its displayed level is inferred from the dominant flat height or lower quartile of interior terrain samples; it is not a live water reading or a surveyed water level. Illustrated basin depths and banks use local 3.4m grids. Grading joins to the existing ground over a 50m bank collar. Nearby dry structure footprints and a 5.3m margin retain their original ground, with a further 10m protective blend. Untouched grid collars prevent seams; height queries and rendering use the same triangles.

2048-pixel masks separate woodland, parks, road surfaces and paved building margins. Woodland and parks have independent channels in `land-biomes.png`, so filtered forest edges cannot accidentally acquire the park colour. Forest transitions are softened over about 18m; park edges remain more defined. Road positions are sourced, but widths and paved margins are illustrative. The tree layer combines the official inventory described below with illustrative woodland infill. Both follow the final ground and appear only near the camera. The Reservoirs camera looks across the largest retained Tai Tam reservoir polygon.

Dry grass, soil and paving use matte materials. The wet film is restricted to low bare shoreline and the mapped beach foreshore, rather than spreading across reclaimed city land. Parks have lighter greens, woodland deeper greens, rock warm mineral tones and paving a warm grey. Small ground grain fades with distance. These are illustrated materials; the surface-colour pass does not change ground or building elevations.

## Streets and footpaths

Car roads use the [Transport Department Road Network, second generation](https://data.gov.hk/en-data/dataset/hk-td-tis_15-road-network-v2). Its ELEVATION field distinguishes surface roads from tunnels and flyovers; TRAVEL_DIRECTION supplies permitted direction. The retained regional extract has 7,902 surface features, 91 underground features and 383 elevated features. Underground and elevated features are excluded from the surface layer. Existing 3D infrastructure supplies some bridges. The detailed footpath layer retains 387 active Lands Department footpaths, trails and non-motorable routes.

Each ribbon is intersected with the actual terrain triangles before packing. The road therefore follows the same surface across hills and city patches. This is a surface stencil, not an engineered cut-and-fill road grade. Tile simplification has a 3.6cm Euclidean tolerance; steep slopes can magnify its vertical component. A small camera-depth bias separates road pixels from ground without moving the geometry. Ground and roads render before vehicles, and roads do not write depth, avoiding cut-outs around wheels.

The 583 small tiles stream near the camera, with a smaller phone cache. They total 18.8MB, rather than being fetched together at startup. Far views use a surface-only road mask. Car roads have matte asphalt and pale edges; walking routes have narrow, irregular earth-coloured edges and no road markings. Road widths (5.5m or 7m), footpath widths (1.5–2.2m), kerbs and car movements are illustrations. No surveyed lanes, crossings or road gradients are inferred. `streets-manifest.json` and `street-routes.json` retain provenance and classifications.

## Illustration and rebuilding

Seabed depths, rock dimensions, waves, vegetation colours, surface materials and night visibility are artistic. Coastlines, base elevations, city model geometry, sand, water and woodland boundaries, parks and road centre lines carry geographic provenance; local beach/bank grades and materials are illustrative. Fine piers, narrow beaches and other details can be lost at the mesh/mask resolutions. The scene is not a navigation chart and is not endorsed by the Government.

From the repository root:

```sh
uv run experiments/sites/ultra-water/scripts/extract-hong-kong-dtm.py --archive <Whole_HK_DTM_5m.zip>
python3 experiments/sites/ultra-water/scripts/bake-hong-kong.py
python3 experiments/sites/ultra-water/scripts/bake-hong-kong-sand.py
uv run experiments/sites/ultra-water/scripts/bake-hong-kong-beaches.py
uv run experiments/sites/ultra-water/scripts/prepare-hong-kong-buildings.py --source <download-cache> --output <converted-cache>
node experiments/sites/ultra-water/scripts/bake-hong-kong-buildings.mjs <converted-cache>
uv run experiments/sites/ultra-water/scripts/bake-hong-kong-foundations.py --source <download-cache>
uv run experiments/sites/ultra-water/scripts/bake-hong-kong-land.py --source <download-cache>
node experiments/sites/ultra-water/scripts/bake-hong-kong-streets.mjs
node experiments/sites/ultra-water/build.mjs
```

The extract command uses an isolated uv environment for NumPy and pyproj. Later bakes use the existing NumPy installation. All geographic rendering data is bundled locally; visitors do not call a map service.

## Building colours across Hong Kong Island

The Lands Department [3D Visualisation Map (Individualised models)](https://portal.csdi.gov.hk/csdi-webpage/dataset/landsd_rcd_1671676915450_88604), dataset `landsd_rcd_1671676915450_88604`, supplies individual photographic models for all 187 scene sheets. All 21,602 rendered building parts have their own extracted palette, with zero missing sources. Building IDs are joined to their own source model before extraction. `buildings/building-colours.json` reports expected and successfully extracted model counts, per-sheet coverage and any unmatched IDs. The browser keeps the existing geometry and its camera-dependent detail levels; infrastructure and foundations retain their source positions.

Original UVs select area-weighted wall samples from the source photographs. Eight colour clusters per building provide estimates for walls, glazing, roofs and accents. Sample heights suggest up to three coarse accent bands; broad colour patches are excluded to reduce the influence of reflected surroundings. The colours are lightened for the illustrated scene. Each building receives its own palette, including the red bands of the waterfront tower. These are approximate interpretations of photographs, not a survey of building materials or exact accent placement.

The renderer draws clean procedural windows and flat colours. No photographic façade texture, baked shadow, reflected scenery, sign or advertising image is displayed. Punched windows, horizontal ribbons, vertical bays, larger glass panels and paired windows vary by building seed; their spacing and sparse night lighting are illustrative. Distant patterns fade to their average coverage to avoid moire. The original photographs remain offline inputs. The palette is a small JSON file, `buildings/building-colours.json`, with source identifiers and hashes; it becomes a packed 252-pixel-wide colour table on the GPU, about 0.5MB for the full island. Packing many palettes into each row avoids mobile texture-height limits. No façade atlases or separate textured meshes are downloaded. Unmatched source models retain neutral stone and glass; no colour family is assigned to stand in for missing photographic evidence. Exact float32 building seeds are matched within each sheet to avoid collisions between similar seeds or different neighbourhoods.

The camera opens in Sheung Wan, with Island available in the view controls. The Look control compares Building colours with Original. `?view=Sheung+Wan&time=14:00` is an explicit daylight preview; Now resumes the live Hong Kong clock. The tested pixel filter was removed at the owner's request.

The earlier photographic pilot used 128px/256px images in two 2048px WebP atlases, with one red-framed tower at 512px. Its bake scripts and manifest are retained as derivation records. The current colour treatment no longer loads those images or textured meshes.


## Small life and habitat placement

People walk short routes inside 44 mapped active parks. Routes avoid mapped building hulls, roads and inland water, and runtime checks reject steep or unsuitable ground. Swimmers follow short routes in coastal water beside mapped island sand, away from dry land; their height comes from the existing animated water query. A few wild pigs wander through clear woodland near Victoria Peak. Bird silhouettes glide in coastal and woodland flight circles, with occasional wing beats.

These are original procedural illustrations, not visitor counts or reported animal sightings. Habitat and species references: [Hong Kong Bird Watching Society, Black Kite](https://avifauna.hkbws.org.hk/species/0180/026100) and [AFCD, terrestrial mammals](https://www.afcd.gov.hk/english/conservation/hkbiodiversity/speciesgroup/speciesgroup_mammals.html). `life-provenance.json` records geographic inputs and placement rules. The models use small instanced batches, limited by distance and phone budgets. Reduced-motion preferences freeze the characters and suppress wind trails. Park and Peak view buttons provide closer views.

## Tree inventory, taxis and mapped rocks

Tree positions and species come from official [LCSD park trees](https://data.gov.hk/en-data/dataset/hk-lcsd-csdi-tree-information-major-parks), [LCSD venue trees](https://data.gov.hk/en-data/dataset/hk-lcsd-csdi-tree-information-lcsd-venues), [Highways Department trees](https://data.gov.hk/en-data/dataset/hk-hyd-csdi-tree-hyd) and [Old and Valuable Trees](https://data.gov.hk/en-data/dataset/hk-devb-ovt-ovt-and-stonewall). The island layer contains 65,263 records and 526 species labels after coordinate deduplication and overlap exclusions. Seven illustrative crown families distinguish palms, banyans, umbrella crowns, conifers, paperbarks, bauhinias and other broadleaf trees. Dimensions and colours are illustrative; extra woodland infill is separate from the inventory. Nearby trees are instanced and capped at 1,800 on desktop or 750 on phones.

The [Transport Department taxi-stand dataset](https://data.gov.hk/en-data/dataset/hk-td-tis_37-taxi-stands) supplies 84 island stands. All match a nearby surface road. The 324 placed queue cars are illustrative, not live availability. Moving saloons, hatchbacks, SUVs, vans and red/silver taxis follow the mapped centre lines and permitted directions, with left-side placement on two-way roads. Only nearby vehicles animate, capped at 260 on desktop or 110 on phones. `street-life-provenance.json` records filters and source hashes.

251 boulders use existing TERRSYMBOL / TNF / BOU locations in the Lands Department map. BOU means Boulder in its official dictionary. Positions inside generalised building hulls or mapped sand are excluded. Shapes and sizes are original illustrations, not a complete inventory of small rocks. See `rocks-provenance.json`.

## Wind and live aircraft

Wind ribbons interpolate velocity vectors from the three nearest fresh HKO stations. Positions come from the official station inventory, with North Point supplemented by the HKO station table. They do not imply street-level airflow measurements. Settings control speed, density, height, height spread, length, opacity, width and camera visibility height. Default visual speed is eight times the observed map-scale flow so the light trails remain readable. Variable, calm, stale or unavailable observations do not invent a direction.

Live aircraft use [adsb.lol](https://www.adsb.lol/docs/open-data/api), Open Database Licence 1.0. The fixed same-origin relay polls the public point API covering Hong Kong; the client refreshes every 15 seconds. Positions, true track, groundspeed in knots and reported altitude in feet are converted into the island's metre scale. Geometric altitude is preferred (WGS84 ellipsoid); otherwise pressure altitude is used. Neither is corrected to the terrain's HKPD datum, so this is not precise terrain clearance. Motion extrapolates for at most 30 seconds and observations expire after 60 seconds. Grounded aircraft and invalid tracks are omitted. Generic aircraft shapes are illustrative; no invented traffic fills an unavailable feed. The settings contain Follow nearest for inspecting a live flight.

## Calm lakes and building shading

Reservoirs share the ocean scatter colour and HDR sky, using level surfaces with no animated wave normals, glitter or FFT displacement. A depth offset prevents shallow basin overlap. Shore geometry and mapped water outlines are unchanged.

Building softness blends precomputed shared-edge shading with the original flat-face shading. Curved facade facets are smoothed more strongly than sharp joins. It adds no polygons, changes no positions or silhouettes, and is not a physical bevel. Quality contains the Building softness slider. Nearby detail has explicit triangle/block budgets, plus bounded GPU caches; distant buildings use the existing overview level. These limits reduce work but do not establish performance on a physical phone.
