feat(layers): math.gl path and polygon refinement (3/3)

[ibgreen]

Follow up of #10835

Background

Source grids do not adapt to nonlinear projection curvature. This independent PR adds sampled map-space edge refinement while retaining existing grid cuts and separate polygon triangulation.

Change List

• Add _projectionTolerance to paths and polygon layers
• Densify paths and closed rings with math.gl subdividePolyline
• Preserve holes, closure, altitude, and hidden cut-edge flags
• Forward tolerance through PolygonLayer fill and outline sublayers
• Rebuild all geometry when refinement configuration changes
• Reject unsupported pre-tessellated buffers and per-vertex path styles
• Documentation

Verified with yarn exec ocular-build layers and yarn lint. Passed 38 focused path/polygon headless tests. Local render checks timed out capturing screenshots on this update; prior CI passed.

---

Note

Medium Risk
Opt-in but changes core tessellation and attribute handling for paths/polygons; invalid configs throw at runtime and densification can increase CPU/memory cost.

Overview
Adds an experimental _projectionTolerance option on PathLayer, SolidPolygonLayer, and PolygonLayer so paths and polygon rings can adaptively densify edges under preprojecting viewports (e.g. CustomProjectionView). A positive value is a sampled edge-error budget in map meters; 0 keeps current behavior.

Tesselators call math.gl subdividePolyline after existing grid/longitude cuts, using the layer’s preprojection transform. Polygon refinement handles outer rings and holes separately and keeps cut-edge visibility; fill triangulation stays separate from boundary subdivision. PolygonLayer passes tolerance through to fill and outline sublayers and drops _pathType: 'loop' on the outline when refinement is on so paths stay normalized.

Layers rebuild all geometry when tolerance, projection, or related config changes (including alongside a partial _dataDiff), and throw for unsupported setups: GPU-only geometry buffers, pre-tessellated attribute layouts, per-vertex colors/widths/elevations, or paths with _pathType set. When refinement is enabled, attribute transforms enforce per-object styling and handle RGB vs RGBA accessors.

Docs cover limits (linear interpolation, no great-circle clipping, math.gl vertex/bisection caps) and What's New mentions the feature under custom projections. Tests cover tolerance behavior, validation, RGB attributes, transitions, and tesselator correctness.

^{Reviewed by Cursor Bugbot for commit 6bf78ef. 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:04:42.996216Z	d37e8e8	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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d37e8e88a6

ℹ️ 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".

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge, with no new actionable issues found.

Summary

Adds opt-in _projectionTolerance to refine path and polygon edges under custom projections.

• Paths gain points where a map projection bends their edges.
• Polygon edges gain matching refinement in fills and outlines.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Source paths and rings] --> B[Normalize and apply existing grid cuts]
  B --> C{Positive tolerance?}
  C -->|Yes| D[Refine source edges using projected samples]
  C -->|No| E[Project vertices]
  D --> E
  E --> F[Build path segments or polygon triangles]

Loading

_{Reviews (7) · Last reviewed commit: "fix(layers): update refinement settings ..." · Reviewed by Greptile}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[ibgreen]

Fixed the CI binary-data render regression in a7828ab. Even a no-op attribute transform forces binary attributes through CPU conversion; with refinement disabled, this converted float colors into the default unorm8 representation and made paths/polygons black. Styling transforms are now attached only while _projectionTolerance is enabled and removed when it is disabled.

Added four regression tests covering binary float color preservation and toggling refinement off for PathLayer and SolidPolygonLayer. All 36 focused headless tests, the binary-data WebGL render test, the layers build, and lint pass locally. The first render retry encountered a browser connection failure; the next run passed. CI is rerunning on the new commit.

[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 a7828ab. Configure here.}

[coveralls]

coverage: 83.589% (+0.07%) from 83.517% — codex/math-ring-subdivision into master