Ellipsoid - Cesium Documentation

# 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.

  ##### See:

  - Ellipsoid.fromCartesian3
  - Ellipsoid.WGS84
  - Ellipsoid.UNIT_SPHERE
  Source: Core/Ellipsoid.js, line 78

### Members

#### staticconstantEllipsoid.MOON :Ellipsoid

  An Ellipsoid instance initialized to a sphere with the lunar radius.
  Source: Core/Ellipsoid.js, line 240

#### staticEllipsoid.packedLength :Number

  The number of elements used to pack the object into an array.
  Source: Core/Ellipsoid.js, line 257

#### staticconstantEllipsoid.UNIT_SPHERE :Ellipsoid

  An Ellipsoid instance initialized to radii of (1.0, 1.0, 1.0).
  Source: Core/Ellipsoid.js, line 232

#### staticconstantEllipsoid.WGS84 :Ellipsoid

  An Ellipsoid instance initialized to the WGS84 standard.
  Source: Core/Ellipsoid.js, line 224

#### maximumRadius :Number

  Gets the maximum radius of the ellipsoid.
  Source: Core/Ellipsoid.js, line 157

#### minimumRadius :Number

  Gets the minimum radius of the ellipsoid.
  Source: Core/Ellipsoid.js, line 147

#### oneOverRadii :Cartesian3

  Gets one over the radii of the ellipsoid.
  Source: Core/Ellipsoid.js, line 127

#### oneOverRadiiSquared :Cartesian3

  Gets one over the squared radii of the ellipsoid.
  Source: Core/Ellipsoid.js, line 137

#### radii :Cartesian3

  Gets the radii of the ellipsoid.
  Source: Core/Ellipsoid.js, line 97

#### radiiSquared :Cartesian3

  Gets the squared radii of the ellipsoid.
  Source: Core/Ellipsoid.js, line 107

#### radiiToTheFourth :Cartesian3

  Gets the radii of the ellipsoid raise to the fourth power.
  Source: Core/Ellipsoid.js, line 117

### 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)
  Source: Core/Ellipsoid.js, line 172

#### staticEllipsoid.fromCartesian3(radii) → Ellipsoid

  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.

  ##### See:

  - Ellipsoid.WGS84
  - Ellipsoid.UNIT_SPHERE
  Source: Core/Ellipsoid.js, line 205

#### staticEllipsoid.pack(value, array, startingIndex)

  Stores the provided instance into the provided array.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `value` | Object |  | The value to pack.
  `array` | Array.<Number> |  | The array to pack into.
  `startingIndex` | Number | `0` | optional The index into the array at which to start packing the elements.

  Source: Core/Ellipsoid.js, line 267

#### staticEllipsoid.unpack(array, startingIndex, result)

  Retrieves an instance from a packed array.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `array` | Array.<Number> |  | The packed array.
  `startingIndex` | Number | `0` | optional The starting index of the element to be unpacked.
  `result` | Ellipsoid |  | optional The object into which to store the result.

  Source: Core/Ellipsoid.js, line 289

#### 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);

  Source: Core/Ellipsoid.js, line 477

#### 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);

  Source: Core/Ellipsoid.js, line 439

#### 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 positions = [new Cesium.Cartographic(Cesium.Math.toRadians(21), Cesium.Math.toRadians(78), 0),
                       new Cesium.Cartographic(Cesium.Math.toRadians(21.321), Cesium.Math.toRadians(78.123), 100),
                       new Cesium.Cartographic(Cesium.Math.toRadians(21.645), Cesium.Math.toRadians(78.456), 250)
      var cartesianPositions = Cesium.Ellipsoid.WGS84.cartographicArrayToCartesianArray(positions);

  Source: Core/Ellipsoid.js, line 403

#### 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 position = new Cesium.Cartographic(Cesium.Math.toRadians(21), Cesium.Math.toRadians(78), 5000);
      var cartesianPosition = Cesium.Ellipsoid.WGS84.cartographicToCartesian(position);

  Source: Core/Ellipsoid.js, line 373

#### 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.
  Source: Core/Ellipsoid.js, line 249

#### 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.
  Source: Core/Ellipsoid.js, line 677

#### 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.
  Source: Core/Ellipsoid.js, line 310

#### 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.
  Source: Core/Ellipsoid.js, line 350

#### 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.
  Source: Core/Ellipsoid.js, line 319

#### 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.
  Source: Core/Ellipsoid.js, line 611

#### 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.
  Source: Core/Ellipsoid.js, line 508

#### toString() → String

  Creates a string representing this Ellipsoid in the format '(radii.x, radii.y, radii.z)'.

  ##### Returns:

  A string representing this ellipsoid in the format '(radii.x, radii.y, radii.z)'.
  Source: Core/Ellipsoid.js, line 688

#### 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.
  Source: Core/Ellipsoid.js, line 662

#### 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.
  Source: Core/Ellipsoid.js, line 644