feat(core): Viewport classes depend on math.gl projectionEngine

[Pessimistress]

For #10739

TL;DR

• Offload CustomProjectionViewport CRS handling to math.gl
• Moderate breaking changes to base Viewport class (remove assumptions about coordinate system and projection mode)
• Existing geospatial viewports (WebMercator, FirstPerson, Globe) are refactored but expect no behavioral change

Change List

• Depend on published @math.gl/projection alpha.17
• Share CRS resolution with synchronous access to loaded descriptors
• Base Viewport adds crs: CRSDescriptor property, drops longitude latitude, no longer contains web-mercator projection as geospatial fallback
• Rewrite WebMercatorViewport, FirstPersonViewport with CRS descriptor. Custom CRS OSMTile512 describes MVT coordinate space.
• Rewrite GlobeViewport with standard geocentric CRS. World-space axes now match proj=geocent and are aligned to deck.gl common space with viewMatrix. Winding direction is not affected. Add earthModel option to switch between WGS84 ellipsoid and v9.4/maplibre sphere.
• CustomProjectionViewport drops projection, toBounds and getDistanceScale options. Use math.gl-resolved CRS descriptor to handle coordinate conversion, normalization, bounds, and distance scales.
• CustomProjectionViewport drops fromCrs in preparation for layer-owned source CRS
• Add projectPosition(position, {sourceCrs}) for explicit input CRS conversion
• Tests, docs, and upgrade guide

---

Note

High Risk
Breaking changes to base Viewport and experimental CustomProjectionView APIs, plus refactors of all built-in geospatial viewports and coordinate/distance-scale paths that affect rendering and picking across the stack.

Overview
This PR routes deck.gl viewports through @math.gl/projection CRS descriptors instead of ad hoc converters and implicit Web Mercator from longitude/latitude.

Custom projections are the largest API shift: _CustomProjectionView now takes a crs string (async initialize()), WGS84 layer/camera/bounds semantics, and drops projection, fromCrs/toCrs, fromBounds/toBounds, and getDistanceScale. _CustomProjectionViewport uses descriptor converters, renderingBounds, and getRenderingScale for meter sizing and invalidation signatures.

The base Viewport gains optional crs, targetToCommonMatrix, and callable distanceScales; geospatial mode follows the descriptor, not lng/lat alone. WebMercatorViewport, FirstPersonViewport, and GlobeViewport attach built-in descriptors (OSMTile512, geocentric GLOBE_CRS) while keeping Mercator/globe shader behavior; resolveCRS caches WGS84/globe/built-ins and async projectionEngine.getCRS. projectPosition(..., { sourceCrs }) allows explicit input CRS. Aggregation uses a linear AggregationViewport instead of identity custom projection hacks.

Docs, v10 upgrade notes, the custom-projection demo, and tests move to the new model; ProjectionConverter is removed from public types.

^{Reviewed by Cursor Bugbot for commit fd28038. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[coveralls]

Coverage is 83.723% — codex/crs-descriptor-integration into codex/async-view-resolution. No base build found for codex/async-view-resolution.

[greptile-apps]

Confidence Score: 4/5

[High impact] Core viewport classes now depend on math.gl projection engine.

Update the dependent render case in PR #10874 before merging the renamed option into the stack.

Findings

1.  Dependent render test breaks ▶

Summary

Moves viewport coordinate conversion and distance scales to math.gl CRS descriptors. The latest changes rename the custom view option to crs and keep the base Viewport on identity shaders.

• Geospatial viewports now describe their coordinates with CRS descriptors.
• Custom projection views now use math.gl CRS descriptors for map coordinates.
• Aggregation layers now scale already-projected coordinates linearly.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[CustomProjectionView crs string] --> B[resolveCRS]
  B --> C[Prepared CRS descriptor]
  C --> D[CustomProjectionViewport]
  D --> E[Coordinate conversion and distance scales]

Loading

_{Reviews (3) · Last reviewed commit: "rename toCrs to crs" · Reviewed by Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fd28038. Configure here.}

[cursor]

CRS viewports produce NaN shader origins

Medium Severity

A base Viewport with a crs is geospatial but now reports IDENTITY projection. Uniform setup still treats that combination as a lng/lat camera and reads longitude/latitude, which the base class no longer has, so geospatialOrigin and the shader origin become NaN. GPU rendering of this documented CRS camera is therefore invalid, even though CPU projectPosition still works.

 

^{Reviewed by Cursor Bugbot for commit fd28038. Configure here.}

[Pessimistress]

This will be addressed in #10874