FINDS - TESTS · Slate 2, Test 2 — deck.gl + MapLibre GL vs hand-rolled three.js
Date: 2026-11-20
Subject: deck.gl 9.4.1 + MapLibre GL JS 4.7.1 (Vite 6.4.6) rendering Ros's real Sausalito 3D dataset, compared with the incumbent hand-rolled three.js app at sausalito-3d.pages.dev.
Output: this folder — app/ (prototype), data/buildings.geojson, data/roads.geojson, screenshot-day.png, screenshot-night.png, extract-data.mjs.
1. Dataset — source and reconciliation
Hunt order, as briefed:
- Space source (
~/workspace/ts-spaces/sausalito-3d-explore/) — dead end. That Space is a different app: it streams Google Photorealistic 3D Tiles (tile.googleapis.com/v1/3dtiles) and contains no OSM building/road dataset. (Itsassets/app.jsis 715 KB of tile-viewer code.) Nothing there was modified. - Live site (
https://sausalito-3d.pages.dev) — hit. The incumbent is a single self-contained HTML file (3,696,915 bytes) with the whole dataset baked in as base64 blobs:window.SAUS(world data),window.SAUS_LABELS(street/address labels), plus the three.js bundle. - GitHub repo (
irostyslav/sausalito-3d) — not needed, and not reachable:git clonefailed (private repo, no credentials in this sandbox). The live site already carried the full dataset, so nothing was lost.
Reconciliation — exact, no trimming:
| Expected | In baked SAUS data |
Written to GeoJSON | Confirmed in prototype HUD | |
|---|---|---|---|---|
| Buildings | 4,212 | 4,212 (stats.buildings; 3,903 dataset heights + 309 estimated) |
4,212 | 4,212 |
| Roads | 2,105 | 2,105 (stats.roads) |
2,105 | 2,105 |
Conversion. The baked data lives in a local tangent-plane metre grid (x east, z south, world 4,400.3 × 5,549.7 m over a 315 × 397 terrain heightmap). The incumbent's own code anchors it: a comment places the pier "at the true ferry landing (37.85526, −122.47927), placed from the baked ferry point". I converted with a standard equirectangular tangent plane on that anchor (110,993.7 m/° lat, 88,004.8 m/° lon) and validated against the two other geocoded landmarks the code names:
- Trident (building idx 86): converted centroid vs geocoded position → residual 4.0 m
- Bay Model (building idx 0): residual 25.9 m (geocoded address point vs footprint centroid — expected slop)
Each building polygon carries its baked wall-base elevation (y1) as the third coordinate, so extrusions start at true ground height; extrusion height is the baked h. Roads carry baked width w and OSM kind k (700 footway, 557 service, 288 residential, 97 secondary, 75 steps, 63 track, 44+38 motorway/link, …).
2. Stack and basemap choice
- deck.gl 9.4.1 (
@deck.gl/core,@deck.gl/layers,@deck.gl/mapboxMapboxOverlay, non-interleaved) + MapLibre GL 4.7.1, Vite vanilla app. - Basemap: CARTO basemaps (keyless) — Positron for day, Dark Matter for night. Protomaps/PMTiles was not used: CARTO's hosted GL styles are keyless and need no tile-file hosting, which kept the prototype self-contained to build. Trade-off noted: the basemap is a hosted dependency at runtime (tiles/sprites/glyphs from CARTO's CDN), where the incumbent page is one fully self-contained file. The two style JSONs are vendored in
app/public/styles/because the CDN style fetch intermittently failed inside this sandbox (see effort log); tiles still load from CARTO.
3. What was built
- MapLibre map centred on the ferry landing/downtown (zoom 15.4, pitch 62°, bearing −28°) with navigation control.
- Buildings: one deck.gl
GeoJsonLayer, extruded, per-feature height (h) and fill colour from the baked type code (0/1 houses, 2 commercial, 3 mixed, 4 floating homes, 5 other), simple lighting material. - Roads:
GeoJsonLayerlines with width in metres from bakedw. - Day/night toggle mirroring the live site's synced modes: swaps the MapLibre style (Positron ↔ Dark Matter) and restyles both deck.gl layers + HUD chrome.
- HUD showing feature counts actually loaded/rendered, read from the data in-page.
- Hover picking with a tooltip (building idx, type, height) — about 15 lines via deck.gl's
pickObject. npm run buildpasses. Built bundle: 1.75 MB JS (≈482 KB gzip) + 66 KB CSS, plus 3.3 MB GeoJSON (≈0.80 MB gzip).
4. Verification evidence
Verified headlessly (Playwright + Chromium, software GL — this VM has no GPU; renders run sequentially with long settle waits):
- Page's own HUD/DOM reported "Buildings rendered: 4,212 · Roads rendered: 2,105" — the full dataset, in the app itself, not just in the files.
screenshot-day.png(1600×900): warm-toned extruded buildings on Positron; Bridgeway spine, downtown cluster, hillside terraces, waterfront and marina basins all in place.screenshot-night.png(same camera): Dark Matter basemap (water region samples RGB 14,14,14), buildings restyled dark slate with warm-brown commercial along Bridgeway, pale road network glowing. Pixel sampling confirms the restyle is real: non-background pixels average RGB (224, 210, 185) by day vs (88, 97, 106) by night.- Two genuine bugs were caught by this verification and fixed (see effort log): a deck.gl
updateTriggersrequirement, without which the building restyle silently didn't apply, and the sandbox proxy breaking CDN fetches in the test browser.
5. Code-size comparison vs the incumbent
| Incumbent (hand-rolled three.js) | This prototype (deck.gl + MapLibre) | |
|---|---|---|
| Hand-written scene/app code | 894 lines / 83,817 bytes of inline app script, plus the app modules inside its esbuild bundle | 171 lines / 6,255 bytes total (main.js 128 lines, style.css 22, index.html 21) |
| Library/bundle JS | 865,452 bytes decoded bundle (three.js + app code, minified) | 1.75 MB built JS (deck.gl + MapLibre + luma.gl), ≈482 KB gzip |
| Data on the wire | Compact custom-baked arrays, base64 inside one 3.70 MB HTML (data blobs ≈2.75 MB of it) | GeoJSON 3.3 MB raw / ≈0.80 MB gzip, separate files |
| Delivery shape | One self-contained HTML file, no runtime dependencies | Built app + hosted CARTO basemap tiles at runtime |
The honest read: the scene logic shrinks by roughly an order of magnitude (the incumbent's 894-line script hand-builds geometry, roofs, labels, picking, camera, and day/night; the prototype's 128-line main.js mostly declares layers). The shipped library weight goes the other way — deck.gl + MapLibre is a bigger runtime than three.js alone, and plain GeoJSON is a fatter data format than the incumbent's purpose-baked arrays.
6. What deck.gl gives for free vs what it takes away
Free (hand-rolled in the incumbent): - GPU extrusion of 4,212 polygons with per-feature height/colour accessors — no BufferGeometry code at all. - Picking/hover (incumbent hand-rolls raycasting and its label system). - Camera: pan/zoom/pitch/bearing, inertia, navigation control, and a real map projection — the incumbent maintains its own orbit rig and tangent-plane world. - Basemap with roads/water/labels and attribution; layer composition and restyle-by-props. - Standard GeoJSON in/out — the same data files drop into any other tool.
Taken away (the incumbent's craft is not in the box): - Terrain. The incumbent drapes everything on a 315 × 397 heightmap; hills are land. Here there is no terrain surface — buildings carry their base elevations, so slopes read only as stepping rooftops, and the town feels flatter. - Roofs and heroes. Pitched/gabled roofs (baked roof fraction/type), custom hero geometry for landmarks (Bay Model, Trident, Casa Madrona…), trees, boats, cars — all custom three.js work that deck.gl does not provide. - The day/night simulation. The incumbent syncs sun/moon position, window and storefront glow, and lighting to time of day. The toggle here restyles colours and basemap only — it reads clearly as night, but it is a restyle, not a simulation. - The isometric game's look and control. Fixed-angle diorama framing, baked labels, the whole art direction — deck.gl gives you a map camera and a map feel. On Positron's near-white land/water, the day view's shoreline nearly vanishes; the incumbent's painted ground never has that problem.
7. Legibility / feel verdict
Is it recognisably Sausalito? Yes. From the downtown camera: the Bridgeway commercial spine, the ferry pier, the marina basins cut into the waterfront, terraced hillside streets, the houseboat rows to the north, Tiburon across the water (top-right of frame). Anyone who knows the town can orient instantly; the road network at night makes it unmistakable.
Does day/night read? Yes, unambiguously — warm paper town by day; dark slate town with a glowing street web by night. Night arguably reads better than day in this stack, because the pale Positron day basemap washes out the shoreline while Dark Matter gives the roads contrast.
Feel: it feels like a very good web map of Sausalito, not like the incumbent's crafted diorama. The data is all there; the charm (terrain, roofs, glow) is the part you'd still have to build.
8. Effort log (honest)
- Data hunt: ~15 min. Space source was a dead end (different app — Google 3D Tiles); live site had everything; GitHub clone blocked by sandbox auth (private repo), not needed.
- Extraction + projection reconstruction + anchor validation: ~20 min.
- App scaffold, layers, toggle, HUD, picking: ~30 min including
npm install. Build passed first try. - Verification: ~55 min across four sequential headless runs (software GL is slow). Three real issues found and fixed:
- Sandbox egress proxy env broke CDN fetches inside the test browser (
ERR_TUNNEL_CONNECTION_FAILED) → launched Chromium with--no-proxy-server(direct egress verified working). - deck.gl restyle trap: swapping
getFillColorclosures on toggle silently did not recompute the extruded layer's colours (roads updated, buildings didn't — caught by pixel sampling, not by eye). Fix:updateTriggers: { getFillColor: mode }. A genuine deck.gl lesson worth recording. - CARTO dark-matter style fetch intermittently reset (
ERR_CONNECTION_RESET) → vendored both style JSONs locally; tiles still remote. - Total wall-clock ≈ 2 h, most of it waiting on software-GL renders.
9. Draft verdict + test record
Test record — FINDS - TESTS slate 2, test 2 (2026-11-20) - Subject: deck.gl 9.4.1 + MapLibre GL 4.7.1 + CARTO keyless basemaps, vs hand-rolled three.js. - What ran: the incumbent Sausalito dataset (extracted from sausalito-3d.pages.dev) rebuilt as a deck.gl/MapLibre prototype — extruded buildings, metre-width roads, day/night toggle, HUD counts, hover picking. - Outcome: full dataset rendered and verified in-page (4,212 buildings / 2,105 roads, exact reconciliation); day and night screenshots captured from the same camera; hand-written scene code 171 lines vs the incumbent's 894-line script plus bundled app modules. Recognisably Sausalito; day/night reads clearly. Does not reproduce terrain drape, roofs, hero buildings, or the sun-synced night simulation. - Output reference:
~/workspace/finds-tests/deckgl-sausalito-2026-11-20/(app/,data/,screenshot-day.png,screenshot-night.png, this report). - Reuse proposal: Adopt deck.gl + MapLibre as the default starting stack for data-first web maps (the Pischana typology route and future map finds): an order of magnitude less scene code, free picking/camera/basemap, standard GeoJSON. Keep hand-rolled three.js where the bespoke diorama look is itself the product (the Sausalito map). Watch-outs: addupdateTriggersfor any accessor restyle; budget for terrain/roofs as custom layers if the look matters; GeoJSON is ~4× the wire size of the baked format gzipped.
Framing, as briefed: this is evidence for the Pischana/Odesa stack thinking — it shows the data-first web route is cheap to build and maintain. It is not a decision on the Odesa engine choice (web vs Godot), which remains Ros's alone and paused.

