search

w3reality / three-geo

3D geographic visualization library
MIT License
1.06k stars 177 forks source link
dataviz gis gps-coordinates terrain threejs

readme

three-geo

NPM MIT licensed CI

three-geo is a three.js based geographic visualization library. Using three-geo, we can easily build satellite-textured 3D terrain models in near real-time by simply specifying GPS coordinates anywhere on the globe. The geometry of the terrain is based on the RGB-encoded DEM (Digital Elevation Model) provided by the Mapbox Maps API.

The terrain is represented by standard THREE.Mesh objects. This makes it easy for us to access underlying geometry/texture array and perform original GIS (Geographic Information System) experiments in JavaScript. (See Usage for how to programatically obtain those mesh objects).

Credits: this library has been made possible thanks to

Demo

1) examples/geo-viewer (live | source code)

This demo app includes features such as

Live:

2) examples/heightmaps (live | source code)

This demo illustrates the relationship between a reconstructed 3D terrain and its underlying satellite/DEM tiles.

image

3) examples/flat (live | source code)

How to get a flattened view of the terrain by post-editing the underlying geometry.

4) examples/projection (live | source code)

How to register a new 3D object on top of the terrain based on its geographic location [latitude, longitude, elevation].

Setup

Installation

$ npm i three-geo

Loading

Script tag: use ThreeGeo after

<script src="https://github.com/w3reality/three-geo/raw/master/dist/three-geo.min.js"></script>

ES6:

import ThreeGeo from 'dist/three-geo.esm.js';

Usage

Here is an example of how to build a geographic terrain located at GPS coordinates (46.5763, 7.9904) in a 5 km radius circle. The terrain's satellite zoom resolution is set to 12. (The highest zoom value supported is 17.)

For standalone tests, use examples/simple-viewer (source code).

For use with NodeJS, do enable this isNode option as well.

const tgeo = new ThreeGeo({
    tokenMapbox: '********', // <---- set your Mapbox API token here
});

const terrain = await tgeo.getTerrainRgb(
    [46.5763, 7.9904], // [lat, lng]
    5.0,               // radius of bounding circle (km)
    12);               // zoom resolution

const scene = new THREE.Scene();
scene.add(terrain);

const renderer = new THREE.WebGLRenderer({ canvas });
renderer.render(scene, camera);

image

Who is using three-geo?

API

In this section, we list three-geo's public API methods, where origin, radius, and zoom are parameters common to them:

ThreeGeo

Legacy callback based API - `getTerrain(origin, radius, zoom, callbacks={})` - `callbacks.onRgbDem` **function (meshes) {}** Implement this to request the geometry of the terrain. Called when the entire terrain\'s geometry is obtained. - `meshes` **Array\** All the meshes belonging to the terrain. - `callbacks.onSatelliteMat` **function (mesh) {}** Implement this to request the satellite textures of the terrain. Called when the satellite texture of each mesh belonging to the terrain is obtained. - `mesh` **THREE.Mesh** One of the meshes that's part of the terrain. - `callbacks.onVectorDem` **function (objs) {}** Implement this to request the contour map of the terrain. Called when the contour map of the terrain is obtained. - `objs` **Array\** Extruded meshes (**THREE.Mesh** objects with `.name` attribute prefixed by `dem-vec-shade--`) and lines (**THREE.Line** objects with `.name` attribute prefixed by `dem-vec-line--`), where `` is the height of each contour in meters.

Build

After git clone and cd to the repository,

$ npm i
$ npm run build

Building on Windows

While npm run build on Windows is confirmed to work (via GitHub's workflow with some tweaks), for better results, it is recommended to use WSL2 instead (thanks @sonicviz for reporting this).