magnus919_agent-skills/ascii-city-engine/references/raleigh-poc.md

Raleigh Proof of Concept

This walkthrough reproduces the committed ../assets/raleigh-downtown-sample/ pack and scales it up to a fuller downtown pack. The committed sample is intentionally coarse (10 m terrain, simplified footprints, <= 2 MB) so the repository stays light; the full pipeline below is what you run for a denser local pack.

Downtown bounding box (authoritative for this POC)

WGS84 (EPSG:4326), south-west to north-east:

min: lon -78.6420, lat 35.7760
max: lon -78.6350, lat 35.7830

This box covers the Fayetteville Street core, the State Capitol grounds, Nash and Moore Squares' west edges, and the Hillsborough Street corridor. Through the tangent-plane conversion in gis-ingestion.md the box measures about 632 m east-west by 779 m north-south; the committed sample's manifest bounds and terrain grid are normalized to an exact 630 m by 770 m working extent (78 rows x 64 cols at 10 m) that sits inside it, so the documented formula and the shipped grid differ by roughly 1-2 m at the edges. It is deliberately compact so the sample stays small and every acceptance check is walkable in minutes. Expand symmetrically (for example to -78.6520..-78.6280, 35.7680..35.7910) for a fuller downtown pack.

Local pack CRS: equirectangular tangent plane, origin [-78.6420, 35.7760], x east / y north, meters (see gis-ingestion.md §Local tangent-plane fallback).

Data sources (all retrieved 2026-08-15)

Layer	Source	URL	License	Role
Elevation	USGS 3DEP Elevation Point Query Service	https://epqs.nationalmap.gov/v1/json	US public domain	Terrain heights
Buildings (footprints + heights)	OpenStreetMap via Overpass	https://overpass-api.de/api/interpreter	ODbL 1.0	Runtime footprints, tagged/estimated heights
Roads, sidewalks, paths	OpenStreetMap via Overpass (Kumi mirror)	https://overpass.kumi.systems/api/interpreter	ODbL 1.0	Walkable surface network
Buildings (municipal cross-check)	City of Raleigh Building Footprints FeatureServer	https://services.arcgis.com/v400IkDOw1ad7Yad/arcgis/rest/services/Building_Footprints/FeatureServer	City of Raleigh Open Data terms; attribution required	Geometry verification; heights absent

Observed yields on 2026-08-15 for the authoritative box: OSM returned 160 building ways, 41 carrying height or building:levels; the Raleigh FeatureServer returned 95 footprint polygons in the same box; EPQS center observation (-78.6385, 35.7795) = 106.517 m. EPQS corner observations for the sample grid: 95.727, 97.789, 101.578, 104.562 m — about 9 m of relief across the box.

Acquisition commands

Run from anywhere; outputs land in /tmp. Each step must succeed before the next (fail on HTTP error, then sanity-check the parse).

# 1. OSM buildings (footprints + height/level tags)
curl --fail --silent --show-error --get \
  --data-urlencode 'data=[out:json][timeout:60];(way[building](35.7760,-78.6420,35.7830,-78.6350););out tags geom;' \
  --output /tmp/raleigh-buildings.json \
  https://overpass-api.de/api/interpreter

# 2. OSM roads/sidewalks/paths (primary endpoint 504s under load; use a mirror)
curl --fail --silent --show-error --get \
  --data-urlencode 'data=[out:json][timeout:90];way[highway](35.7760,-78.6420,35.7830,-78.6350);out tags geom;' \
  --output /tmp/raleigh-roads.json \
  https://overpass.kumi.systems/api/interpreter

# 3. Municipal footprints (cross-check; 1 page is enough at this box size)
curl --fail --silent --show-error --get \
  --data-urlencode 'where=1=1' \
  --data-urlencode 'geometry=-78.6420,35.7760,-78.6350,35.7830' \
  --data-urlencode 'geometryType=esriGeometryEnvelope' \
  --data-urlencode 'inSR=4326' \
  --data-urlencode 'spatialRel=esriSpatialRelIntersects' \
  --data-urlencode 'outFields=*' \
  --data-urlencode 'returnGeometry=true' \
  --data-urlencode 'f=geojson' \
  --output /tmp/raleigh-city-footprints.geojson \
  'https://services.arcgis.com/v400IkDOw1ad7Yad/arcgis/rest/services/Building_Footprints/FeatureServer/0/query'

# 4. Elevation: one EPQS call per grid node for a coarse sample;
#    for a full pack, download the 3DEP 1/3 arc-second DEM for the tile and resample.
curl --fail --silent --show-error \
  --output /tmp/raleigh-elevation-center.json \
  'https://epqs.nationalmap.gov/v1/json?x=-78.6385&y=35.7795&units=Meters&wkid=4326&includeDate=False'

Verification per gis-ingestion.md: check HTTP status, byte size, JSON parseability, and record a SHA-256 per file before conversion. If the City of Raleigh URL has moved, search the portal (https://data.raleighnc.gov) for "Building Footprints" and record the new service URL plus your retrieval date; the committed sample keeps this POC runnable regardless.

Conversion

Reproject lon/lat to the local tangent plane (gis-ingestion.md §fallback), clip to the box, normalize polygons, estimate missing heights at 3.2 m per floor with lowered confidence, emit manifest.json plus world/tile-0.json, then validate:

python3 scripts/validate-city-pack.py assets/raleigh-downtown-sample

Expected tail of a good run:

PASS tile[0].content.bounds — world/tile-0.json
PASS buildings.unique-ids
PASS surfaces.unique-ids
PASS manifest.spawn.bounds
SUMMARY rules_passed=1411 rules_failed=0 buildings=159 terrain_extent=[0.0, 0.0]..[630.0, 770.0] surfaces=899

The deliberately-broken fixture must fail:

python3 scripts/validate-city-pack.py assets/deliberately-broken-pack
# FAIL manifest.bounds / manifest.tiles.nonempty / manifest.provenance ... ; exit 1

Human acceptance checks (run after any acquisition)

Serve the repo root (python3 -m http.server 8000) and open http://localhost:8000/assets/ascii-city-engine.html.

1. Load. The HUD reads 159 buildings · 298 props · 29 signs with no error text. Colored building walls rise against dark sky, and the wayfinding line reads On: South Wilmington Street (the spawn street).
2. Spawn. Camera starts at local (340, 390) facing north (heading 90°), mid-corridor on the Wilmington Street axis. HUD elevation reads about 100 m.
3. Street-name sign. Hold W and walk north ~120 m (about 30 s at 4 m/s) along Wilmington Street. The light-gray text North Wilmington Street (anchored ~143 m ahead, y≈532) floats in-world as you approach. The East Hargett Street sign is ~141 m behind the spawn (y≈249) and ~167° off the north-facing axis, so press A or D to rotate around to it (W/S only translate, they never turn the camera). These names come from the road name tags, never invented.
4. Street furniture. Along the walk, yellow T traffic signals cluster at intersections, white = crosswalk bands cross the road, green t trees dot the verges, and a cyan B marks a bus stop. All are point records from the OSM furniture layer.
5. Walk with a grade. The HUD elevation climbs continuously from ~100.1 m to ~101.0 m over the ~120 m walk — feet_z follows terrain and movement is never rejected on this gentle grade.
6. Solid footprint. Turn toward the nearest building wall and hold W into it. Forward motion stops at the wall face; strafing (A/D while holding W) slides along it. You cannot pass through or under it.

Re-run the validator after every fresh acquisition; if a data update moves a footprint onto the documented spawn, pick a new walkable spawn inside bounds and update manifest.json before publishing the pack.

Known limitations of the committed sample

• Terrain is bilinear interpolation of four EPQS corner observations — smooth and correct in trend, but it cannot show curb-level detail. A full pack should resample the 3DEP DEM at 2–5 m.
• Most buildings use the OSM building:levels × 3.2 m/floor estimate (confidence 0.72); a minority carry an explicit OSM height tag (confidence 0.88). The 0.55/0.35 fallback tiers in gis-ingestion.md step 7 apply to lower-evidence cases than this sample contains. Skyline proportions are right; individual roof elevations may not be.
• Buildings and surfaces crossing the bbox edge are clipped to the 630 × 770 m working extent and marked clipped: true; a small number that collapse below 3 vertices or self-intersect after clipping are dropped rather than weaken the validator's simple-polygon guarantee.
• OSM does not record highway=street_lamp nodes for downtown Raleigh, so lamps are absent from props; road lit tags still drive ground brightness. Municipal furniture layers (signals, lamps, trees) on the City of Raleigh ArcGIS portal can fill this gap but were not required for the current census.
• Raleigh municipal footprints are used as a geometry cross-check only; runtime footprints stay on ODbL-licensed OSM geometry so the sample remains redistributable with attribution.