API to access the camera parameters when using terrain

[Pessimistress]

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:

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

mapbox-gl-js/src/ui/handler_manager.js

Lines 485 to 489 in d7e1beb

	if (eventEnded("drag") && !hasChange(combinedResult)) {
	const preZoom = tr.zoom;
	tr.cameraElevationReference = "sea";
	tr.recenterOnTerrain();
	tr.cameraElevationReference = "ground";

IMO this behavior is at odds with the documented definition for zoom level, 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:

visgl/react-map-gl#1894
visgl/react-map-gl#1855
visgl/react-map-gl#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.

[SnailBones]

Thank you for opening this issue @Pessimistress!

In the case of consistently recreating transform, would the Free Camera API be of any help?

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:

I agree that this is a troubling issue. I think that much of the cause for this stems from our attempts to avoid breaking existing mapswhile adding new 3d features. If we were building from scratch, we might have considered preventing clipping by capping zoom at high elevation areas. Instead, in order to allow for a smooth update from existing 2d maps, we changed the behavior of zoom and added complexity under the hood. (We've more recently done the same for globe.)

I'm not sure what we can do about this without introducing breaking changes, but simplifying the transform API to prioritize 3d use cases would be a great thing to include in v3.0.0.

[Pessimistress]

Thank you @SnailBones for the pointer.

I can successfully calculate the "real zoom" from camera position, center and pitch:

https://github.com/visgl/deck.gl/pull/7114/files#diff-c804cf7ecd745e0fa2dfef7ea3a3a1871e74f10d35025ada4274ec12b4510384R170-R197