Projections
A map projection is a way of transforming the three-dimensional planet to a two-dimensional plane like a page or screen. Every projection has strengths and weaknesses, so the right projection depends on your use case.
For most maps, we recommend using globe to accurately represent locations on the Earth. The most notable limitation of globe is that only half the earth is visible onscreen at once. If you're building a static map or data visualization, an alternative projection might be a good choice.
The Maps SDK for Android supports the following projections:
- Globe (
globe): A 3D representation of the Earth. - Mercator (
mercator): Shapes and angles are accurate, but sizes are distorted. - Albers (
albers): Relative area is accurate, but shapes are distorted. Available starting with v11.32.0.
Learn more about map projections, including the projections available in Mapbox GL JS.
Default projection
The map style sets the projection. If you don't overwrite it at runtime:
- With the Mapbox Standard style, or a style that imports Standard and doesn't set its own projection, the map displays Globe.
- With any other style that doesn't set a projection, the map displays Mercator.
Set a projection in a style
You can set the projection by editing the map style in Mapbox Studio, or in a style JSON that you load at runtime:
{
"version": 8,
"projection": { "name": "albers" },
"imports": [{ "id": "basemap", "url": "mapbox://styles/mapbox/standard" }],
"sources": {},
"layers": []
}
Load the style JSON like any other style:
mapView.mapboxMap.loadStyle(albersStyleJson)
MapboxMap(
style = { MapStyle(style = albersStyleJson) }
)
Important notes about using projections in a style:
- A projection defined in a style JSON file must be a JSON object, for example
"projection": { "name": "albers" }. The Maps SDK ignores a projection written as a string, such as"projection": "albers". - If you define one projection in a style, and set a different one at runtime, then the runtime projection will be used.
Set a projection at runtime
To change the projection of the current style, use setProjection with a ProjectionName:
mapView.mapboxMap.getStyle { style ->
style.setProjection(projection(ProjectionName.GLOBE))
}
ProjectionName includes GLOBE and MERCATOR.
Albers is not part of the Maps SDK API yet: there is no ProjectionName constant for it, and setting or reading it at runtime is not officially supported. To use Albers, set it in your style JSON.
Globe
The Globe projection (defined as globe in the Maps SDK) is a three-dimensional representation of the earth. Globe increases the sense of depth of the map and is a correct representation of the surface of the earth as viewed from space. Using this projection limits the display of the earth to one hemisphere at a time. This can be addressed in some cases by rotating the globe with camera animation.
Globe is the default projection in Mapbox Standard. As you zoom in, the map transitions from the globe to the Mercator projection.
Rotate the globe with camera animation.
Mercator
The Web Mercator projection (defined as mercator in the Maps SDK) is a cylindrical, conformal projection and the default projection in the Maps SDK if projection is not specified in a style. Web Mercator is classified as EPSG:3857 and is a variant of the classic Mercator projection used for marine navigation.
Mercator accurately displays shapes and angles, which makes it useful for navigation. At the world scale, it exaggerates the size of geographic shapes near the poles. For example, Greenland appears the same size as Africa, even though it's 14 times smaller.
Mercator is suitable for maps remaining at high zoom or cases where a map needs to cover the 180th meridian.
Albers
The Albers projection (defined as albers in the Maps SDK) is a conic, equal-area projection. This projection provides accurate relative sizes, but shapes are increasingly distorted at further distances.
The Albers projection is centered on the mainland United States at [-96, 37.5] with the standard parallels [29.5, 45.5]. The Maps SDK doesn't support the center and parallels options yet. 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.
Albers is an adaptive projection: it adjusts the projection as you zoom in to reduce distortion at all zoom levels by gradually transitioning from Albers to Web Mercator (which is optimal on higher zooms).
Composite Albers projection (for example where Alaska and Hawaii are alongside the mainland U.S.) is not yet supported in the Maps SDK.
Limitations of Albers
Albers doesn't support all features that Globe and Mercator support. We plan to add support for these features in a future release.
3D and background styling
3D terrain and 3D landmarks can only be used with Globe and Mercator projections.
Atmospheric styling is also supported only in Globe and Mercator projections. In other projections, the empty area around the world is rendered black.