# Ellipsoid

#### new Ellipsoid(x, y, z)

A quadratic surface defined in Cartesian coordinates by the equation `(x / a)^2 + (y / b)^2 + (z / c)^2 = 1`. Primarily used by Cesium to represent the shape of planetary bodies. Rather than constructing this object directly, one of the provided constants is normally used.
Name Type Default Description
`x` Number `0` optional The radius in the x direction.
`y` Number `0` optional The radius in the y direction.
`z` Number `0` optional The radius in the z direction.
##### Throws:
• DeveloperError : All radii components must be greater than or equal to zero.

### Members

#### staticconstantEllipsoid.MOON :Ellipsoid

An Ellipsoid instance initialized to a sphere with the lunar radius.

#### staticconstantEllipsoid.UNIT_SPHERE :Ellipsoid

An Ellipsoid instance initialized to radii of (1.0, 1.0, 1.0).

#### staticconstantEllipsoid.WGS84 :Ellipsoid

An Ellipsoid instance initialized to the WGS84 standard.

Gets the maximum radius of the ellipsoid.

Gets the minimum radius of the ellipsoid.

Gets one over the radii of the ellipsoid.

Gets one over the squared radii of the ellipsoid.

Gets the radii of the ellipsoid.

Gets the squared radii of the ellipsoid.

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

### Methods

#### staticEllipsoid.clone(ellipsoid, result) → Ellipsoid

Duplicates an Ellipsoid instance.
Name Type Description
`ellipsoid` Ellipsoid The ellipsoid to duplicate.
`result` Ellipsoid optional The object onto which to store the result, or undefined if a new instance should be created.
##### Returns:
The cloned Ellipsoid. (Returns undefined if ellipsoid is undefined)

Computes an Ellipsoid from a Cartesian specifying the radii in x, y, and z directions.
Name Type Default Description
`radii` Cartesian3 `Cartesian3.ZERO` optional The ellipsoid's radius in the x, y, and z directions.
##### Returns:
A new Ellipsoid instance.
##### Throws:
• DeveloperError : All radii components must be greater than or equal to zero.

#### cartesianArrayToCartographicArray(cartesians, result) → Array.<Cartographic>

Converts the provided array of cartesians to an array of cartographics.
Name Type Description
`cartesians` Array.<Cartesian3> An array of Cartesian positions.
`result` Array.<Cartographic> optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Array instance if none was provided.
##### Example:
``````//Create an array of Cartesians and determine their Cartographic representation on a WGS84 ellipsoid.
var positions = [new Cesium.Cartesian3(17832.12, 83234.52, 952313.73),
new Cesium.Cartesian3(17832.13, 83234.53, 952313.73),
new Cesium.Cartesian3(17832.14, 83234.54, 952313.73)]
var cartographicPositions = Cesium.Ellipsoid.WGS84.cartesianArrayToCartographicArray(positions);``````

#### cartesianToCartographic(cartesian, result) → Cartographic

Converts the provided cartesian to cartographic representation. The cartesian is undefined at the center of the ellipsoid.
Name Type Description
`cartesian` Cartesian3 The Cartesian position to convert to cartographic representation.
`result` Cartographic optional The object onto which to store the result.
##### Returns:
The modified result parameter, new Cartographic instance if none was provided, or undefined if the cartesian is at the center of the ellipsoid.
##### Example:
``````//Create a Cartesian and determine it's Cartographic representation on a WGS84 ellipsoid.
var position = new Cesium.Cartesian(17832.12, 83234.52, 952313.73);
var cartographicPosition = Cesium.Ellipsoid.WGS84.cartesianToCartographic(position);``````

#### cartographicArrayToCartesianArray(cartographics, result) → Array.<Cartesian3>

Converts the provided array of cartographics to an array of Cartesians.
Name Type Description
`cartographics` Array.<Cartographic> An array of cartographic positions.
`result` Array.<Cartesian3> optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Array instance if none was provided.
##### Example:
``````//Convert an array of Cartographics and determine their Cartesian representation on a WGS84 ellipsoid.
var cartesianPositions = Cesium.Ellipsoid.WGS84.cartographicArrayToCartesianArray(positions);``````

#### cartographicToCartesian(cartographic, result) → Cartesian3

Converts the provided cartographic to Cartesian representation.
Name Type Description
`cartographic` Cartographic The cartographic position.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Cartesian3 instance if none was provided.
##### Example:
``````//Create a Cartographic and determine it's Cartesian representation on a WGS84 ellipsoid.
var cartesianPosition = Cesium.Ellipsoid.WGS84.cartographicToCartesian(position);``````

#### clone(result) → Ellipsoid

Duplicates an Ellipsoid instance.
Name Type Description
`result` Ellipsoid optional The object onto which to store the result, or undefined if a new instance should be created.
##### Returns:
The cloned Ellipsoid.

#### equals(right) → Boolean

Compares this Ellipsoid against the provided Ellipsoid componentwise and returns `true` if they are equal, `false` otherwise.
Name Type Description
`right` Ellipsoid optional The other Ellipsoid.
##### Returns:
`true` if they are equal, `false` otherwise.

#### geocentricSurfaceNormal(cartesian, result) → Cartesian3

Computes the unit vector directed from the center of this ellipsoid toward the provided Cartesian position.
Name Type Description
`cartesian` Cartesian3 The Cartesian for which to to determine the geocentric normal.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Cartesian3 instance if none was provided.

#### geodeticSurfaceNormal(cartesian, result) → Cartesian3

Computes the normal of the plane tangent to the surface of the ellipsoid at the provided position.
Name Type Description
`cartesian` Cartesian3 The Cartesian position for which to to determine the surface normal.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Cartesian3 instance if none was provided.

#### geodeticSurfaceNormalCartographic(cartographic, result) → Cartesian3

Computes the normal of the plane tangent to the surface of the ellipsoid at the provided position.
Name Type Description
`cartographic` Cartographic The cartographic position for which to to determine the geodetic normal.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Cartesian3 instance if none was provided.

#### scaleToGeocentricSurface(cartesian, result) → Cartesian3

Scales the provided Cartesian position along the geocentric surface normal so that it is on the surface of this ellipsoid.
Name Type Description
`cartesian` Cartesian3 The Cartesian position to scale.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter or a new Cartesian3 instance if none was provided.

#### scaleToGeodeticSurface(cartesian, result) → Cartesian3

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.
Name Type Description
`cartesian` Cartesian3 The Cartesian position to scale.
`result` Cartesian3 optional The object onto which to store the result.
##### Returns:
The modified result parameter, a new Cartesian3 instance if none was provided, or undefined if the position is at the center.

#### transformPositionFromScaledSpace(position, result) → Cartesian3

Transforms a Cartesian X, Y, Z position from the ellipsoid-scaled space by multiplying its components by the result of `Ellipsoid#radii`.
Name Type Description
`position` Cartesian3 The position to transform.
`result` Cartesian3 optional The position to which to copy the result, or undefined to create and return a new instance.
##### Returns:
The position expressed in the unscaled space. The returned instance is the one passed as the result parameter if it is not undefined, or a new instance of it is.

#### transformPositionToScaledSpace(position, result) → Cartesian3

Transforms a Cartesian X, Y, Z position to the ellipsoid-scaled space by multiplying its components by the result of `Ellipsoid#oneOverRadii`.
Name Type Description
`position` Cartesian3 The position to transform.
`result` Cartesian3 optional The position to which to copy the result, or undefined to create and return a new instance.
##### 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.