Globe and Atmosphere
Mapbox GL JS supports displaying the map as a 3D globe, starting from v2.9.
Use Globe in Mapbox GL JS
Most of the latest Mapbox styles use globe by default. Using these styles or a style created them in Studio will enable globe on your map.
Navigation styles default to the Mercator projection.
You can change any other map to globe by setting the projection property.
const map = new mapboxgl.Map({
container: 'map',
projection: 'globe'
});
Globe is compatible with all tile sources and map styles (with a few caveats). See examples for custom atmosphere styling and rotating globe.
Atmosphere styling
The latest Mapbox styles include atmosphere by default. You can customize stars and atmosphere with the fog property. To set a custom atmosphere in GL JS:
map.on('style.load', () => {
map.setFog({
color: 'rgb(186, 210, 235)', // Lower atmosphere
'high-color': 'rgb(36, 92, 223)', // Upper atmosphere
'horizon-blend': 0.02, // Atmosphere thickness (default 0.2 at low zooms)
'space-color': 'rgb(11, 11, 25)', // Background color
'star-intensity': 0.6 // Background star brightness (default 0.35 at low zoooms )
});
});
These properties support zoom expressions, for instance to fade from starry space at low zooms to a blue sky at high zooms.
Atmosphere can also be customized per-style in Mapbox Studio.
Behavior
For any camera zoom level and location, maps in globe will be rendered at roughly the same size. At low zoom levels, the same zoom level will result in features near the poles appearing larger in Mercator, while near the equator features will appear larger in globe. This is a compromise ensuring relatively consistent map appearance given the size distortion inherent in Mercator.
Limitations of Globe
Globe does not yet support CustomLayerInterface.
Globe does not support the deprecated sky layer. We recommend styling the sky and atmosphere with the fog property as described above.
Panning is limited by the poles. In the case where it's important to position the map center at pole, consider a polar projection.