| !draw tool | !Potree point cloud | !GeoTIFF elevation |
| ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------ |
| !alt text | !alt text | !alt text |

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.

$3

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

$3

- DEM/DTM/DSM through WMTS
- Elevation GeoTIFFs

$3

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

$3

- 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)

$3

- 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:

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

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

`zsh
docker build -t giro3d:local https://gitlab.com/giro3d/giro3d.git#
`

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

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

Then open your browser on the following URL: .

> [!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):

`bash
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:

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

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

`js
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:

`bash
npm test
`

API documentation and examples

Browse the API Documentation documentation or check the examples.

$3

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

To run the examples locally:

`bash
npm run start
`

Then open (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:

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

$3

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

$3

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.

$3

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.

$3

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.

$3

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.