Overview
Developer Guide
Basics
3D Math
Geospatial Math
API Reference
@math.gl/culling
@math.gl/geoid
@math.gl/geospatial
@math.gl/proj4
@math.gl/sun
@math.gl/web-mercator
Concepts

Ellipsoid A quadratic surface defined in Cartesian coordinates by the equation (x / a)^2 + (y / b)^2 + (z / c)^2 = 1. Primarily used to represent the shape of planetary bodies.

The main use of this class is to convert between the "cartesian" and "cartographic" coordinate systems.

Rather than constructing this object directly, one of the provided constants is used.

Usage

Determine the Cartesian representation of a Cartographic position on a WGS84 ellipsoid.

import {Ellipsoid} from '@math.gl/geospatial';
const cartesianPosition = Ellipsoid.WGS84.cartographicToCartesian(cartographicPosition);

Determine the Cartographic representation of a Cartesian position on a WGS84 ellipsoid.

import {Ellipsoid} from '@math.gl/geospatial';
const cartesianPosition = [17832.12, 83234.52, 952313.73];
const cartographicPosition = Ellipsoid.WGS84.cartesianToCartographic(cartesianPosition);

Get the transform from local east-north-up at cartographic (0.0, 0.0) to Earth's fixed frame.

import {Ellipsoid} from '@math.gl/geospatial';
const transformMatrix = Ellipsoid.WGS84.eastNorthUpToFixedFrame([0, 0, 0]);

Static Fields

An Ellipsoid instance initialized to the WGS84 standard.

Members

Gets the radii of the ellipsoid.

Gets the squared radii of the ellipsoid.

Gets the radii of the ellipsoid raise to the fourth power.

Gets one over the radii of the ellipsoid.

Gets one over the squared radii of the ellipsoid.

Gets the minimum radius of the ellipsoid.

Gets the maximum radius of the ellipsoid.

Methods

constructor(x : Number, y : Number, z : Number)

• x=0 The radius in the x direction.
• y=0 The radius in the y direction.
• z=0 The radius in the z direction.

Throws

• All radii components must be greater than or equal to zero.

clone() : Ellipsoid

Duplicates an Ellipsoid instance.

• {Ellipsoid} [result] Optional object onto which to store the result, or undefined if a new instance should be created.

Returns

• The cloned Ellipsoid.

equals(right : Ellipsoid) : Boolean

Compares this Ellipsoid against the provided Ellipsoid componentwise.

• right The other Ellipsoid. used.

Returns

• true if they are equal, false otherwise.

Returns

cartographicToCartesian(cartographic : Number, result : Number]) : Vector3 | Number

Converts the provided cartographic to Cartesian representation.

• cartographic The cartographic position.
• result Optional object onto which to store the result.

Returns

• The modified result parameter or a new Vector3 instance if none was provided.

cartesianToCartographic(cartesian : Number, result : Number]) : Vector3 | Number | undefined

Converts the provided cartesian to cartographic representation. The cartesian is undefined at the center of the ellipsoid.

• cartesian The Cartesian position to convert to cartographic representation.
• result Optional object onto which to store the result.

Returns

• The modified result parameter, new Vector3 instance if none was provided, or undefined if the cartesian is at the center of the ellipsoid.

eastNorthUpToFixedFrame(origin : Number, ellpsoid : Ellipsoid, result : Number) : Matrix4 | Number

Computes a 4x4 transformation matrix from a reference frame with an east-north-up axes centered at the provided origin to the provided ellipsoid's fixed reference frame.

The local axes are defined as:

• The x axis points in the local east direction.

• The y axis points in the local north direction.

• The z axis points in the direction of the ellipsoid surface normal which passes through the position.

• origin The center point of the local reference frame.

• ellipsoid=Ellipsoid.WGS84 The ellipsoid whose fixed frame is used in the transformation.

• result Optional object onto which to store the result.

Returns

• The modified result parameter or a new Matrix4 instance if none was provided.

Notes

• Calls localFrameToFixedFrame with east, north, up axis.

localFrameToFixedFrame(String firstAxis, secondAxis : String, thirdAxis : String | null, origin : Number[, result : Number]) : Matrix4 | Number

Computes a 4x4 transformation matrix from a reference frame centered at the provided origin to the ellipsoid's fixed reference frame.

• firstAxis name of the first axis of the local reference frame. Must be 'east', 'north', 'up', 'west', 'south' or 'down'.
• secondAxis name of the second axis of the local reference frame.
• thirdAxis name of the third axis of the local reference frame. Can be omitted as it is implied by the cross product of the first two axis.
• origin The center point of the local reference frame.
• result Optional object onto which to store the result.

Returns

• A 4x4 transformation matrix from a reference frame, with first axis and second axis compliant with the parameters, in the modified result parameter or a new Matrix4 instance if none was provided.

geocentricSurfaceNormal(cartesian : Number, result : Number]) : Vector3 | Number

Computes the unit vector directed from the center of this ellipsoid toward the provided Cartesian position.

• cartesian - The WSG84 cartesian coordinate for which to to determine the geocentric normal.
• result - Optional object onto which to store the result.

Returns

• The modified result parameter or a new Vector3 instance if none was provided.

geodeticSurfaceNormalCartographic(cartographic : Number, result : Number]) : Vector3 | Number

Computes the normal of the plane tangent to the surface of the ellipsoid at the provided position.

• cartographic The cartographic position for which to to determine the geodetic normal.
• result Optional object onto which to store the result.

Returns

The modified result parameter or a new Vector3 instance if none was provided.

geodeticSurfaceNormal(cartesian : Number, result : Number]) : Vector3 | Number

Computes the normal of the plane tangent to the surface of the ellipsoid at the provided position.

• cartesian The Cartesian position for which to to determine the surface normal.
• result Optional object onto which to store the result.

Returns

• The modified result parameter or a new Vector3 instance if none was provided.

scaleToGeodeticSurface(cartesian : Number, result : Number]) : Vector3 | Number | undefined

Scales the provided Cartesian position along the geodetic surface normal so that it is on the surface of this ellipsoid. If the position is at the center of the ellipsoid, this function returns undefined.

• cartesian The Cartesian position to scale.
• result Optional object onto which to store the result.

Returns

• The modified result parameter, a new Vector3 instance if none was provided, or undefined if the position is at the center.

scaleToGeocentricSurface(cartesian : Number, result : Number]) : Vector3 | Number

Scales the provided Cartesian position along the geocentric surface normal so that it is on the surface of this ellipsoid.

• cartesian The Cartesian position to scale.
• result Optional object onto which to store the result.

Returns

• The modified result parameter or a new Vector3 instance if none was provided.

transformPositionToScaledSpace(position : Number, result : Number]) : Vector3 | Number

Transforms a Cartesian X, Y, Z position to the ellipsoid-scaled space by multiplying its components by the result of Ellipsoid.oneOverRadii.

• position The position to transform.
• result Optional array into which to copy the result.

Returns

• The position expressed in the scaled space. The returned instance is the one passed as the result parameter if it is not undefined, or a new instance of it is.

transformPositionFromScaledSpace(position : Number, result : Number]) : Vector3 | Number

Transforms a Cartesian X, Y, Z position from the ellipsoid-scaled space by multiplying its components by the result of Ellipsoid.radii.

• position The position to transform.
• result Optional array to which to copy the result.

Returns

• The position expressed in the unscaled space. The returned array is the one passed as the result parameter, or a new Vector3 instance.

getSurfaceNormalIntersectionWithZAxis(position, buffer, result) : | undefined

Computes a point which is the intersection of the surface normal with the z-axis.

• position the position. must be on the surface of the ellipsoid.
• buffer=0.0 A buffer to subtract from the ellipsoid size when checking if the point is inside the ellipsoid.
• result Optional array into which to copy the result.

Returns

• The intersection point if it's inside the ellipsoid, undefined otherwise.

Throws

• position is required.