Detect whether coordinates are behind the globe when using the globe view

[ianlet]

Motivation

Similar to a Marker or a Popup, in some cases we need to know whether coordinates (lat long) are behind the globe to apply some visual effects (when using globe view). Currently, it doesn't seem like there are a public API to do so.

Additional context

We are working on a wrapper for using mapbox-gl-js in Qwik applications. Though usable, the Popup element provided by mapbox-gl-js doesn't integrate well with how Qwik works and makes it quite complicated to have richer popups managed by Qwik. We're currently working on a Qwik native implementation of those popups to offer a better DX, aligned with Qwik's approach.

Our current implementation works well, but as we can't detect easily whether a point is behind the globe or not, we're having trouble hiding the popup when it is moved behind the globe.

Design

Option 1: expose 'isLngLatBehindGlobe' and 'showingGlobe' publicly

As util functions to detect whether a point is behind a globe already exists, we could simply make them part of the public API of mapbox-gl-js.

Usage example:

const transform = map.transform;
const isBehind = map.showingGlobe() && isLngLatBehindGlobe(transform, [12.34567, 12.34567]);

Pros:

• Very few changes to the existing codebase

Cons:

• Lower level API not initially meant to be exposed publicly
• Lower level API forcing devs to access the internal transform object of the map map.transform

Option 2: introduce a new function on the Map

Usage example:

const isBehind = map.isBehindGlobe(coords);

Pros:

• Avoid exposing internal functions and properties

Cons:

• Add a new API that doesn't always make sense (if not globe view)

Option 3: add a new behavior to the Map.project function

Per se, if the coordinates we're trying to project were behind the globe, it could make sense to return null or undefined to indicated that the coordinates are occluded and not actually visible on the screen (so no screen point).

To reduce the impact of breaking changes, an extra option could be used to activate the new behavior (e.g. globeOcclusion: true or something similar).

Usage example:

const point = map.project(coordinates, { globeOcclusion: true })
if (!point) {
  // do something
}

Pros:

• Avoid introducing extra APIs
• Make it easier for developer to start using this new behavior with much changes on their hand

Cons:

• Reuse a function that maybe wasn't meant to be used that way
• Introduce a signature change that will force existing devs to adapt their code