Skip to main content

What's New

v4.0 S2 (DGGS)

v4.0 GeoHash (DGGS)

v4.0 Quadkey (DGGS)

v3.4 Geoid (Earth Gravity Model)

v3.2 TypeScript

v3.0 WGS84 & Ellipsoid

v5.0 (In development)​

Status: prerelease development.

Highlights:

  • TypeScript 6.0 or later is required for TypeScript consumers; emitted JavaScript continues to target ES2020.
  • New @math.gl/geometry CPU primitive mesh and tessellation module.
  • glTF 2.1 box, capsule, cylinder, plane and sphere analytic shapes in @math.gl/culling.
  • New expression evaluator module
  • DGGS support is consolidated into a single module with interchangeable decoder objects.
  • New standards-based CRS definitions module and modernized proj4 support.
  • New runtime-independent GeoArrow descriptor and columnar geometry module.
  • New dependency-free WKB, EWKB, and WKT geometry codec module.
  • New typed-array geometry utilities module.
  • Functionality additions to improve 3D Tiles support in loaders.gl.
  • Stronger type guarantees for math classes via the new sized array types.
  • Raised aggregate statement coverage to 96.07% (+5.34 points over the pre-moonshot baseline) across expressions, culling, GeoArrow, DGGS, CRS, geoid, geometry, WKB, and typed-array utilities, with coverage tracked directly in pull request checks.
  • Culling results, polygon winding directions, and Euler rotation orders now use descriptive string literal types.

@math.gl/dggs (NEW MODULE)

  • Consolidates all lightweight DGGS functionality into a single module and removes the individual DGGS packages.
  • Exports DGGS decoder objects with an interchangeable API for encoded data.
  • Aligns the core decoder shape with deck.gl-community's GlobalGridLayer contract.
  • Provides /a5, /geohash, /h3, /plus-code, /quadkey, and /s2 subpath exports from @math.gl/dggs.
  • Detects conventional cell-column names for all bundled decoders to power data-driven visualization layers.

@math.gl/core

  • Added destination-owned Matrix4.fromMatrix3(), Matrix3.fromMatrix4(), and Quaternion.fromEuler() conversion helpers.
  • Euler.fromQuaternion() now supports all six rotation orders and preserves the destination's current order by default.
  • Removed the redundant Euler.getQuaternion() and Euler.toQuaternion() allocation helpers; use Quaternion.fromEuler() instead.
  • Removed deprecated class aliases, compatibility methods, scalar helpers, Euler constants, and root-level low-level namespaces. See the upgrade guide for replacements.
  • Added focused /mat3, /mat4, /quat, /vec2, /vec3, and /vec4 subpath exports for opt-in low-level functions.
  • SphericalCoordinates now uses the structural Vector3Like type and direct calculations, avoiding runtime dependencies on Vector3 and vec3.
  • Core named-import gzip fixtures are 6–62% smaller than v4.1; the full public-entry fixture is 37% smaller. See the bundling guide for methodology and measurements.

@math.gl/expressions (NEW EXPERIMENTAL MODULE)

  • Promotes the expression parser previously embedded in @deck.gl/json to a documented experimental module.
  • Parses, evaluates, and compiles synchronous or asynchronous JavaScript-style expressions.
  • Provides configurable function libraries, including importable basic math and WGS84 geospatial libraries.
  • Adds isolated function registries and optional GeoHash, Quadkey, and S2 function tables.
  • Compiles restricted JSON-style accessor expressions with function calls disabled.
  • Includes an interactive expression playground with editable context and sample DGGS expressions.

@math.gl/crs (NEW MODULE)

  • Adds lightweight, proj4-independent TypeScript definitions for coordinate reference systems with no runtime dependencies.
  • Uses strict PROJJSON v0.7 as its semantic CRS object model and exports types generated from the official schema.
  • Exposes the vendored official PROJJSON v0.7 schema for runtime validation by applications.
  • Represents authority codes, PROJ strings, and WKT definitions as serialized strings.
  • Adds value-preserving WKT1/WKT2 syntax parsing, profile validation, and compact or pretty encoding.
  • Adds ordered PROJ definition and pipeline syntax parsing and encoding.
  • Adds immutable, format-neutral spatial-reference descriptors that preserve definition representation, alternatives, provenance, coordinate epoch, frame, stored order, and explicit default/unknown/absent state.
  • Adds a comprehensive CRS developer guide covering standards, serialization versus semantics, axis order, dynamic and vertical CRS, transformation boundaries, and integration guidance.

@math.gl/wkb (NEW MODULE)

  • Adds dependency-free synchronous WKB, EWKB, and WKT codecs over plain geometry values.
  • Supports both endian orders, ISO and EWKB dimension headers, EWKB SRIDs, all geometry families, nested collections, dimension tokens, MultiPoint variants, and empty geometry.
  • Enforces strict input coverage plus configurable WKB nesting and element-count limits.
  • Supports header-only and count-only visitor traversal that skips coordinate decoding when scalar ordinate callbacks are not requested.
  • Provides the neutral format layer used by @math.gl/geoarrow without depending on GeoArrow or Apache Arrow.

@math.gl/geoarrow (NEW MODULE)

  • Defines borrowed physical descriptors for native, mixed, box, WKB, and WKT geometry columns without requiring an Arrow runtime.
  • Traverses and validates interleaved or separated XY/XYZ/XYM/XYZM coordinates, Int32/Int64 list offsets, sliced validity bitmaps, chunks, dense unions, and geometry collections.
  • Adds synchronous bounds, vertex-count, coordinate-map, layout-conversion, winding, and resource limit kernels.
  • Adds a two-pass builder, WKB/WKT column adapters, Polygon/MultiPolygon tessellation, and an optional worker transfer subpath.
  • Adds direct WKB dimension/family classification, serialized vertex counting, exact per-chunk measure/write conversion, BinaryView access, stable mixed-union schemas, and Arrow-compatible child-null dispatch without materialized geometry rows.
  • Moves reusable GeoArrow math out of loaders.gl and luma.gl prototypes while leaving runtime adapters, worker scheduling, and GPU resources with their owning libraries.

@math.gl/proj4

  • Updates proj4js to v2.20.9 and accepts modern WKT2 definitions and the supported PROJJSON CRS object types.
  • Adds optional CRS axis-order enforcement and NTv2 datum-grid registration.
  • Defines aliases for WGS84 UTM and UPS EPSG coordinate systems automatically.

@math.gl/geospatial

  • makeOBBFromRegion() - New function that creates a cartesian oriented bounding box from a geospatial region.
  • EllipsoidTangentPlane - New helper class for doing math on the ellipsoid surface.

@math.gl/geometry (NEW MODULE)

  • Adds renderer-independent Geometry typed-array storage and indexed-geometry unpacking.
  • Adds tessellators for glTF 2.1 draft shapes and common luma.gl primitives.

@math.gl/culling

  • Adds analytic glTF shape queries for clipping/culling, rays, transforms and enclosing bounds.

@math.gl/geometry-utils (NEW MODULE)

  • Promotes the renderer-independent geometry helpers previously maintained in @loaders.gl/math.
  • Adds typed geometry traversal, vertex-normal generation, component-type conversion, packed RGB565 colors, octahedral attribute compression, and typed-array utilities.

v4.1​

Release Date: Sep 7, 2024.

This minor release brings:

  • type improvements to support more rigorous typing of array lenghts.
  • SPDX-compliant license headers.

@math.gl/core

  • Vector2Like - Matrix4Like - New types to specify numeric inputs of a specific length.

@math.gl/types

  • Bounds, Bounds2D and Bounds3D - New types for expressing bounds (extents).
  • NumberArray2 - NumberArray16 - New types to specify numeric arrays of a specific length.
  • NumericArray2 - NumericArray16 - New types to specify numeric arrays of a specific length.
  • isTypedArray(), isNumericArray() - These utilities now perform typescript type narrowing.

v4.0​

Release Date: Oct 14, 2023.

This release brings:

  • ESM (ECMAScript module) compliant.
  • Node.js v16, v18, v20.
  • Typescript v5
  • gl-matrix dependency removed.
  • New modules for working with DGGS (Discrete Global Grid System) math.

@math.gl/dggs-geohash (NEW MODULE)

  • New module with lightweight math for the GeoHash DGGS (Discrete Global Grid System).

@math.gl/dggs-quadkey (NEW MODULE)

  • New module with lightweight math for the quadkey DGGS (Discrete Global Grid System).

@math.gl/dggs-s2 (NEW MODULE)

  • New module that contains a lightweight implementation of the S2 DGGS (Discrete Global Grid System).

@math.gl/core

  • config is now truly global (stored on globalThis).
  • gl-matrix dependency removed.

@math.gl/types

  • New isTypedArray() and isNumericArray() utilities that check values and return properly restricted types to help write clean TypeScript code (e.g. avoids the DataView case when using ArrayBuffer.isView()).

v3.6​

Release Date: June 10, 2022

Codebase has been fully converted to typescript. In general this means that users can expect the types exported from math.gl to be considerably improved, however in some function signatures are no longer supported. For details, consult the upgrade guide.

@math.gl/types (NEW)

  • New module that exports a few typescript types that e.g. generalize handling of numeric arrays.

@math.gl/polygon (NEW)

  • Includes earcut 2.2 (various bug fixes for edge cases)
  • The earcut utility supports a new argument plane to calculate tesselation on alternative projection planes.

v3.5​

Release Date: July 14, 2021

@math.gl/web-mercator

  • getBounds() now supports an optional fovy parameter on the WebMercatorViewport object
  • getProjectionMatrix() and getProjectionParameters() now accept a fovy parameter

@math.gl/polygon

  • Improve performance of getPolygonSignedArea() by 3x
  • Addition of earcut() method for triangulating polygons

math.gl/culling

  • New TypeScript interface BoundingVolume with common operations for bounding volumes (BoundingSphere, AxisAlignedBoundingBox, OrientedBoundingBox).
  • BoundingVolume.transform() supported on all bounding volumes.

v3.4​

Release Date: Jan 7, 2021

@math.gl/geoid - New module

  • Support for geoid-based earth gravity models.
  • New Geoid class calculates the height offset (aka "undulation") from the pure ellipsoid for a given lng/lat (using spherical harmonics).
  • Geoid instances can be initialized with PGM-encoded earth gravity model coefficient files from standard sources.

@math.gl/polygon

  • Support for flat arrays (e.g. polygons stored in typed arrays)
  • Support for calling polygon utilities directly on arrays, without a Polygon instance.
  • New function modifyPolygonWindingDirection() to modify polygon array winding direction in-place.

v3.3​

Release Date: Oct 9, 2020

@math.gl/proj4 - New module

  • A new module supporting conversion between a wide range of geospatial coordinate reference systems specified e.g. using the OGC WKT-CRS specification.

v3.2​

Release Date: July 18, 2020

Typescript

  • Typescript type definitions (.d.ts files) are now exported for all math.gl modules.

@math.gl/polygon - New module

  • A new module offering geospatial polygon clipping functions.

v3.1​

Release date: Dec 16, 2019

@math.gl/web-mercator​

  • WebMercator projection support is now available through the new @math.gl/web-mercator npm sub-module.
  • The @math.gl/web-mercator module is an evolution of the now archived viewport-mercator-project repository.

v3.0​

Release date: Aug 8, 2019

The 3.0 release brings support for geospatial math, culling, performance improvements, and some API consolidation.

@math.gl/geospatial​

A new module (developed in collaboration with the Cesium engineering team) providing WebGL-framework-independent geospatial math classes and algorithms:

  • New class Ellipsoid and constant Ellipsoid.WGS84 for working with WSG84 coordinates

@math.gl/culling​

A new module (developed in collaboration with the Cesium engineering team) providing WebGL-framework-independent classesthat support geometric intersection calculations (primarily intended to support frustum culling operations):

  • New class AxisAlignedBoundingBox
  • New class OrientedBoundingBox
  • New class BoundingSphere
  • New class CullingVolume

@math.gl/core​

Transform API Consolidation

The API for transformations (i.e. multiplying vectors with matrices or quaternions) has been extended and made more orthogonal:

  • The transform* methods are now available on all Vector classes, in addition to on the Matrix classes. Among other things, this enables transformations without using Matrix classes.
  • Naming consistency of transform methods across classes (transform, transformAsPoint, transformAsVector).
  • Alternative transform methods added to the Vector classes (transformByMatrix3, transformByMatrix2, transformByMatrix2x3 and transformByQuaternion). Simplifies using the most efficient transformation for the job.

Matrix classes

  • New methods Matrix*.setColumn() and Matrix*.getColumn()
  • New method Matrix*.toString()
  • Improved method: Matrix4.frustum() now supports infinite far plane (parity with Matrix4.perspective, which already supported this).

Utility Functions

  • New: global functions toRadians and toDegrees
  • New: global function exactEqual

Performance Improvements (and Website Benchmarks)

A benchmarking example has been added to the website that makes it easy to assess the performance of the math.gl library on your own browser. The math.gl library has been carefully tuned based on these benchmarks and performance of the library has been significantly improved over version 2.x.

v2.3​

Release date: Jan 29, 2019

  • New class: Matrix3
  • New: Add scale factor support to Matrix3 and Matrix4
  • Support quaternion to euler conversion
  • Now uses the official gl-matrix@3.0.0 package as dependency instead of forked gl-matrix packages.

v2.2​

Release date: Sep 20, 2018

  • Use @babel/runtime to reduce bundle size
  • equals function fix on arrays

v2.0​

Release date: June 25, 2018

New Naming Convention for Experimental Exports​

Experimental exports are now exported with a leading underscore (_), instead of as members of the experimental namespace.

The change was made to make it possible for tree-shaking bundlers to remove unused experimental exports from applications.

v1.2​

Release date: May 4, 2018

  • New lerp utility
  • Experimental Pose class

v1.1​

Release date: April 16, 2018

Matrix4 Improvements​

Matrix4.orthographic() - To simplify switching between perspective and orthographic views, math.gl now offers an additional method for creating orthographic projection matrix, that takes the same parameters as Matrix4.perspective(), with the addition of one additional parameter, focalDistance. See Matrix4.orthographic({fovy, aspect, focalDistance, near, far})

Bundle Size Reduction​

math.gl has been tuned to have approximately 20% smaller footprint when bundled in applications.

THREE.js Compatibility​

math.gl classes now pass large parts of the THREE.js test suite, which should make it easier to reuse code written for the THREE.js math library.

v1.0​

Release date: Jan 9, 2018

Initial release.