RFC: GlobeView projection continuity and smooth Mercator fallback

[charlieforward9]

Direction

After discussion, this RFC should focus on one direction: a true globe-to-mercator projection morph inside deck.gl.

The smaller ideas from the original post, such as webMercatorFallbackZoom, fallback ranges, or transition-hold props, are useful only as temporary scaffolding. If GlobeView no longer hard-swaps viewport/projection behavior under the hood, most of those props should not be part of the long-term public API.

The v10/view-layout work is also not a separate solution here. It is a design constraint: whatever we build should fit cleanly into future view architecture, but this RFC is specifically about projection/camera/layer continuity.

Problem

GlobeView needs close-zoom Mercator-like performance, especially on mobile, but a hard switch between globe and Mercator behavior creates visible and behavioral discontinuities.

The cases that matter most:

1. FlyToInterpolator and camera transitions crossing the globe/mercator boundary.
2. Wheel/pinch zoom with cursor or touch anchoring through that boundary.
3. TileLayer imagery and terrain keeping coverage without cache/request churn.
4. Picking and unproject returning coherent results during the transition.
5. User-facing layers such as TileLayer, TripsLayer, paths/icons/text, and widgets continuing to behave as one stable view.

The target behavior is closer to Cesium/Mapbox-style adaptive projection: a shared projection-transition state that the renderer, controller, transitions, picking, and tile selection can all read.

Proposal

Add a deck-level projection transition state for GlobeView, conceptually something like a projectionBlend / morphTime where one end is globe projection and the other end is close-zoom Mercator behavior.

The important properties of the design:

• A stable GlobeView / layer tree; no consumer-level GlobeView ↔ MapView swap.
• No layer ID changes and no forced layer recreation during the transition.
• Shader projection and CPU projection paths agree on the same blend state.
• project, unproject, picking, controller interactions, and FlyToInterpolator use the same projection-transition semantics.
• TileLayer / TerrainLayer tile selection and cache policy are defined early, not treated as a later integration detail.
• The public API should stay small until the behavior is proven.

A possible final API shape could be:

new GlobeView({
  projectionTransition: {
    type: 'globe-mercator',
    startZoom: 12.5,
    endZoom: 14.5,
    tileStrategy: 'coverage'
  }
})

The exact prop names are less important than avoiding a hard projection swap and making the transition state a first-class deck concept.

Near-term PR stack

1. Demo/repro first

   • Add a test/apps demo runnable with start-local.
   • Show the current discontinuity during FlyTo, pointer zoom, and mobile-like interaction.
   • Include the layers/widgets we need to validate: TileLayer, TripsLayer/path animation, icons/text, zoom/compass/layer-list style widgets.
   • Capture screen recordings so reviewers can see the failure before evaluating internals.

2. Projection morph plumbing

   • Add viewport/uniform state for projection blending with no behavior change by default.
   • Keep the API private or experimental while validating the model.

3. Shader + CPU projection MVP

   • Implement the first blend-aware projection path for lng/lat layers.
   • Keep project, unproject, and picking semantics coherent for the supported subset.

4. TileLayer early

   • Define how tiles are selected while the projection is morphing.
   • Preserve TileLayer cache identity and request continuity.
   • Fold in or coordinate with the coverage LOD strategy from feat(geo-layers): coverage LOD tile prefetching #10306 where useful.

5. Controller and transition continuity

   • Ensure pointer-anchored zoom, pinch zoom, drag interaction, and FlyTo transitions all read the same morph state.
   • Add tests for antimeridian crossings, latitude-sensitive perceived zoom, and close-zoom transitions.

6. Broaden layer coverage and docs

   • Extend coverage beyond the initial layer subset.
   • Add docs and examples once the API shape is stable.

Existing context

• Tracker: GlobeView graduation #9199 tracks GlobeView graduation and already lists pitch/bearing/cursor zoom, TileLayer/BitmapLayer low-zoom projection issues, terrain, and projection switching/synchronization as active or remaining work.
• [Feat] MapboxLayer / MapboxOverlay integration with globe projection #7920 discusses Mapbox/MapLibre globe overlay integration and the need for a more generalized projection system.
• GlobeView reprojection issue at low zooms? #9861 is a prior GlobeView reprojection/tile issue at low zooms.
• feat(core): GlobeController with inertia, tilt & pan #10298 adds GlobeController inertia, tilt, and pan.
• feat(core): GlobeView pointer-anchored zoom (wheel + transitions) #10307 adds opt-in pointer-anchored GlobeView zoom and transition anchoring.
• feat(geo-layers): coverage LOD tile prefetching #10306 proposes opt-in TileLayer/TerrainLayer coverage LOD prefetching.
• RFC: Add view layout compiler #10269 and Add layout expressions for view positions #9842 improve declarative view layout / view positioning, but they do not solve projection morphing directly.

Open questions

• Should the blend be driven purely by zoom, explicitly by view state, or both?
• What common space should the morph use so shader projection, CPU projection, and picking remain consistent?
• How should TileLayer choose current/target/coverage tiles during the morph?
• Which coordinate systems should be supported in the MVP beyond COORDINATE_SYSTEM.LNGLAT?
• How should terrain, billboards, depth/culling, and antimeridian handling be staged?

[charlieforward9]

CC @ibgreen @chrisgervang @felixpalmer

[chrisgervang]

Thanks for compiling this. It's helpful context since its been a while since I've thought about this..

I'm most interested in pursuing 3, a true globe-to-mercator projection morph. The other API changes proposed here seem like bandaids and unnecessary if the view isn't hard-swapped under the hood. In other words, if we do 3, how much of 1 and 2 is necessary?

It's unclear what 4 means since I believe it'd depend on the earlier parts.. is there something concrete to consider right now, or is it moreso a guiding principle?

Suggested demos/tests

Demos that show the issues would be super valuable here. A lot of these issues are only visible in transitions or on mobile, which our existing demos don't cover. Feel free to add to test/apps so we can take advantage of start-local.

[charlieforward9]

You got it! I updated the description to reflect the state.

Im running low on weekly LLM credits - so I will hold off on this till the usage limit resets and I have some more time to focus on this.

[charlieforward9]

Prompts to initiate

Below I have included the prompts generated by GPT5.5 extra-high to initiate this pursuit - open to feedback - adjustment

[charlieforward9]

Prompt 1: Start In Standalone deck.gl

You are working in the standalone visgl/deck.gl repository, not NEW_HEAT and not a vendored submodule. First verify the repo root and remotes. If the cwd is inside NEW_HEAT or vendor/deck.gl, stop and tell me.

Context:
- RFC: https://github.com/visgl/deck.gl/discussions/10343
- Chris’s direction: focus on true globe-to-mercator projection morph. The fallback/hold props are bandaids unless needed as private scaffolding.
- Start with demos in test/apps so reviewers can see the current issue via start-local.

Task:
Create the first PR in the stack: a demo/repro app only, no core projection implementation yet.

Add `test/apps/globe-projection-continuity` with:
- `start-local` support matching other test apps.
- A controlled GlobeView scene that clearly shows the current hard-switch / projection-continuity problem.
- Scenarios/buttons:
  - Fly SF -> Tokyo at close zoom.
  - Fly across the antimeridian.
  - Zoom through the close-zoom transition using pointer/wheel.
  - Mobile-sized viewport mode.
- Layers to validate our real use cases:
  - `TileLayer` with `BitmapLayer` sublayers using a tokenless public tile source.
  - `TripsLayer` or animated path/trip data.
  - Icons/text if cheap to add.
  - Widgets such as `ZoomWidget`, `CompassWidget`, and `StatsWidget` if available.
- Add a small on-screen debug overlay showing zoom, longitude/latitude, viewport/projection mode, transition state if available, and basic tile load/cache counters if practical.
- Add a README with exact recording checklist and expected failure modes.

Constraints:
- Do not copy NEW_HEAT app code.
- Do not add a public API yet.
- Do not fix projection morph in this PR.
- Do not depend on fork-only APIs unless they are already merged into upstream master; if an open PR is needed, note that dependency.

Verification:
- Run the focused checks needed for the new test app.
- If a browser smoke test is practical, run `yarn start-local` from the test app and capture what should be recorded.
- End with a PR-ready summary, test commands, and remaining follow-up items.

Prompt 2: Next Agent / Morph Plumbing

You are in standalone visgl/deck.gl. Continue from the projection-continuity demo PR and RFC #10343.

Goal:
Start the implementation stack for true GlobeView globe-to-mercator projection morphing. Keep this PR narrow but do not punt TileLayer; tile continuity must be considered early.

Task:
Add internal projection-morph plumbing with minimal behavior change by default.

Implement:
- A private/experimental projection blend state on GlobeViewport/GlobeView, conceptually 0 = globe and 1 = mercator.
- Pass the blend through project uniforms for GLSL and WGSL.
- Add tests proving the viewport state and uniforms are wired correctly.
- Add a small internal helper for zoom-driven blend calculation, but keep public API conservative.
- Update the demo app from PR 1 to display the blend value when enabled.
- Inspect TileLayer/Tileset2D traversal and document exactly where tile selection should read current/target/coverage projection state. If a small non-invasive hook is needed now, add it; otherwise leave a precise TODO and test plan.

Do not:
- Replace all shader projection logic in this PR.
- Add a polished public API before the behavior is proven.
- Break existing GlobeView behavior when morph is disabled.

Validation targets:
- Existing GlobeView viewport tests.
- Project uniform tests.
- Demo still runs with TileLayer, TripsLayer/path, and widgets.
- Summarize the next PR: shader/CPU projection MVP for TileLayer/BitmapLayer and TripsLayer/path first.

Prompt 3: TileLayer + First Real Morph MVP

You are in standalone visgl/deck.gl, not NEW_HEAT. Continue from the GlobeView projection-continuity demo and morph-plumbing work tied to RFC #10343:
https://github.com/visgl/deck.gl/discussions/10343

Goal:
Implement the first real projection morph MVP, with TileLayer handled early. This PR should prove that globe-to-mercator blending can render real layers without a hard viewport swap.

Focus layers:
- TileLayer + BitmapLayer sublayers
- TripsLayer or PathLayer-based animated route data
- IconLayer/TextLayer if already present in the demo
- Widgets should remain stable and usable

Task:
- Implement blend-aware projection for the initial lng/lat path in the project shader.
- Add matching CPU projection semantics where needed for `project`, `unproject`, and picking in the supported subset.
- Ensure TileLayer selection/cache identity remains stable while morphing.
- If full tile selection is too large for this PR, implement the smallest real hook needed so TileLayer can receive/read morph state, and add focused tests around cache/layer identity.
- Update `test/apps/globe-projection-continuity` to toggle hard-switch vs morph mode.
- Show visual debug values: zoom, blend, viewport type/projection mode, tile load state.

Do not:
- Solve every coordinate system.
- Over-polish public API names.
- Recreate layers or change layer IDs during morph.
- Hide TileLayer problems behind a later TODO.

Verification:
- Add focused shader/projection tests where existing test patterns allow.
- Add viewport/project/unproject tests for blend endpoints and midpoint.
- Run the demo and document expected screen recording steps.
- End with a clear list of supported layers and known unsupported layers.

Prompt 4: Camera, FlyTo, Pointer Zoom

You are in standalone visgl/deck.gl. Continue the GlobeView projection morph stack from RFC #10343.

Goal:
Make camera movement continuous through the morph range.

Task:
- Ensure FlyTo transitions read the same projection blend state as rendering.
- Preserve FlyTo zoom timing while using globe-aware/geodesic lng/lat motion where appropriate.
- Test SF -> Tokyo, antimeridian crossing, and close-zoom transitions through the morph range.
- Ensure pointer-anchored wheel zoom and pinch zoom stay anchored while blend changes.
- Ensure drag/pan interaction does not force hard switches or reset unexpectedly.
- Update `test/apps/globe-projection-continuity` with buttons for all transition cases.

Key principle:
There should be one projection-transition state shared by rendering, transitions, picking, and controller interaction. Do not add app-level mode switching.

Verification:
- Focused controller/transition tests.
- Demo recording checklist.
- Note any dependency on open PRs such as pointer-anchored GlobeView zoom.
Prompt 5: Mobile + Performance Validation

You are in standalone visgl/deck.gl. Continue the GlobeView projection morph stack from RFC #10343.

Goal:
Validate that the morph path is actually better for mobile and tile-heavy usage.

Task:
- Add mobile-sized mode to the demo, if not already done.
- Profile/inspect TileLayer request behavior during morph transitions.
- Confirm layer IDs and tile cache identity do not churn during camera transitions.
- Add visible tile/debug counters if practical.
- Compare hard-switch mode vs morph mode in the demo.
- Add or update tests for tile request continuity, selected tile stability, and cache preservation.
- Verify widgets remain responsive and visually stable during morph.

Layers to include:
- TileLayer/BitmapLayer
- TripsLayer or PathLayer animated route
- IconLayer/TextLayer if already included
- ZoomWidget, CompassWidget, StatsWidget or nearest equivalents

Deliverables:
- Short performance notes.
- Recording checklist.
- Any recommended follow-up to #10306 coverage LOD prefetching.

Prompt 6: API Hardening + Upstream PR Packaging

You are in standalone visgl/deck.gl. Continue the GlobeView projection morph stack from RFC #10343.

Goal:
Turn the proven morph prototype into an upstreamable API and PR series.

Task:
- Review the implementation and decide the smallest stable public API.
- Prefer a compact GlobeView prop such as:
  `projectionTransition: {type: 'globe-mercator', startZoom, endZoom, tileStrategy?}`
  only if the behavior is proven.
- Remove temporary names or private scaffolding that leaked into public API.
- Add docs for GlobeView projection continuity.
- Update the demo README with before/after recordings.
- Add migration notes explaining that this avoids consumer-level GlobeView/MapView swaps.
- Summarize how this relates to:
  - #9199 GlobeView graduation
  - #10306 TileLayer coverage LOD
  - #10307 pointer-anchored zoom
  - #10298 GlobeController inertia/tilt/pan

Verification:
- Run focused unit tests for viewport/project/controller/tile changes.
- Run the demo with start-local and produce a concise recording checklist.
- End with a PR stack summary: what landed, what remains, and what reviewers should inspect first.