@giro3d/giro3d NPM

What is Giro3D ?

Giro3D is a Web library written in TypeScript to build 2D and 3D geospatial scenes. It is powered by three.js and WebGL. It aims to support major geospatial standards and provide a rich feature set to help visualize data in a 3D environment.

!note Giro3D is designed to integrate well in major UI frameworks such as React and Vue.

Features

2D and 3D maps with unlimited color layers, real-time lighting and a broad range of data sources (tiled images, GeoTIFFs, static images, vector data, including Vector tiles).
High-resolution terrain rendering with elevation querying / elevation profile
Support of shadow maps on terrain
Point clouds colored by classification, colormaps or color layer
Create shapes and annotations, including height measurements and angular sectors.
Easy to integrate with GUI frameworks such as Vue and React.
Limit visibility of datasets using cross-sections
Display 3D features with a rich style API

Supported data sources

Giro3D is powered by OpenLayers for maps, and three.js for 3D assets, and can be easily extended to support more.

Below is a non-exhaustive list of supported data sources.

Image data

WMTS
WMS
TMS
GeoTIFF, with support for Cloud Optimized GeoTIFFs (COG)
Static images

Elevation data

DEM/DTM/DSM through WMTS
Elevation GeoTIFFs

Vector data

Point clouds

Potree datasets
- Regular (bin file) point clouds
- LAZ Potree point clouds
Cloud Optimized Point Clouds (COPC)
LAS/LAZ files
3D Tiles with .pnts tiles (you can generate them with py3dtiles)

3D assets

3D Tiles for optimized massive 3D datasets, including point clouds
glTF for individual models

!note You can also implement your own data sources, such as image sources or point cloud sources, as well as your own entities.

Getting started

💡 To test Giro3D without installing anything, check the interactive examples.

🐋 Quick start with Docker

To run the examples locally without installing Node or NPM and without cloning the repository, you can use Docker to build and run an arbitrary branch of Giro3D:

docker run --rm -p 8080:8080 $(docker build https://gitlab.com/giro3d/giro3d.git#<branch> -q)

Alternatively, a two-step method to see the Docker output:

docker build -t giro3d:local https://gitlab.com/giro3d/giro3d.git#<branch>

docker run --rm -p 8080:8080 giro3d:local

Replace <branch> with the branch name, (e.g main).

Then open your browser on the following URL: http://localhost:8080.

!note This procedure will not work on branches that do not contain a Dockerfile.

Install from the NPM package

To install with npm (recommended method):

npm install --save @giro3d/giro3d

This package contains both original sources (under src/) and slightly processed sources (dead code elimination, inlining shader code...).

If you're using a module bundler (like wepback) or plan on targeting recent enough browser, you can directly import it as such:

import Instance from '@giro3d/giro3d/core/Instance.js';

You can also import the original, untranspiled sources, by adding src after @giro3d/giro3d/ :

import Instance from '@giro3d/giro3d/src/core/Instance.js';

This will probably limit browser compatibility though, without application specific process or loader. Also, non .js files (such as .glsl files) will need to be inlined at client application level.

From a release bundle

See our release page.

Tests

To run the test suite:

npm test

API documentation and examples

Browse the API Documentation documentation or check the examples.

Running examples locally

The examples are the main way to test and develop Giro3D.

To run the examples locally:

npm run start

Then open <localhost:8080> (or the port that was mentioned in the build log) to see the example page.

To run a single example, for example the osm example, set the EXAMPLE environment variable to the name of the example:

EXAMPLE=osm npm run start

!note Any change in the source code (typescript or GLSL files) will automatically reload the example. Other changes, such as HTML or CSS require a manual refresh of the page.

Contributors and sponsors

Giro3D has received contributions and sponsoring from people and organizations listed in CONTRIBUTORS.md. If you are interested in contributing to Giro3D, please read CONTRIBUTING.md.