| | | | | ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------ | | | | |

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

• Mapbox Vector Tiles
• GeoJSON
• TopoJSON
• KML
• GPS Exchange Format (GPX)

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.

Support

Giro3D is the successor of iTowns, an original work from IGN and MATIS research laboratory. It has been funded through various research programs involving the French National Research Agency, Cap Digital, The Sorbonne University, Mines ParisTech, CNRS, IFSTTAR, Région Auvergne-Rhône-Alpes.

Giro3D is currently maintained by Oslandia.

No code with Piero

In case you don't want to code your own application, you can also use Piero, our sister project - also available on GitLab.

FAQ

Where does the name Giro3D come from ?

The name is a reference to the italian mathematician and inventor Girolamo Cardano.

What licenses does Giro3D use ?

The Giro3D source code and example code is licensed under the MIT license. The Giro3D website, documentation, and images are licensed under the CC BY-SA license.

Can I use Giro3D in React/Vue/Angular... framework ?

Yes, Giro3D should integrate without issue in those frameworks. We have tested and integrated Giro3D in React and Vue extensively.

If you notice any issue while integrating Giro3D in your GUI framework, please let us know by creating an issue.

Does Giro3D support this data format ?

Giro3D can directly load a number of data formats as mentioned in the "supported data sources" section of this document.

Additionally, some other formats might be directly supported by Giro3D via OpenLayers, but are not yet tested.

Finally, you can easily implement your own data sources by subclassing the relevant base class, such as ImageSource for draped image, PointCloudSource for point cloud data, and so on.

[!note] If you wish to see a particular format supported in Giro3D, you can let us know by creating an issue. Keep in mind however that Giro3D is a web library and thus puts emphasis on formats that are optimized for web streaming, such as COPC for point cloud, 3D Tiles, Cloud optimized GeoTIFFs, etc.

Can Giro3D work as a desktop application ?

A web app built with Giro3D can be packaged using Electron or any similar application packagers. However, if you encouter compatibility issues, please let us know by creating an issue.