Introduction
Welcome to math.gl! math.gl is JavaScript (TypeScript) math library focused on geospatial and 3D use cases. Designed as a composable, modular toolbox. math.gl provides a core module with classic vector and matrix classes, and a suite of optional modules implementing various aspects of geospatial and 3D math.
While math.gl is highly optimized for use with the WebGL and WebGPU APIs, it has no WebGL dependencies and is designed to be usable in any application.
Features
- 3D math - Basic vectors and matrices, as well as 3D primitives and culling:
@math.gl/types,@math.gl/core,@math.gl/culling - Geospatial projections - Support for a variety of geospatial projections
@math.gl/geospatial,@math.gl/geoid,@math.gl/proj4,@math.gl/web-mercator - Geospatial utilities - Cutting polygons and calculating sun position and direction
@math.gl/polygon,@math.gl/sun - Discrete Global Grids - Standardized interfaces to a number of the major discrete global grids.
@math.gl/dggs-geohash,@math.gl/dggs-quadkey,@math.gl/dggs-s2
Modules
math.gl is a toolbox that offers a suite of composable modules.
| Core math libraries | Module | Description |
|---|---|---|
@math.gl/types | Basic math type helpers (NumericArray etc) | |
 | @math.gl/core | 3D math classes (vectors, matrices, etc) |
 | @math.gl/culling | Bounding volumes and intersection testing. |
| Geospatial math libraries | Module | Description |
|---|---|---|
 | @math.gl/geospatial | Ellipsoidal math for WGS84 coordinates. |
 | @math.gl/geoid | Earth Gravity Model support . |
@math.gl/polygon | Polygon math, including geospatial cutting etc. | |
@math.gl/proj4 | Conversion between coordinate reference systems. | |
@math.gl/sun | Solar position / direction from position and time. | |
@math.gl/web-mercator | Supports 3D Web Mercator (spherical) projections. |
| DGGS (Discrete global grid support) libraries | Module | Description |
|---|---|---|
 | @math.gl/dggs-geohash | Get geometry of GeoHash tokens. |
 | @math.gl/dggs-quadkey | Get geometry of QuadKey tokens |
 | @math.gl/dggs-s2 | Get geometry of S2 tokens. |
In addition, math.gl provides a few deprecated legacy modules, to avoid breaking older applications.
| Legacy Module | Description |
|---|---|
math.gl | Re-exports the API from @math.gl/core. An "alias" for @math.gl/core to avoid breaking old applications. |
viewport-mercator-project | Re-exports the Web Mercator projection utilities in @math.gl/web-mercator. The viewport-mercator-project repository was moved to math.gl in Oct 2019. |
Supported Browsers and Node Versions
math.gl is fully supported on:
- Evergreen browsers: Recent versions of Chrome, Safari, Firefox, Edge etc.
- Node.js: Active and Maintenance LTS releases
History
| Year | Version | Description |
|---|---|---|
| 2015 | N/A | @math.gl/core classes were created as part of luma.gl v4, as a set of class wrappers for gl-matrix for luma.gl and deck.gl frameworks. |
| 2017 | v1.0 | math.gl was broken out into its own repository to manage luma.gl growth. The goal was to independently usable set of 3D and Geospatial math modules. |
| 2018 | v2.0 | The math.gl API started to mature. |
| 2019 | v3.0 | A collaboration with the Cesium team around 3D Tiles led to parts of the Cesium math library were ported into the math.gl/geospatial and @math.gl/culling modules. |
| 2020+ | v3.x | Additional geospatial modules have gradually been added to support more advanced use cases for deck.gl. |
| 2022 | v3.6 | Code base fully rewritten in TypeScript. |
| 2023 | v4.0 | ES module support. gl-matrix was removed as a dependency and math.gl became fully stand-alone. |
Attributions
math.gl was inspired by and built upon some of the most proven open source JavaScript math libraries:
gl-matrix- math.gl classes use gl-matrix under the hood- THREE.js math library - math.gl classes are API-compatible with a subset of the THREE.js classes and pass THREE.js test suites.
- The CesiumJS math library (Apache2) - The geospatial and culling modules were ported from Cesium code base.
License
MIT license. The libraries that the core @math.gl/core module are built on (e.g. gl-matrix) are also all open source and MIT licensed.
The @math.gl/geospatial and @math.gl/culling modules include Cesium-derived code which is Apache2 licensed.
math.gl will never include any code that is not under permissive license.