Globe Projection

MapMetrics GL can render the same vector tiles either as a flat Mercator map or as a 3D globe. The globe draws the exact same polygons, lines and symbols — no separate globe-only data is needed — and smoothly transitions back to Mercator as you zoom in.

Enabling globe

Set the projection on the map:

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
  center: [0, 20],
  zoom: 1.5,
});

map.setProjection({ type: 'globe' });

Read the current projection with:

map.getProjection(); // { type: 'globe' } or { type: 'mercator' }

Switch back with map.setProjection({ type: 'mercator' }).

Adding the toggle control

GlobeControl gives users a button that flips between mercator and globe:

map.addControl(new mapmetricsgl.GlobeControl());

The control watches the map's styledata event and updates its own icon (mapmetricsgl-ctrl-globe / mapmetricsgl-ctrl-globe-enabled) to reflect whichever projection is currently active — including changes made programmatically via setProjection, not just clicks on the button itself.

Behavior and limitations

• Automatic Mercator fallback at high zoom. Globe projection is only used up to roughly zoom level 12; above that the map transitions smoothly (and imperceptibly) to Mercator. This is a precision limitation, not a toggle you control.
• Terrain, pitch, and camera animations (flyTo, easeTo) all work under globe — panning and zooming keep the cursor's location fixed on the sphere, the same way Mercator zooming keeps it fixed on the plane.
• No center constraining. Globe transform does not currently support constraining the map's center the way Mercator does.
• Poles. The camera can't move directly across a pole to the opposite hemisphere; MapMetrics GL rotates around instead of cutting through, so zooming into a point "behind" a pole uses an approximation rather than an exact zoom path.
• At very low zooms near the edge of the visible globe, cursor-anchored zooming is faded out in favor of an approximation, to avoid rapid, unpleasant panning.