2d picking fixes #13098

mzschwartz5 · 2025-12-15T22:04:13Z

Description

There are various issues with terrain picking in 2D/CV scene modes. Some of these have existed for a very long time, and some are recent regressions from #9961.

All of them manifest as undefined pick results when performing globe.pick. This PR addresses nearly all of the issues that manifest this way. They're all documented here, but tl;dr-

2D mode has an "Infinite scroll" option. To support this, the terrain gets rendered multiple times in a given frame. Picking relies on testing ALL tiles rendered this frame, but QuadtreePrimitive only tracks the tiles rendered in a given render call.
Another, related issue- in infinite scroll mode, the map "wraps", and the camera's world position wraps with it, but the ray generated by camera.pickRay() does not account for that wrap.
Antimeridian issues: it seems like the vertex data near the antimeridian sometimes suggests is should be rendered on the other end of the map - some sort of disagreement between the position data and where its rendered. Easily fixed with some modulo math.
TerrainPicker regression 1: globe.getHeight() picks in 3D mode, even when the scene mode is 2D/CV. This causes the TerrainPicker to cache and use a stale transform for the incorrect scene mode.
TerrainPicker regression 2: vertex positions were passed to workers as 32 bit floats. This seems to have caused some precision issues in 2D mode (maybe in 3D mode too?), so I switched to Float64Array.

Unfixed issues:

Still some undefined picks near the poles in 2D. Couldn't figure this one out in a reasonable time period, but this is a classic issue and one that doesn't historically have a big impact.
The unit tests for TerrainPicker 2D mode are not good. I don't think the mock terrain provider can even provide data in the 2D coordinate system, but it would be a lot of work to learn how to enhance it.

Issue number and link

Primary issue

Also came up here

Testing plan

I've been using this sandcastle to test: it picks as you move the mouse, and draws a point wherever there results are undefined.

After these changes, it should mostly draw nothing (except near the poles)!

Author checklist

I have submitted a Contributor License Agreement
I have added my name to CONTRIBUTORS.md
I have updated CHANGES.md with a short summary of my change
I have added or updated unit tests to ensure consistent code coverage
I have updated the inline documentation, and included code examples where relevant
I have performed a self-review of my code

github-actions · 2025-12-15T22:04:35Z

Thank you for the pull request, @mzschwartz5!

✅ We can confirm we have a CLA on file for you.

jjhembd

Thanks @mzschwartz5, this is a huge improvement. Thanks for the testing Sandcastle, and the in-depth discussion in #13083.

I only have a comment about naming, and a question about loop performance.

packages/engine/Source/Scene/Globe.js

jjhembd · 2026-01-23T20:25:29Z

packages/engine/Source/Scene/QuadtreePrimitive.js

-  for (let i = 0, len = tilesRendered.length; i < len; ++i) {
-    tileFunction(tilesRendered[i]);
+  const tilesRendered = this._tilesRenderedThisFrame;
+  for (const tile of tilesRendered) {


As above, how many tiles are in this list? If it's a "small" number, then for..of is probably ok.

Another instance where I don't think it's a hot path for performance, but it's an easy change to make, so might as well change it.

packages/engine/Source/Workers/incrementallyBuildTerrainPicker.js

jjhembd · 2026-01-23T22:14:48Z

packages/engine/Specs/Core/TerrainMeshSpec.js

+  GeographicProjection,
+} from "../../index.js";
+
+describe("Core/TerrainMeshSpec", function () {


Always good to see more specs!

ggetz

Overall the code is looking great. Thanks @mzschwartz5 for tracking down all the fixes here! I just have one question regarding precision. Otherwise this all looks good to me.

ggetz · 2026-01-29T22:32:49Z

packages/engine/Source/Core/TerrainPicker.js


+  // Right near the antimeridian, in 2D/CV modes, the vertex positions may correspond to the other side of the world from the ray origin.
+  // Compare to the ray origin and adjust accordingly.
+  const worldWidth = CesiumMath.TWO_PI * projection.ellipsoid.maximumRadius;


This is going to use a spherical approximation and not the true ellipsoid circumference. Is that adequate for the use case here, or should the true circumference be used?

Good point.... I need to think about this. It does seem to "work" in all my testing but is it correct?

Perhaps the reason it's valid (at least in the testing I've done) is because our two common projections (mercator and web geographic) are cylindrical projection, where this math is exact.

It might not be valid for other projections.

Well, conveniently those are the only two 2D projections we support. 😄 So maybe good enough, and just worth a comment explaining why.

If in doubt, using a root mean square approximation should be accurate enough for most real world applications since the radii are generally close in value. But that could be overkill given the above.

Yeah the issue is that MapProjection is an interface technically, so people could in theory extend it with their own projection implementations that may not be cylindrical.

In practice this hasn't happened in 15+ years so... (there are plenty of places that assume our two projections are the ONLY projections, for better or for worse).

Will leave a comment though.

ggetz · 2026-01-29T22:38:15Z

packages/engine/Specs/Core/TerrainMeshSpec.js

+        [],
+      );
+
+      // Mock out the dependency on TerrainPicker


Just curious—What's the motivation on mocking this? Is the TerrainPicker difficult to construct or is there another source of friction?

Generally speaking, it'd preferable to call through this function call, even if you are spying on it. (Though this doesn't need to prevent this PR from being merged—Just adding the unit test is already an improvement.)

I think my thought process was that these tests aren't supposed to be testing the terrain picker ray intersection logic, they're testing TerrainMesh.

Otherwise it's more of an integration test than a unit test. For what it's worth, it is also difficult to construct TerrainPicker - fully constructing things would require having real mesh data to give it. Once you start down that rabbit hole, where do you stop?

ggetz · 2026-01-29T22:53:39Z

packages/engine/Specs/Core/TerrainMeshSpec.js

+      );
+
+      mesh.updateExaggeration(2.0, 1.0);
+      const expected2DTransform = mesh.getTransform(


While calculating a value rather than hardcoding it can make tests more resilient, in this case the function computing the expected value is part of the system under test. Depending on it may lead to cases where there's a bug somewhere in TerrainMesh but this unit test still passes. I'd opt to hard code it, or compute it outside of TerrainMesh operations.

(Again, this doesn't need to prevent this PR from being merged—Just adding the unit test is already an improvement.)

mzschwartz5 added 6 commits December 15, 2025 17:03

Accounts for wrap around in 2D pick ray

4d69440

Tracks all tiles rendered in a frame for picking

7d725f3

Fixes terrain picking near antimeridian in 2D/CV modes

f2d476b

Fixes stale transforms in 2D mode

ba86e86

Increases the precision of vert positions in terrain picker

e6d62a0

Clamps aabb bounds in terrain picker

6e20e37

This was referenced Dec 15, 2025

Camera jumps when globe translucency is enabled since 1.136 #13092

Open

Undefined terrain picks in 2D/CV mode. #13083

Open

mzschwartz5 added 4 commits December 22, 2025 11:42

Small adjustment to terrain mesh

745fe8b

Adds unit tests for TerrainMesh

3550cbf

Adds unit test for camera wrap edge case

467605c

QuadtreePrimitive small tweak and unit tests

8b877ba

mzschwartz5 force-pushed the 2d-picking-fixes branch from 7216a00 to 8b877ba Compare December 30, 2025 16:49

Changes.md

983ea47

mzschwartz5 marked this pull request as ready for review December 30, 2025 17:25

ggetz assigned mzschwartz5 Jan 9, 2026

mzschwartz5 requested a review from jjhembd January 9, 2026 21:29

jjhembd reviewed Jan 23, 2026

View reviewed changes

mzschwartz5 added 2 commits January 29, 2026 17:09

Revisions to 2d-picking based on PR review

0caeca8

Merge branch 'main' into 2d-picking-fixes

77b5a2f

mzschwartz5 added the priority - next release label Jan 29, 2026

mzschwartz5 requested a review from jjhembd January 29, 2026 22:23

ggetz reviewed Jan 29, 2026

View reviewed changes

2d picking fixes #13098

Are you sure you want to change the base?

2d picking fixes #13098

Conversation

mzschwartz5 commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue number and link

Testing plan

Author checklist

Uh oh!

github-actions bot commented Dec 15, 2025

Uh oh!

jjhembd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ggetz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ggetz Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mzschwartz5 commented Dec 15, 2025 •

edited

Loading

mzschwartz5 Jan 29, 2026 •

edited

Loading

ggetz Jan 29, 2026 •

edited

Loading