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
• [x] React example
• [x] Basic example

License and attributions

The map library code is MIT licensed.