mapbox / mapbox/mapbox-gl-js

API to access the camera parameters when using terrain

Open
#12,040 2 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

3d :triangular_ruler: feature :green_apple: needs discussion :speech_balloon:
Dominant language
TypeScript
Stars
12.4k
Forks
2.4k
PR merge metrics
No merged PRs in 30d

Description

### Motivation

To use deck.gl (or other visualization overlays / custom layers) with Mapbox's terrain feature, we need to be able to construct viewport matrices that match those of the base map. Currently deck.gl accesses transform properties via `Map` class methods `getCenter`, `getZoom`, `getPitch`, `getBearing` and `getPadding`. These are not sufficient to match the camera if terrain is used.

### Design

Unsure, see discussion below

### Implementation

In my experiment, I have attempted to match the Mapbox view matrix with the following:

```js
function getCenterElevation(map) {
return map.queryTerrainElevation(map.getCenter(), {exagerated: false});
}
```

However it does not seem to match what `map.transform` uses to target the camera. I observe that `getZoom()` returns different values before and after dragging ends (i.e. before and after the pointerup event, without the camera moving), possibly due to the manipulation here and alike https://github.com/mapbox/mapbox-gl-js/blob/d7e1bebffc6f4f4a2c6e06ab713b4aad96c0d18a/src/ui/handler_manager.js#L485-L489

IMO this behavior is at odds with the documented definition for [zoom level](https://docs.mapbox.com/help/glossary/camera/#zoom), which should not be dependent on some internal interaction state.

A higher-level issue I have experienced as a maintainer of Mapbox-dependent libraries, is that the more recent features, including terrain and projection, are very much hostile to library developers. I am seeing the increasing behavior of `setCenter`, `setZoom` etc. become dependent on map states that are manipulated in the input handlers and the render call. The matrices of `transform` cannot be predictably reproduced from public getters/setters. As a result, we are not able to take a snapshot of a transform instance using public API, and replay that snapshot later. Here are some examples of our desperate struggle trying to chase down private transform mutations:

https://github.com/visgl/react-map-gl/pull/1894
https://github.com/visgl/react-map-gl/pull/1855
https://github.com/visgl/react-map-gl/pull/1831

I am personally very excited about these new features coming to Mapbox, and the users of my libraries expect to be able to use them as they become available. The only way I can make Mapbox integrations forward-compatible, by eliminating all hacks, is if `transform` can be consistently reproduced via public APIs.

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 reviewing the public Map methods getCenter, getZoom, getPitch, getBearing, getPadding, and queryTerrainElevation, then compare them with the internal transform behavior referenced in src/ui/handler_manager.js. Define how terrain camera parameters or matrices should be exposed consistently through the public API, including a reproducible transform snapshot.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
api, 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.