feat(layers): math.gl bitmap UV subdivision (2/3)

[ibgreen]

Follow up of #10835

Background

Uniform bitmap grids spend vertices in areas with little distortion. Adaptive subdivision in UV space preserves bilinear quadrilateral bounds while refining projection curvature, including triangle interiors. This PR is independent of the converter adapter.

Change List

• Add opt-in BitmapLayer._projectionTolerance in map meters
• Refine existing meshes with math.gl subdivideTriangleMesh
• Preserve bilinear bounds, altitude, UVs, and picking
• Rebuild meshes when model matrices or coordinate systems change
• Reuse projected positions without applying the converter twice
• Documentation

Verified with yarn exec ocular-build layers and yarn lint. Passed 7 bitmap headless tests. Visual checks were not run.

---

Note

Medium Risk
Touches core bitmap mesh generation and vertex attributes for custom projections; opt-in and default-off, but bad tolerance or seams can throw or increase vertex counts up to math.gl caps.

Overview
Adds an experimental BitmapLayer._projectionTolerance option (map meters, default 0) so bitmap geometry can be adaptively subdivided on preprojecting viewports (e.g. CustomProjectionView) instead of relying only on a uniform resolution grid.

Refinement runs in UV space via @math.gl/polygon’s subdivideTriangleMesh, keeping bilinear bounds-to-texture mapping (including non-rect quads and altitude) while sampling projected error through the layer’s position transform. Refined meshes expose projectedPositions so the position attribute skips re-applying model matrix/projection. Meshes rebuild when bounds, tolerance, coordinate system, projection, or (on preproject viewports) modelMatrix change; tolerance without a preprojecting viewport throws.

Docs describe limits, seam/domain requirements, and incompatibility with coordinateSystem: 'cartesian'. Tests cover UV/altitude preservation, modelMatrix rebuilds, and turning refinement off.

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

[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-10T12:00:09.039108Z	43409e7	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.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge, with no outstanding findings.

Summary

Adds opt-in bitmap mesh refinement through _projectionTolerance for preprojecting views.

• BitmapLayer can refine its mesh to a map-meter projection tolerance.

No new actionable issues were found. Tests were inspected but not run.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Bitmap bounds and resolution] --> B{Positive tolerance?}
  B -->|No| C[Existing mesh]
  B -->|Yes| D[Refine in UV space]
  D --> E[Map UVs to four-corner bounds]
  E --> F[Apply model matrix and projection]
  F --> G[Store projected positions]
  G --> H[Upload without projecting again]
  C --> I[Existing position transform]

Loading

_{Reviews (2) · Last reviewed commit: "test(layers): cover adaptive bitmap refi..." · 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 43409e7. Configure here.}

[coveralls]

coverage: 83.513% (-0.004%) from 83.517% — codex/math-bitmap-subdivision into master

[charlieforward9]

supercedes #10350 and closes #10011 ?

[ibgreen]

@charlieforward9 Thanks for connecting these. I compared the current diffs: this PR does not supersede #10350 or close #10011 by itself.

#10836 adds opt-in adaptive UV mesh subdivision for CPU preprojecting viewports (such as CustomProjectionView), using a sampled error tolerance in map meters. Its default is off, and the refinement path is not enabled for the current GlobeView.

#10350 addresses separate correctness issues: rebuilding bitmap geometry and coordinate-conversion uniforms when the viewport mesh resolution changes, plus remapping Mercator-spaced TerrainLayer rows for curved rendering. Neither fix is included here.

These changes can coexist. The reusable math.gl subdivision utility provides a useful foundation for future globe refinement, but the GlobeView lifecycle and terrain coordinate fixes still need their own validation. I would keep #10350 and #10011 open until that work lands and the low-zoom reproduction is verified.