Three-map-terrain NPM

three-map-terrain

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

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.

three map terrain landscape geolocation react

@everything-registry/sub-chunk-2939

1.0.1

1 year ago

1.0.0

1 year ago