math.gl

What is math.gl?

math.gl is a suite of JavaScript libraries designed for high-precision mathematical computations, particularly in the context of computer graphics and geospatial applications. It provides a range of utilities for vector and matrix operations, geospatial transformations, and more.

What are math.gl's main functionalities?

Vector Operations

math.gl provides a comprehensive set of vector operations. This example demonstrates how to create vectors and perform addition.

const {Vector3} = require('math.gl');
const v1 = new Vector3(1, 2, 3);
const v2 = new Vector3(4, 5, 6);
const v3 = v1.add(v2);
console.log(v3); // Vector3 { x: 5, y: 7, z: 9 }

Matrix Operations

math.gl supports various matrix operations. This example shows how to create identity and translation matrices and multiply them.

const {Matrix4} = require('math.gl');
const m1 = new Matrix4().identity();
const m2 = new Matrix4().translate([1, 2, 3]);
const m3 = m1.multiplyRight(m2);
console.log(m3); // Matrix4 { elements: [1, 0, 0, 1, 0, 1, 0, 2, 0, 0, 1, 3, 0, 0, 0, 1] }

Geospatial Transformations

math.gl includes utilities for geospatial transformations. This example demonstrates converting cartographic coordinates to Cartesian coordinates using an ellipsoid model.

const {Ellipsoid} = require('math.gl/geospatial');
const ellipsoid = new Ellipsoid(6378137.0, 6356752.314245);
const cartesian = ellipsoid.cartographicToCartesian([0.1, 0.1, 0]);
console.log(cartesian); // Vector3 { x: 6378137.0, y: 11131.949079327358, z: 11131.949079327358 }

Other packages similar to math.gl

gl-matrix

gl-matrix is a high-performance matrix and vector library for WebGL. It is highly optimized for speed and provides similar functionalities for vector and matrix operations. However, it lacks the geospatial transformation utilities found in math.gl.

three.js

three.js is a popular 3D library that includes a math module for vector and matrix operations. While it is more comprehensive in terms of 3D rendering capabilities, its math utilities are not as specialized for high-precision or geospatial computations as math.gl.

turf

Turf is a geospatial analysis library for JavaScript. It provides a wide range of geospatial functions, including transformations and calculations. While it is more focused on geospatial analysis, it does not offer the same level of general-purpose vector and matrix operations as math.gl.

README

math.gl | Docs

math.gl

math.gl is an Array-based JavaScript 3D math library. In spite of its name it has no hard WebGL dependencies, but however both API and design are focused on the needs of typical WebGL applications

Features

This is a short list of feature high-lights to show what math.gl is about.

• Array-based Classes - All math.gl classes (like Vector3, Matrix4) are subclasses of the built-in JavaScript Array class. This means that they can be used directly with any Javascript function that e.g. expects plain JavaScript Array arguments for Vectors, which is increasingly common.

• Debug Friendly - JavaScript math can be frustrating to code and debug. math.gl offers optional error checking after every math operation which makes quick work of locating coding errors and bad data. Also, strong "printing support" (toString) simplifies debugging.

• WebGL Support - Matrices are stored internally in the format required by WebGL (array of contiguous values in column-major order), while exposing the more "natural" row-major API to the JavaScript programmer (e.g. through accessors, printing using toString() etc).

• Documentation - Some JavaScript 3D math libraries come with reference documentation only. If you are new to 3D programming it can be hard to know where to start. math.gl comes with articles that try to show you the big picture and get you quickly up-to-speed on the mathematical concepts and the math.gl classes that support them.

• Size Conscious - A math library can quickly get big as a various classes and functions keep getting added. But for many 3D applications, only a few basic operations are necessary. math.gl has made a choices to restrict itself to a set of classes and functions that are likely to be most important in WebGL applications. The intention is to position math.gl as a "mid-size" 3D math library: reasonably full featured, but small enough that unless you are targeting a very small final bundle for your application, its size should not be a big concern.

Supported Browsers and Node Versions

math.gl is only supported on "evergreen" browsers, such as Chrome, Safari, Firefox, Edge etc. While not evergreen, IE11 should support the math.gl distribution's transpiled code, but Internet Explorer < 10 will not work. math.gl also works on recent versions of Node.js (tested on v6+).

Disclaimer: These restrictions are both due to real technical limitations with math.gl's Arraysubclassing approach, as well as a conscious decision by the maintainers to limit the support matrix for the library. So, if your application needs to support non-evergreen browsers, math.gl is unlikely to be the right choice for you. A good alternative option could be to use e.g. gl-matrix directly.

History

math.gl was developed as a companion 3D math library for the luma.gl and deck.gl WebGL frameworks, and the precursors of the math.gl classes were in fact part of luma.gl v4.0, but have now been broken out in this separate library.

In spite of its roots, the intention is that math.gl should be able to serve a general purpose 3D math library, and be used either directly or as a "starting point" by other projects with similar needs.

Attribution

math.gl heavily inspired by, and includes code, documentation and ideas from some of the most proven open source JavaScript math libraries, the awesome gl-matrix and the THREE.js math library. Those libraries encouraged reuse which enabled math.gl to be built, and naturally math.gl does the same!

License

MIT license. The libraries that math.gl are built on are also all open source and MIT licensed.