three-slippy-map-globe

ThreeJS Slippy Map Tiled Globe

A ThreeJS mesh to render tiled raster images onto a sphere using slippy map mechanics, with automatic detection of zoom level and tiles in view based on camera aim and proximity.

Check out the example (source).

Quick start

import SlippyMapGlobe from 'three-slippy-map-globe';

or using a script tag

<script src="//unpkg.com/three-slippy-map-globe"></script>

then

const myMap = new SlippyMapGlobe(100, {
  tileUrl: (x, y, l) => `https://tile.openstreetmap.org/${l}/${x}/${y}.png`
});

const myScene = new THREE.Scene();
myScene.add(myMap);

and on camera position changes:

controls.addEventListener('change', () => {
  myMap.updatePov(camera);
});

API reference

Initialisation

new SlippyMapGlobe(globeRadius: float, { configOptions })

Config options	Description	Default
tileUrl: fn(x, y, l)	The callback function that defines the URL of the tile engine, invoked for each single tile that needs fetching. The slippy map coordinates x, y and l (zoom level) are passed as arguments and the function is expected to return a URL string.	-
minZoom: int	The minimum zoom level of the tiles.	0
maxZoom: int	The maximum zoom level of the tiles.	17
mercatorProjection: boolean	Whether the tile images use a mercator projection. This is usually true for slippy maps tile sets.	true

Attributes

Attribute	Description	Default
tileUrl: fn(x, y, l)	The callback function that defines the URL of the tile engine, invoked for each single tile that needs fetching. The slippy map coordinates x, y and l (zoom level) are passed as arguments and the function is expected to return a URL string.	-
minZoom: int	The minimum zoom level of the tiles.	0
maxZoom: int	The maximum zoom level of the tiles.	17
thresholds: float[]	The list of zoom level shifting thresholds, based on camera proximity to the surface, specified in globe radius units.	[8, 4, 2, 1, 0.5, 0.25, ...]
level: int	The current zoom level the map is in. Can be modified to manually shift zoom levels.	0

Methods

Method	Description
updatePov(camera)	Reports the current position of the camera to this component. The camera object in use should be passed as sole argument. This is necessary to internally calculate which tiles are in view and need to be fetched, as well as controlling automatic zoom level changes. This method should be called everytime the camera changes position, so that the tiles in view and zoom level remains synchronized with what the viewport is showing.
clearTiles()	Removes all the tiles across all zoom levels currently loaded on the map.

Giving Back

If this project has helped you and you'd like to contribute back, you can always buy me a ☕!