Projections and zoom

Two modes

mode	What you get
"globe" (default)	Orthographic sphere. Drag to spin, momentum carries
"map"	Flat map. Drag to pan, wraps past the antimeridian

Three flat projections

Loading globe…

Projection	Character
equirectangular (default)	Longitude and latitude map linearly. Simple, slightly stretched at the poles
mercator	Familiar web-map look. Preserves angles, exaggerates polar area badly
naturalEarth	A compromise projection. Rounded, pleasant, good for print-style graphics

Each canvas ratio suits one projection: see Sizing the canvas.

Latitude window

latRange is [north, south] and defaults to [83, -56], which trims the polar caps where almost nobody lives.

latRange: [90, -90];   // full height, includes Antarctica

:::caution Markers outside the window With the default range, a marker south of −56° or north of 83° projects outside the drawn map. project() correctly reports visible: false, but nothing else warns you. Widen latRange if you plot research stations. :::

Zoom

globe.setZoom(3);
globe.zoomBy(1.4);
globe.fitTo([68, 6, 98, 36]);      // [west, south, east, north]
globe.fitToMarkers();

Option	Default	Meaning
zoom	1	Starting zoom
minZoom	1	Lower bound
maxZoom	8	Upper bound
zoomable	true	Wheel and pinch

Wheel zoom in map mode is anchored to the pointer: the coordinate under the cursor stays put. On the globe, zoom is about the centre, because rotation already does the panning.

Loading globe…

Crossing the antimeridian

Once the world is wider than the viewport, horizontal panning is unbounded and the map wraps. Fiji at 178°E and Samoa at 172°W render side by side, as they should.

Internally, longitudes are wrapped around the visible centre, which puts the seam half a world away: off screen whenever you are zoomed in. At zoom 1 the seam sits at ±180°, the natural map edge.

fitToMarkers() understands this too: it picks the shortest longitude arc covering your points, so a set straddling the dateline frames tightly instead of zooming out to the whole world.

Flying

globe.flyTo(139.69, 35.68);                        // eased, damped spring
globe.flyTo(139.69, 35.68, { instant: true });     // jump
globe.flyTo(139.69, 35.68, { zoom: 4 });           // and change zoom

flyTo jumps rather than eases when the visitor prefers reduced motion.

Coordinates in and out

globe.project(lon, lat);    // → { x, y, visible } or null if behind the globe
globe.unproject(x, y);      // → [lon, lat] or null if the pointer missed
globe.getCenter();          // → { lon, lat }

Both speak CSS pixels. project is exact to floating point: the pixel position matches the closed-form projection, so a marker sits precisely where you put it.

:::info The coastline is the approximation, not your marker Bundled geometry is Natural Earth 1:110m, decimated to about 5 km. A harbourside marker can look slightly offshore because the drawn shoreline moved, not the dot. Natural Earth 1:110m also omits microstates such as Singapore and Malta. Pass higher-detail GeoJSON via world if that matters. :::