Overview
Developer Guide
@math.gl/culling
@math.gl/geospatial
@math.gl/sun
@math.gl/web-mercator
API Reference
@math.gl/culling
@math.gl/geospatial
@math.gl/polygon
@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 {toRadians} from '@math.gl/core';
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.

### toString() : String

Creates a string representing this Ellipsoid in the format used `'[radii.x, radii.y, radii.z]`.

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.
• `Ellipsoid` must be an ellipsoid of revolution (`radii.x == radii.y`).
• Ellipsoid.radii.z must be greater than 0.

Notes:

• In earth case, with common earth datums, there is no need for this buffer since the intersection point is always (relatively) very close to the center.
• In WGS84 datum, intersection point is at max z = +-42841.31151331382 (0.673% of z-axis).
• Intersection point could be outside the ellipsoid if the ratio of MajorAxis / AxisOfRotation is bigger than the square root of 2