Explore editable deck.gl overlays on Google Maps 3D Map3DElement

[charlieforward9]

Context

We need an editable Google Maps 3D surface that can eventually host Strava-quality GeoJSON editing on top of google.maps.maps3d.Map3DElement without falling back to a different basemap. The goal is to reuse the deck.gl / editable-layers interaction model through an adapter, not rebuild all drawing/editing behavior from scratch.

Relevant starting point:

• Draft PR: WIP: experiment with Google Maps 3D overlay support #10401
• Local branch: codex/google-maps-3d-overlay-prototype
• Local worktree: /Users/rich/Code/visgl/_worktrees/google-maps-3d-overlay-prototype
• Local demo path: examples/website/google-map-3d-overlay-prototype

Current Prototype

• GoogleMapsOverlay#setMap accepts gmp-map-3d / Map3DElement in addition to google.maps.Map.
• Map3D adapter derives deck view state from center, range, heading, tilt, and fov.
• Map3D camera events trigger redraws.
• A passive WebGL context capture hook records a Map3D WebGL context if Google creates one after the overlay is constructed.
• If capture fails, the overlay warns and falls back to a non-interleaved DOM deck canvas instead of touching Google GL state.
• Focused tests cover Map3D detection, camera view-state derivation, and safe fallback when internals are not captured.

Local Demo Command

cd /Users/rich/Code/visgl/_worktrees/google-maps-3d-overlay-prototype
ln -s /Users/rich/Code/visgl/deck.gl/node_modules node_modules 2>/dev/null || true
export GoogleMapsAPIKey=<localhost-allowed Maps JS key>
cd examples/website/google-map-3d-overlay-prototype
../../../node_modules/.bin/vite --config ../../vite.config.local.mjs --host 127.0.0.1 --port 8093

Open: http://127.0.0.1:8093/

Current Blocker

• The local demo boots, loads gmp-map-3d, and reaches the overlay fallback path.
• The available NEWHEAT key is valid but rejects this standalone origin with RefererNotAllowedMapError on 127.0.0.1 and localhost.
• A second local key candidate was invalid for Maps JS.
• Need a Maps JS key whose HTTP referrers allow the standalone dev origin, or a permitted local host/origin setup.

Rabbit Hole / Next Steps

• Verify visible alignment in the local demo once the key/origin blocker is cleared.
• Decide whether Map3D should start in non-interleaved overlay mode by default until shared-GL draw-after-Google-render can be proven.
• Extend the adapter to expose enough picking/event data for editable-layers handles.
• Prototype EditableGoogleMap3DLayer as an adapter over editable-layers rather than a new editor.
• Use native Map3D polylines/polygons as visual comparison only; deck.gl should remain the editable layer engine.
• Keep the initial implementation local/prototype until the adapter is stable enough for upstream review.

References

• Google Maps JS Map3D reference: https://developers.google.com/maps/documentation/javascript/reference/3d-map
• Draft PR: WIP: experiment with Google Maps 3D overlay support #10401

[charlieforward9]

Follow-up from the prototype dev server:

Non-interleaved Deck-over-Map3D is not acceptable as the authoritative route/editing surface. The Deck canvas can visibly drift during pan/tilt because the public Map3D surface does not expose the same terrain/projection/depth contract as Google's native 3D renderer.

Current prototype direction:

• Use native Polyline3DElement / future native Map3D geometry for locked route display where possible.
• Keep Deck fallback explicit and debug-only for now.
• Continue pushing toward shared WebGL/projection capture or an adapter that can make editable-layers-style handles work without lying about terrain-locked paths/polygons.
• Added cameraPosition altitude handling/tests as an incremental camera-sync improvement, but this is not enough for polished Strava-quality editing on Map3D by itself.

[charlieforward9]

Prototype update: the local demo now has a native Map3D editor shell. It keeps the display/edit geometry in Google's native 3D elements, with Deck disabled by default and only available as approximate debug.

Implemented locally in the demo:

• point/path/polygon mode state
• Map3D click-to-add using gmp-click positions
• click existing path/polygon to insert nearest segment vertex
• native 3D vertex markers for selection/delete
• undo/reset
• GeoJSON serialization/export

This preserves the core constraint from the drift test: until shared GL/projection/depth is real, editable geometry should not be authored against the non-interleaved Deck canvas. Next useful rabbit hole is adapter hardening: drag handles if Google exposes a supportable path, snapping/routing, and a bridge from editable-layers/TerraDraw-style edit operations into this native Map3D geometry adapter.

[charlieforward9]

Adapter update: extracted the Map3D editor semantics into a pure operation module and covered it with focused tests.

This matters for the editable-layers/TerraDraw question: the current experiment now has a renderer-neutral operation boundary that can be driven by native Map3D clicks today, and later by editable-layers/TerraDraw-style edit events without changing the native Map3D rendering adapter.

Current supportable UX now includes:

• click-to-add point/path/polygon vertices
• click path/polygon to insert nearest-segment vertex
• select/delete/undo/reset
• move selected vertex by arming Move Selected and using the next documented Map3D click position
• GeoJSON export

Still not claiming true drag handles until there is a documented supportable Map3D drag/pointer coordinate path or shared GL/projection/depth path.

[charlieforward9]

Prototype update after 7406654:

• Editor operations are now module-level typed utilities in @deck.gl/google-maps, with the standalone Map3D demo consuming those exports.
• Native Map3D geometry remains the authoritative editing surface for now: point/path/polygon use Map3D elements with CLAMP_TO_GROUND and occluded segment drawing where the current API supports it.
• Deck remains a diagnostic overlay, not the source of truth. The Map3D path now avoids Google depth-buffer participation (depthTest: false, depthMask: false) and no longer uses Map3D center altitude as Deck viewport elevation, which addresses the visible z/bob drift during pan.
• Live browser probe: gmp-map-3d did not expose a reachable Google canvas; only Deck fallback canvas was present in DOM, so the prototype currently reports DOM overlay fallback in that browser. This reinforces the adapter boundary: do not claim terrain-locked Deck geometry until a real Map3D projection/shared-context path is proven.
• Demo runtime fix: removed unsupported polygon outerColor/outerWidth options rejected by current Polygon3DInteractiveElement.

Local dev server remains up at http://127.0.0.1:5173/ for manual inspection.

[charlieforward9]

Prototype update after f45ee0d:

• Added map3DDepthMode?: "screen" | "mesh" to the experimental GoogleMapsOverlay Map3D path.
• screen keeps Deck as a stable compositor/debug overlay.
• mesh requests shared-GL depth testing against Google Map3D depth (depthTest, LEQUAL, no depth writes). This is the closest Deck-side toggle to Map3D-style mesh occlusion, but it only works when the Map3D shared WebGL context is captured.
• Demo now exposes Deck: Screen / Deck: Mesh Depth, with bright green/yellow Deck debug colors so it is clear what is Deck versus native Map3D geometry.
• Latest live browser finding: the user screenshot was native Map3D geometry. Deck debug was off, and the page was in DOM overlay fallback. After toggling Deck debug, Deck appears as a separate bright route; toggling mesh depth reports deck mesh-depth requested (shared WebGL unavailable) because the real Google Map3D canvas is still not reachable/captured in that browser.

This preserves the current product contract: native Map3D geometry remains the authoritative clamp-to-ground editor surface; Deck mesh-depth is an experimental mode gated by proven shared GL.

[charlieforward9]

Follow-up from the local alignment pass on the Map3D editor prototype:

The visible Deck drift was not a data mismatch. Native Map3D geometry and Deck were using the same route coordinates. The main fallback projection bug was in the Map3D cameraPosition zoom path: it used vertical camera height without the pitched-camera cos(tilt) correction, so steep views were over-zoomed and Deck geometry walked away from the native Map3D clamp-to-ground path.

bc2aa71e75d0b0fee4898e2c86d10d563b9cf1ff fixes that in the draft PR, adds gmp-steadychange redraws, and removes an unsupported demo path outline option that was producing Google Maps constructor errors. Local browser verification shows the Deck debug route back on the same corridor as the native Map3D route in screen and mesh-depth fallback modes. Shared WebGL capture is still the harder path for true mesh-depth terrain locking.