Design Proposal: Add Center Altitude

[NathanMOlson]

Design Proposal: Add Center Altitude

Motivation

I would like to be able to pitch the camera above 90 degrees.
maplibre/maplibre-gl-js#4717
NathanMOlson/maplibre-gl-js#1

To keep the camera above the terrain, the center point elevation must be above terrain when pitch is > 90. 2D center point is no longer sufficient to place the camera.

Proposed Change

I would like to add a field centerAltitude to the root style spec object. centerAltitude sets the center point elevation in meters above sea level, and joins its friend center.

API Modifications

Root style spec gets a new centerAltitude field. jumpTo(), easeTo(), and flyTo() get elevation added to their options.

Migration Plan and Compatibility

This is a pure extension. To achieve existing functionality, just leave centerAltitude undefined (default 0).

Rejected Alternatives

I considered adding centerAltitude to the API but not to the style spec. Rejected because:

1. elevation is needed in style spec for render tests.
2. Similar field center already exists in style spec

[HarelM]

Render tests can work with methods defined in the render harness and in the map API (check out wait and other "special" operations).
It is not clear what elevation stands for as currently zoom basically defines the elevation.
It's not perfect, but adding a parameter that may confuse the user is not ideal...

[NathanMOlson]

Understood about the render tests.

The elevation proposed here corresponds to map.transform.elevation, which is the elevation of the center point (map.transform.center).

For pitch angles >= 90 degrees, if the center point is at the same elevation as the map, the camera will be below the map. To allow the camera to be above the map, it must look at a center point which hovers above the map (map.transform.elevation must be greater than the elevation of the map, which is zero in the absence of terrain).

[HarelM]

Is it possible to add a third number to center?

[wipfli]

Is center the location of the camera or is it the location of where the camera looks at?

[wipfli]

I know center and zoom are already part of the style spec so we will not remove them, but in my opinion they should never have been added. I think the style sheet should encode how the map looks like, and the MapLibe GL JS / Native API should take care of what you do with the map, i.e., where to look at, zoom level, field of view etc...

[HarelM]

Center is where the camera is looking at.
I respectfully disagree about the fact that center shouldn't be part of the spec.
Consider the case where you want to present a map of a location (for example a web page with a business showing where it resides).
Setting zoom, center, pitch, bearing allows a designer to indicate exactly how the map should look without needing to change a single line of code.

[wipfli]

OK, so

• center is the location of the point where the camera is looking at
• elevation is the elevation of the point the camera is looking at

More question are:

• is the elevation referenced to sea level or to the height of the 3d terrain under the center point?
• What is the relation between center, elevation, and zoom?

I have a feeling that you could already emulate what elevation should do by moving the center point and adjusting the zoom level...

[wipfli]

And would it not make more sense to introduce properties for the camera location and view direction?

[HarelM]

I've asked the same questions basically. Some have been answered here:
maplibre/maplibre-gl-js#4851
For pitch > 90 elevation is a must.
Relevant PR about pitch support is here:
#860
Let me know if this answers your questions.

[wipfli]

Ok thanks for the links. I think I understand the math part now. But isn't this all very backward? I mean if I remember correctly the use case that you would like to support @NathanMOlson is first-person-view of a pilot flying through a valley. I think it would be much more intuitive as a user interface to provide camera location and view direction. The plain has a gps position and a heading, that's what you should give to maplibre...

[HarelM]

Since this is not the main use case for maplibre, we agreed these APIs can be added as a plugin code (external code) as these are basically converters from camera location to camera target.