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

``bash
yarn add three three-map-terrain
`




Basic - Quick start

`typescript
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


`tsx
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

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 (

{map && }

)
}
`
See full example

Documentation

$3

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

`typescript
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 | - |

$3

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

`javascript
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
`typescript
{
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
`typescript
{
lights: true,
wireframe: false,
fog: true
}
`

$3


#### Init map cache

`typescript
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


`typescript
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

`typescript
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.

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