New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

expose field of view option #3796

ansis opened this Issue Dec 13, 2016 · 4 comments


None yet
5 participants
Copy link

ansis commented Dec 13, 2016

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


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.


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.


  • 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 })


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.


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


This comment has been minimized.

Copy link

lucaswoj commented Dec 15, 2016

Sounds great! Thanks for the detailed proposal @ansis.


This comment has been minimized.

Copy link

dpieri commented Feb 15, 2017

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.


This comment has been minimized.

Copy link

drhase2 commented Feb 21, 2017

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


This comment has been minimized.

Copy link

lucaswoj commented Feb 21, 2017

@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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment