expose field of view option

[ansis]

This is a big wall of text but the actual implementation should be short.

Motivation

You want to change how perspective-y the map looks, either to match the fov in some other piece of software or to just change the appearance of a 3D map to make you look closer or more distant.

Design Alternatives

Field of view

Expose the fieldOfView (fov) transform property in all the places bearing is exposed.

Field of view is usually specified as an angle in either the x or y direction. Since maps can exist at variable aspect ratio and resolutions, the fov needs to be scaled at least in one direction. For example, if you stretch a map horizontally does the horizontal fov change? or does the vertical fov change? or do they both change? Here is an overview of some of the options. The main options are:

• fixed vertical field of view
• fixed horizontal field of view
• scale both horizontal and vertical fov (think about having a fixed fov in both directions at a fixed resolution and then cropping that image)

Name possibilities: fov, fieldOfView, verticalFieldOfView, fovY, fieldOfViewY

focal_length / dolly zoom / old altitude

Field of view could alternatively be specified as the distance from the camera to the center. This is basically the dolly zoom effect. The old internal altitude property implemented this. Tangram implements this and calls it focal_length.

do nothing

It's an option since this is mostly a nice-to-have but the cost of supporting it isn't high.

Design

We should expose fieldOfView in all the places we expose bearing.

Field of view is better than focal_length/altitude/dolly zoom because:

• fov is way more common in 3d graphics
• the units for focal length are harder define. Since the real-world focal length changes when you zoom the units need to be based on some distance that doesn't change, like viewport height. But it's awkward to say the focal length is 1.25 viewport heights.

I think either fov or fieldOfView are good names. The former is standard in graphics but the latter is less cryptic. I lean towards fieldOfView.

We should have a fixed vertical fov. This is the most common approach in games and is better suited for wider aspect ratios. This is what is currently implemented.

Mock-Up

• var map = new Map({ fieldOfView: 35 })
• var fov = map.getFieldOfView(fieldOfView)
• map.setFieldOfView(fov)
  and using CameraOptions:
• map.jumpTo({ fieldOfView: fov })
• map.easeTo({ fieldOfView: fov })
• map.flyTo({ fieldOfView: fov })

Concepts

What terminology will work best for the new concepts introduced by this design?

field of view

What existing precedents support the new concepts?

Video games, 3d graphics libraries.

Implementation

The core of this is already implemented. The Transform#fov property (#3790) needs to be exposed through an external api.

[lucaswoj]

Sounds great! Thanks for the detailed proposal @ansis.

[dpieri]

This would be very useful for us. I just had an exchange with support about this same question today.

Our use case is we are integrating Mapbox with our own 3D map. To do a smooth crossfade between 2D and 3D we need information about the real-world location of the Mapbox camera. Today we're trying to figure out how to estimate this given the information available through the public API.

[drhase2]

We are desperately waiting for this to exchange current rendering with mapbox

[lucaswoj]

@drhase2 It sounds like this feature implementation will be as easy as wiring up a private property to some external getters / setters. Any interest in putting together a PR?

(Also, FWIW, you may prototype this feature using the existing private API: map.transform.fov = 4)