A versatile framework to visualize geospatial data in the browser.
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.
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
- 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
Elevation data
Vector data
Point clouds
3D assets
- 3D Tiles for optimized massive 3D datasets, including point clouds
- glTF for individual models
Getting started
💡 To test Giro3D without installing anything, check the interactive examples.
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.
This is handy if you need to develop on Giro3D alongside your project. You need to first prepare the
package folder and link from there:
npm run make-package
cd build/giro3d
npm link
npm link @giro3d/giro3d
To ease development, files can be automatically transpiled on modification with the watch
script :
npm run watch
Each time a source file is modified, this script will transpile it in the build folder.
Tests
To run the test suite:
npm test
API documentation and examples
Browse the API Documentation documentation or check the examples.
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.
v0.42.0 (2025-02-10)
Improved 3D Tiles support
This release integrates the 3d-tiles-renderer
package into Giro3D. This enables a much better support for the 3D Tiles format, including the 3D Tiles 1.1 specification. This makes it very easy to load Google Photorealistic 3D Tiles into Giro3D !
Cast shadows and dynamic lighting in Maps
Maps now support light-based shadows and lighting provided by three.js lights, in addition to the hillshade mode (which is still the default mode). When using this mode, the terrain is shaded by all directional and point lights in the scene. This allows for light-based simulations such as sun shadows for a given time of day for example.
BREAKING CHANGE
-
Map lighting and shading options have changed:
- Map lighting options are now under
entities/
rather than core/
- Map lighing options are renamed
MapLightingOptions
- Hillshade specific lighting options are prefixed
hillshade
(e.g
hillshadeAzimuth
, hillshadeIntensity
...)
-
The Tiles3D
entity's API has changed and the
Tiles3DSource
class is removed. Please refer to the API documentation
for more information.
-
The ColorMap
constructor now uses named parameters
rather than positional parameters, i.e new ColorMap({ colors, min, max })
-
ColorMap
and ColorMapMode
are moved from /core/layer/
into /core
since they don't apply only to layers.
Feat
- Map: support light-based lighting and shadows (#502, #443)
- Sun: add functions to compute the position of sun
- AxisGrid: support adaptive labels (#555)
- AxisGrid: add
"label-created"
event to customize the DOM label after creation - ColorMap: add
.clone()
method - Tiles3D: replace underlying implementation with 3d-tiles-renderer (#191)
- StatusBar: add function to dynamically update attributions
- FeatureCollection: support shading through the style API
- WmsSource: add support for the .requestPriority constructor option (#305)
- VectorTileSource: add support for the .requestPriority constructor option (#305)
- VectorSource: add support for the .requestPriority constructor option (#305)
- TiledImageSource: add support for the .requestPriority constructor option (#305)
- StaticImageSource: add support for the .requestPriority constructor option (#305)
- GeoTIFFSource: add support for the .requestPriority constructor option (#305)
- ImageSource: support HTTP priorities (#305)
- Fetcher: support request priority (#305)
- PointCloud: add the
.brightness
, .constrast
and .saturation
properties
Fix
- GeoTIFFSource: fix incorrect count of images (#568)
- PointCloud: clone the default ColorMap
- PointCloudMaterial: enable transparent flag if colormap has an opacity array (#559)
- PointCloud: compute the world matrix of the node before the bounding box (#556)
- GeometryConverter: support triangulation of vertical polygons (#544)