three-map-terrain

A JavaScript library to build 3D maps with three.js.

Live demo / Source code

About

three-map-terrain takes two slippy map tilesets, one to fetch elevation data tiles, the other to texture the meshes built from said elevation data (any XYZ tileserver will do).

Installation

yarn add three three-map-terrain

Basic - Quick start

import { Scene } from 'three'
import { Map, Source } from 'three-map-terrain'

const scene = new Scene()

const location = { lat: 46.57634, lon: 7.9904 }
const source = new Source({ api: 'eox' })
const map = new Map({ source, location })

scene.add(map)
map.init(() => {
  console.log('Map is ready')
})

See full example

React - Quick start

import { useEffect, useState } from 'react'
import { Canvas } from '@react-three/fiber'
import { Map, Source } from 'three-map-terrain'

export default function App() {
  const [map, setMap] = useState<Map>()

  useEffect(() => {
    setMap(
      new Map({
        source: new Source({ api: 'eox' }),
        location: { lat: 46.57634, lon: 7.9904 }
      })
    )
  }, [])

  useEffect(() => {
    if (map) {
      map.init(() => console.log('Map is ready'))
    }
  }, [map])

  return (
    <Canvas>
      {map && <primitive object={map.terrain} position={[0, 0, 0]} />}
    </Canvas>
  )
}

See full example

Documentation

Source class

Defines a tileset source used to fetch textures applied to the 3D terrain mesh.

const source = new Source({ api, token })

Argument	Description	Required	Default Value
api	One of ['osm', 'mapbox', 'eox', 'maptiler']	true	-
token	Your api key	for mapbox or maptiler	-

Map class

The main class three-map-terrain. Creates a 3D map using a grid of tiles.

const map = new Map({ source, location, options, material })

Argument	Type	Description	Required	Default Value
source	Source	A source instance	true	-
position	{ lat: number, lon: number }	An object containing the latitude and longitude values used to center the map	true	-
options	MapOptions	An object to pass some map options (override)	false	defaultMapOptions
material	QuadTextureMaterialOptions	An object to pass some material options (override)	false	defaultTextureOptions

The MapOptions type

Option	Type	Description
nTiles	number	Map.init() will display a grid of nTiles x nTiles
zoom	number	Default zoom level
tileSize	number	Tile size at the default zoom level
tileSegments	number	Number of segments given to the PlaneGeometry constructor. Maximum value is 256
zScale	number	The raw elevation data is multiplied by zScale when building a Tile mesh

The defaultMapOptions object

{
  nTiles: 3,
  zoom: 11,
  tileSize: 600,
  tileSegments: 100,
  zScale: 0.045
}

The QuadTextureMaterialOptions type

These props are passed to ShaderMaterial.

Option	Type	Description
lights	boolean	Defines whether this material uses lighting; true to pass uniform data related to lighting to this shader
wireframe	boolean	Render geometry as wireframe (using GL_LINES instead of GL_TRIANGLES)
fog	boolean	Define whether the material color is affected by global fog settings; true to pass fog uniforms to the shader

The defaultTextureOptions object

{
  lights: true,
  wireframe: false,
  fog: true
}

Map helpers

Init map cache

map.init(() => { console.log('Map is ready') })

Argument	Type	Description	Required	Default Value
callback	() => void	Ready callback	false	-

Determine the location of a point by coordinates

const posInVector3 = map.getPosition(
  {
    lat: 46.57634,
    lon: 7.9904,
    alt: 3e3
  },
  { loadTile: true }
)

Argument	Type	Description	Required	Default Value
location	{ lat: number, lon: number, alt: number }	Your geolocation	true	-
options	{ loadTile: number }	Extra options (override)	false	{ loadTile: true }

Parameter loadTile determines whether to load the required tile if you have specified coordinates that are outside the already loaded tiles.

Reset map cache

map.clean()

Future list

• Asynchronous analog of the getPosition function without passing the altitude parameter
• Advanced example
• Base Pin component
• Base Direction component
• Vue example
• React example
• Basic example

License and attributions

The map library code is MIT licensed.

This project is an updated and more advanced version of the map33.js library.