feat(core): math.gl projection alignment (1/3)

[ibgreen]

Follow up of #10802

Background

Custom projection sizing guesses source units from CRS strings. This series adopts math.gl alpha.15 through an optional adapter, adaptive bitmap UV meshes, and path/polygon ring subdivision in three independent PRs.

Change List

• Add optional @deck.gl/core/projection converter factory
• Prepare selected algorithms before synchronous rendering and picking
• Resolve loaders.gl CRS descriptors through math.gl
• Use normalized source units and ellipsoid for sizing
• Reject incompatible axes, targets, and lossy transforms
• Documentation

Verified with yarn, yarn build, and yarn lint. Passed 3 focused adapter tests.

---

Note

Medium Risk
Changes coordinate conversion contracts and meter sizing for custom projections, but the new path is optional and guarded by strict CRS/axis validation.

Overview
Adds an optional @deck.gl/core/projection entry that exposes createProjectionConverter, which builds math.gl ProjectionTransform instances ahead of time and wraps them in deck’s ProjectionConverter shape (sync forward/inverse, height preserved). The main @deck.gl/core bundle does not pull in the projection engine; consumers opt in via an optional peer on @math.gl/projection alpha.15.

The factory normalizes loaders.gl/math.gl CRS descriptors, enforces longitude/latitude or east/north/up order, requires a planar meter target, and rejects lossy transforms. It attaches sourceCoordinates (kind, unit scale, ellipsoid) so CustomProjectionViewport can size layers from declared units (degrees, radians, feet) instead of guessing from fromCrs strings.

Docs cover the adapter usage and limitations; vitest pre-bundles math.gl projection deps for the new adapter tests.

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

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issue remains from this review.

Summary

Adds an optional math.gl converter for custom projection views and uses source units and ellipsoid values for meter sizing.

• Custom projection views can use prepared math.gl converters.
• Custom projection sizing follows the converter's source units.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Source and target CRS] --> B[Validate coordinate order and target units]
  B --> C[Prepare math.gl transform asynchronously]
  C --> D[Reject lossy transforms]
  D --> E[Synchronous forward and inverse converter]
  E --> F[Rendering and picking]
  E --> G[Source units and ellipsoid guide meter sizing]

Loading

_{Reviews (3) · Last reviewed commit: "test(core): include projection adapter i..." · Reviewed by Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: af78af8874

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-10T11:58:08.075167Z	af78af8	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coveralls]

coverage: 83.515% (-0.002%) from 83.517% — codex/math-projection-adapter into master