Adaptive projections
Starting from v2.6, Mapbox GL JS supports multiple map projections. This feature allows you to create more accurate visualizations at every zoom level, and tell a better story with your data.
Map Projections
A map projection is a way to flatten the globe's surface onto a screen. Every projection distorts size, shape and/or distance in its own way, so it's important to pick the right projection for your data.
Nearly all web maps, including Mapbox GL JS up to v2.5, rely only on the Web Mercator projection. It’s simple and efficient, but it heavily distorts the size of geographic shapes on lower scales. For example, Greenland is visually the same size as Africa, even though it’s 14 times smaller.
Mapbox GL JS provides a variety of alternative map projections to address this, offering new options to minimize distortion for a particular use case while keeping other aspects of an interactive map intact. The available options include projections optimized for thematic world maps, and projections for representing specific regions (such as the contiguous U.S. or Alaska).
Use projections in Mapbox GL JS
As of the Mapbox GL JS v2.6 release, developers are able to define the projection to use for displaying their map. The new projections are compatible with existing tile sources and map styles. See this simple example to get started quickly, or explore all available projections in this more advanced example.
You can set the projection through the map constructor’s projection
option, at runtime via the setProjection
method, or by including the projection
in your map style. By default, maps will be in the Mercator projection, as they have been in all previous versions of Mapbox GL JS.
What projections are available?
Developers can select any of the following options when defining a style (each projection is defined in more detail below):
- Albers (
albers
) - Lambert conformal conic (
lambertConformalConic
) - Equal Earth (
equalEarth
) - Natural Earth (
naturalEarth
) - Winkel tripel (
winkelTripel
) - Equirectangular (
equirectangular
) - Mercator (
mercator
, the default)
See the Available projections section below for more information about each.
Define a projection as a Map constructor option
You can define a map projection when creating a Map
instance using shorthand:
const map = new mapboxgl.Map({
container: 'map',
projection: 'naturalEarth'
});
For projections with additional options, use an Object representation:
const map = new mapboxgl.Map({
container: 'map',
projection: {
name: 'albers',
center: [41.33, 123.45],
parallels: [30, 50]
}
});
Set a projection at runtime
You can set or change the map’s projection after Map
creation by using the setProjection
method:
// Use shorthand with default parameters
map.setProjection('equalEarth');
// Or override the projection-specific options
map.setProjection({
name: 'albers',
center: [41.33, 123.45],
parallels: [30, 50]
});
Define a projection in a style
You can define a projection in a map style:
const map = new mapboxgl.Map({
style: {
version: 8,
name: 'My Projected Style',
sources: {
// ...
},
layers: [
// ...
],
projection: {
name: 'equalEarth'
}
}
});
Important notes about using projections in a style:
- A projection defined in a style must be an object. The string shorthand is not valid in a style specification.
- If you define one projection in a style, and set a different one at runtime (either through the map’s constructor or
setProjection
), then the runtime projection will be used. - Calling
map.setProjection(null)
will revert from any runtime projection to the one defined in the style.
Define a projection’s center and parallels
Conic projections like albers
and lambertConformalConic
have special properties, parallels
and center
:
parallels: [latitude1, latitude2]
: Distortion of area and shape is minimized by the projection in the region between these two lines of latitude. The parallels can be the same latitude.center: [longitude, latitude]
: The location used to match scale and bearing with mercator. The size and bearing at this location will always be the same as it would be in mercator at the same zoom. At low zoom levels, other locations may have distorted size and bearing.
For any projection besides Albers and Lambert Conic Conformal, the center
and parallels
properties will be ignored.
This example shows how to configure the Albers projection to center on the U.S. state of Alaska. These properties can also be defined in the setProjection
method or in a style.
const map = new mapboxgl.Map({
container: 'map',
projection: {
name: 'albers',
center: [-154, 50],
parallels: [55, 65]
}
});
Get current map projection
Developers can get the current map’s projection using map.getProjection()
.
Behavior and limitations
Map “unskewing” on zoom
Alternate projections in Mapbox GL JS have a novel adaptive design that adjusts the projection as you zoom in to minimize distortion on higher zoom levels, gradually transitioning from the defined projection to Web Mercator (which is optimal on higher zooms). This behavior is a core part of the implementation and can’t be configured or turned off.
Querying
Map querying via map.queryRenderedFeatures()
works in all projections.
3D
In Mapbox GL JS v2.6, 3D terrain, fog and Free Camera API cannot be used simultaneously with non-Mercator projections. We plan to resolve this in a future release.
Custom style layers
In Mapbox GL JS v2.6, CustomLayerInterface
cannot be used simultaneously with non-Mercator projections. We plan to resolve this in a future release.
Zoom and bearing
For any camera zoom level and location, maps in different projections will be rendered at the same scale they would be rendered in Mercator.
The bearing in Mercator maps corresponds directly to the rotation of the map (north is up). In other projections, the concept of bearing is more complicated since the direction of north can be different at different points on the map:
- At low zoom levels, the bearing corresponds to the direction of north at the center of the projection.
- At high zoom levels, the bearing corresponds to the direction of north at the center of the screen.
- At intermediate zoom levels, bearing transitions between the two meanings.
Projection background
The empty area around the world in alternate projections is rendered as transparent. There are no style properties to control its appearance yet — the only way to change it is with CSS background property on the map container.
Constraining interaction
Maximum bounds constraints work differently with alternate projections. Map panning and zooming is constrained in a way so that the center of the map doesn’t go beyond the specified geographic bounds, rather than the whole visible area. This is potentially subject to change in future versions.
Available projections
Albers
The Albers projection (defined as albers
in the Mapbox GL JS API) is a conic, equal-area projection. As a conic projection, it can be configured with the center
and parallels
properties to define a region in which distortion is minimized.
By default, the Albers projection is centered on the mainland United States at [-96, 37.5]
with the standard parallels [29.5, 45.5]
. This “Albers USA” projection is commonly used for showing geographic data in which comparing state-level sizes is important, for example in U.S. elections. Notable users of the projection include U.S. Geographical Survey, U.S. Census Bureau, and National Atlas of the U.S.
By configuring center
and parallels
, a developer can get a similar view for any region on Earth. See the above section on using the center
and parallels
properties for an example of configuring conic projections.
Composite Albers projection (e.g. where Alaska and Hawaii are alongside the mainland U.S.) is not yet supported in Mapbox GL JS.
Equal Earth
The Equal Earth projection (defined as equalEarth
in the Mapbox GL JS API) is a cylindrical, equal-area projection. This projection is a global projection which is appropriate for thematic mapping, especially when size comparisons or relative distance from the equator are needed for interpreting the geographic data.
A notable use of Equal Earth projection is thematic maps on global temperature anomalies by NASA.
Equirectangular
The Equirectangular (Plate Carrée) projection (defined as equirectangular
in the Mapbox GL JS API) is a cylindrical, compromise projection in which positions on the map directly correspond to their longitude and latitude values.
This projection is the standard for global raster datasets, such as Celestia, NASA World Wind, and Natural Earth, and is useful when you need to display these datasets without any distortion.
Lambert conformal conic
The Lambert Conformal Conic projection (defined as lambertConformalConic
in the Mapbox GL JS API) is a conic, conformal projection used for aeronautical charts and many regional mapping systems. It can be configured with the center
and parallels
properties to define a region in which distortion is minimized.
By default, this projection is centered on [0, 30]
with the standard parallels [30, 30]
. This projection preserves shapes and is appropriate for regional maps which need accurate shapes and angles (note that as with many other conformal projections, size distortion will increase towards the poles).
This projection is popular for aeronautical charts because straight lines on it approximate great circle routes between endpoints. Notable users include the European Environmental Agency, France, and also U.S. National Geodetic Survey for several U.S. states such as Tennessee.
Natural Earth
The Natural Earth projection (defined as naturalEarth
in the Mapbox GL JS API) is a cylindrical, compromise projection. This projection is appropriate for global, thematic mapping.
The distinguishing characteristics of Natural Earth are that parallels on this projection are straight lines, and a pleasant rounded aesthetic.
Winkel tripel
The Winkel tripel projection (defined as winkelTripel
in the Mapbox GL JS API) is a “modified azimuthal” projection. The “tripel” part of the name comes from its goal of minimizing distortion in three aspects: area, direction and distance.
Since it doesn’t perfectly preserve any one aspect, Winkel tripel is a compromise projection, but it is commonly regarded as one of the least distorted compromise projections. The National Geographic Society and many other educational institutions use Winkel tripel for global, thematic mapping.