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="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\<THREE.Mesh\>** 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\<THREE.Object3D\>** 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. </details></p> ## 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](https://github.com/w3reality/three-geo/blob/b8775e3a3e2d6b815fd550a96f7f45e441ff54a2/.github/workflows/nodejs.yml#L30-L32)), for better results, it is recommended to use WSL2 instead (thanks [@sonicviz](https://github.com/sonicviz) for [reporting this](https://github.com/w3reality/three-geo/issues/44#issuecomment-1482906468)).

This site is open source. Improve this page.