mapbox / mapbox/mapbox-gl-js

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

Open
#13,403 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

auto-triaged feature :green_apple:
Dominant language
TypeScript
Stars
12.4k
Forks
2.4k
PR merge metrics
No merged PRs in 30d

Description

## 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](https://qwik.dev/) 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:
```ts
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:
```ts
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:
```ts
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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing isLngLatBehindGlobe and showingGlobe utilities mentioned in the issue, along with the Map.project API. The work is complete when a public approach for detecting globe occlusion is selected, implemented, and verified for coordinates behind the globe.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.