[StrawberryJam22]

With terrain enabled on the mercator projection, pan and pinch-zoom gestures lose the terrain point grabbed at gesture start. This PR fixes the pan/zoom case; the rotation drift family of #2937 is a separate follow-up.

The bug

In-gesture solves intersect the horizontal plane at the frozen center elevation (elevationFreeze), and on frames where a drag is in progress the pinch anchor is dropped entirely: handleMapControlsRollPitchBearingZoom has already applied the zoom about the screen center, and the drag branch in HandlerManager._handleMapControls applies the pan as a raw center pixel-shift. Terrain under the fingers at a different elevation moves at a different pixels-per-meter rate, so the grabbed terrain point slips out from under the fingers by roughly the centroid travel — while the identical gesture with terrain disabled is exact.

We hit this in an iOS app embedding GL JS in a WKWebView over high-relief terrain, and measured it with synthetic two-finger TouchEvent sequences driven through the real handler stack over Chamonix (terrarium raster-dem, zoom ~12.6): a moving-centroid pinch-in with ~103 px of centroid travel slips the grabbed mountain 125.8–136.8 px per gesture (release-time drift against the live finger midpoint), pinch-out 44–46 px, pitch-independent (as bad at nadir as at pitch 66), and ~0 px with terrain off in the identical scenario. A fixed-centroid pinch stays clean (4.4–7.2 px), which is why scripted symmetric pinches miss it. Re-pinning the grabbed point from outside via setLocationAtPoint once per frame does not work — the handler re-derives its own center-plane solution every frame while fingers are down, so the correction only lands at release; the fix has to live in the gesture path.

The fix

Capture the elevation of the terrain point under the gesture once at gesture start (from the terrain coords-framebuffer raycast, terrain.pointCoordinate), and solve the whole gesture — pan and pinch zoom alike — against the horizontal plane at that elevation, using the same anchored code path the flat map uses (handleMapControlsPan → setLocationAtPoint, with the anchor plane threaded through MapControlsDeltas.aroundElevation into setLocationAtPoint's new elevation parameter). The anchor is fixed geography, so its elevation is stable for the whole gesture even while terrain tiles keep loading mid-gesture — unlike the center's elevation, which changes as the map moves under a frozen screen point.

• MercatorTransform.setLocationAtPoint(lnglat, point, elevation?) solves the pick ray on the plane at elevation (default: previous behavior). The center term stays a ray ∩ z=0 solve through the same inverse pixel-matrix, which keeps the matrix-inversion error cancelling out of the a − b difference; it must not be intersected with the elevated plane, since that point sits (elevation − centerElevation)·tan(pitch) away from the center and would make the solve run away at pitch. (The old z = mercatorZfromAltitude(...) value was mercator-units in a meters-typed slot, i.e. numerically ~0; the new code states the units it actually uses.)
• HandlerManager captures _terrainGestureAnchorElevation at gesture start and clears it when movement finishes (same lifetime as the existing elevation freeze); preZoomAroundLoc is computed on the anchor plane via the new ITransform.screenPointToLocationAtElevation.
• When the anchor is unavailable, the code falls back to the previous behavior: raycast returns null (terrain not loaded / sky) → previous path for the whole gesture; around is, or collapses to, the center point (center-anchored pinches, fingers past the horizon guard) → previous path for that frame; anchor plane within 10% of the camera altitude (extreme zoom-in toward a peak) → previous path for that frame.
• Globe controls are untouched (useGlobeControls branch; the vertical-perspective transform ignores the elevation parameter — there is no flat ground plane to offset); a globe style rendering mercator inherits the fix through the delegating transform.

Measurements (before/after)

Same harness as above, v6.1.0 stock vs this branch — a 24-cell matrix ({terrain on/off} × {pitch 66/0} × {around: touch/center} × {fixed-centroid in / moving in / moving out}) plus 7 shim-instrumented diagnostic cells. Drift in px of the grabbed terrain point against the live finger midpoint at release:

cell (default touch mode, terrain on)	stock	fixed
moving pinch-in, pitch 66	125.8	7.5
moving pinch-in, pitch 0	136.8	7.8
moving pinch-out, pitch 66	44.0	0.5
moving pinch-out, pitch 0	46.3	0.7
fixed-centroid pinch (control)	4.4 / 7.2	4.4 / 7.2 (unchanged)

The residual 7.5–7.8 px is comparable to the fixed-centroid control (4.4–7.2 px), i.e. at the harness noise level. Release drift is bit-identical in every terrain-off cell; center-anchored cells change by at most 0.04 px (the moving pinch-out cells — pan-component frames where around is the centroid now use the anchored solve). Wheel zoom over terrain also anchors to the terrain elevation under the cursor now.

Reproducing manually

Run a terrain example (e.g. the 3D terrain example) over high relief, pitch and zoom to a mountainside, then do a two-finger pinch whose midpoint travels across the slope (or the same with a drag). On main the terrain feature you grabbed slides away from your fingers by roughly the distance your fingers travel; on this branch it stays under them. Terrain off is unaffected.

Tests

The first commit adds three gesture tests (full synthetic-touch sequences through the real handler stack, terrain stubbed with createTerrain()): the two terrain cases fail on main — the grabbed point slips 7.7 px and 20.1 px for these small synthetic gestures, the unit-scale analogue of the slips above — while the flat control passes. The fix commit makes them pass, tightens the tolerance to 0.5 px, and adds five more cases: a pitched (60°) pinch (pins the tan(pitch) failure mode of a naive plane solve), a drag over a 2000 m ridge with a non-zero frozen center elevation (pins the relative-plane math), capture-once-per-gesture while terrain "loads" mid-gesture, wheel zoom capturing the terrain elevation under the cursor as the gesture anchor, the center-anchored-pinch pan path, and the raycast-null fallback. A follow-up commit adds three small tests covering the near-camera fallback guard and the globe/vertical-perspective delegation paths (flagged by Codecov). Existing suite: all green.

Known scope edges (deliberate)

• The inertia fling after release still re-anchors on the center plane (handler_inertia → easeTo); measured effect in our harness is a few px between release and settle. Candidate follow-up, kept out to keep this reviewable.
• The rotation drift of rotateCamera does not work properly with terrain exaggeration #2937 (rotation over terrain, which shares this gesture math) is a separate follow-up, and should become easier after this lands.
• A gesture chain that never fully ends (e.g. wheel → drag inside the scroll-zoom timeout) keeps the first sub-gesture's anchor plane — the same lifetime the elevation freeze already has; re-capturing mid-movement would reintroduce plane jumps.

Related issues: #2937 (rotation over terrain), #7989 (DEM loads mid-drag), #4688 (terrain camera-math nondeterminism), #1024 (closed; the wheel-zoom-over-terrain case) — same terrain-gesture family; none of them describes this moving-centroid slip, so no existing issue is closed by this PR.

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) — original work.
• Briefly describe the changes in this PR.
• Link to related issues.
• Include before/after visuals or gifs if this PR includes visual changes — before/after drift table and manual repro above.
• Write tests for all new functionality.
• Document any changes to public APIs — the new screenPointToLocationAtElevation is @internal-documented; the new optional parameter is documented on the existing setLocationAtPoint interface doc.
• Post benchmark scores — no performance claim: the gesture path does one extra plane intersection per frame and one raycast per gesture start (the same raycast recalculateZoomAndCenter already does at gesture end).
• Add an entry to CHANGELOG.md under the ## main section.
• Confirm you have read our AI policy here.

Assisted-By: Claude Fable 5 (claude-fable-5)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.12%. Comparing base (1a66c2d) to head (a2d5216).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8067      +/-   ##
==========================================
+ Coverage   93.09%   93.12%   +0.02%     
==========================================
  Files         298      298              
  Lines       24784    24816      +32     
  Branches     6506     6521      +15     
==========================================
+ Hits        23073    23110      +37     
+ Misses       1711     1706       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[HarelM]

Thanks for the write up! Can you share a few before-after videos maybe?

[HarelM]

There's a need to tone down the comments in this PR, it's too verbose.
I'll do a second sweep after that. Thanks!!

[HarelM]

• Does this PR solve jumpTo/easeTo non deterministic when used with terrain #4688 or [terrain] Camera jumps between dragend and moveend when DEM elevation loads during an active drag #7989?

[StrawberryJam22]

Agreed — trimmed the source and test comments in 29afe96.

[StrawberryJam22]

No — deliberately neither, to keep this reviewable. The PR only changes the reference surface used while a gesture is in progress. #7989 lives in the gesture-end settle (recalculateZoomAndCenter after the elevation freeze lifts), which is untouched — one adjacent improvement is that DEM tiles loading mid-gesture no longer influence the in-gesture solve, since the anchor's elevation is captured once at gesture start, but the dragend→moveend jump itself remains. #4688 is in the jumpTo/easeTo path, also untouched — easeTo still re-anchors on the center-elevation plane (the 'inertia' item under known scope edges). Both should get easier on top of this: the plane-at-elevation plumbing (setLocationAtPoint with elevation, screenPointToLocationAtElevation) is what a settle/ease fix would reuse.

[StrawberryJam22]

Thanks for the write up! Can you share a few before-after videos maybe?

Sure thing! Here are two videos of continuous zoom-in-and-out gestures in the same location in the alps before and after the changes.

trim.D26556A2-3978-410B-9B95-3A005476FC6A.MOV

trim.BF7730E7-7989-4B8A-87D0-F14FF715653C.MOV

[HarelM]

Thanks for the video! Added a few more comments.

[HarelM]

Looks good, THANKS!

[HarelM]

Sorry for the extra work on bundle size... Hopefully this is the last time.

[HarelM]

@StrawberryJam22 is this still solved in latest version?
When I pan a pitched map that has terrain on, the map jumps a bit when I release the grab. Was this solved as part of this PR?

[StrawberryJam22]

@StrawberryJam22 is this still solved in latest version?

When I pan a pitched map that has terrain on, the map jumps a bit when I release the grab. Was this solved as part of this PR?

The in-gesture anchoring from this PR is intact on latest, its gesture tests enforce the "grabbed point stays under the pointer" invariant and pass on current main.

The jump at release is a separate mechanism this PR deliberately didn't touch: while the pointer is down the center elevation is frozen; on release the freeze lifts and recalculateZoomAndCenter re-derives zoom/center/elevation. In a clean synthetic repro that settle is visually invariant (0.0 px even after dragging the center onto ground 1500 m higher, with a smooth inertia decay after it). Where it visibly jumps is when the terrain data itself changed during the drag, DEM tiles that loaded mid-gesture get applied all at once at the freeze lift. That's the #7989 family.

One thing worth checking: whether the jump is new in 6.5/6.6, #8158 moved the picking to a CPU raycast, and the release settle goes through that path. If 6.3/6.4 doesn't jump in the same spot, that points there rather than at the gesture code.

[HarelM]

I still see jumps in terrain in 6.3/6.4 when releasing the mouse, I thought this PR fixed it. Oh well, there's another PR to address this opened now, just wanted to make sure this didn't broke with the changes to ray case etc.
Thanks for looking into this.
Feel free to review it.