agi.foundation.geometry.shapes
(agi.foundation.core-2018r4.jar)

Class Ellipsoid

• All Implemented Interfaces:
IEquatableDefinition

```public class Ellipsoid
extends Object
implements IEquatableDefinition```
A quadratic surface defined in Cartesian coordinates by the equation:
``````
(x / a)^2 + (y / b)^2 + (z / c)^2 = 1
``````
• Constructor Summary

Constructors
Constructor and Description
`Ellipsoid()`
Initializes an ellipsoid as a unit sphere.
`Ellipsoid(Cartesian semiaxisLengths)`
Initializes an ellipsoid as a scalene ellipsoid.
```Ellipsoid(Cartesian semiaxisLengths, double centerTolerance, double surfaceTolerance)```
Initializes an ellipsoid as a scalene ellipsoid.
`Ellipsoid(double radius)`
Initializes an ellipsoid as a sphere.
```Ellipsoid(double centerTolerance, double surfaceTolerance)```
Initializes an ellipsoid as a unit sphere.
```Ellipsoid(double equatorialRadius, double polarRadius, AxisIndicator polarAxis)```
Initializes an ellipsoid as a spheroid.
```Ellipsoid(double equatorialRadius, double polarRadius, AxisIndicator polarAxis, double centerTolerance, double surfaceTolerance)```
Initializes an ellipsoid as a spheroid.
```Ellipsoid(double x, double y, double z)```
Initializes an ellipsoid as a scalene ellipsoid.
```Ellipsoid(double x, double y, double z, double centerTolerance, double surfaceTolerance)```
Initializes an ellipsoid as a scalene ellipsoid.
• Method Summary

All Methods
Modifier and Type Method and Description
`double[]` `apparentAngularSize(Cartesian point)`
Provides the minimum and maximum apparent angular size of the ellipsoid, as viewed from the provided point.
`Cartographic` `cartesianToCartographic(Cartesian position)`
Converts the motion given in terms of cartesian coordinates to motion in cartographic coordinates.
`Motion1<Cartographic>` ```cartesianToCartographic(Motion1<Cartesian> cartesianMotion, int order)```
Converts the motion given in terms of cartesian coordinates to motion in cartographic coordinates.
`Cartesian` `cartographicToCartesian(Cartographic position)`
Converts the motion given in terms of planetodetic cartographic coordinates to motion in cartesian coordinates.
`Cartesian` ```cartographicToCartesian(double longitude, double latitude)```
Converts the specified planetodetic surface location into a cartesian vector in the fixed frame of the ellipsoid.
`Motion1<Cartesian>` ```cartographicToCartesian(Motion1<Cartographic> cartographicMotion, int order)```
Converts the motion given in terms of planetodetic cartographic coordinates to motion in cartesian coordinates.
`UniversalPolarStereographic` `cartographicToUniversalPolarStereographic(Cartographic coordinates)`
Converts the location given in terms of planetodetic cartographic coordinates to Universal Polar Stereographic (UPS) coordinates.
`UniversalPolarStereographic` ```cartographicToUniversalPolarStereographic(double longitude, double latitude)```
Converts the location given in terms of planetodetic longitude and latitude to Universal Polar Stereographic (UPS) coordinates.
`UniversalTransverseMercator` `cartographicToUniversalTransverseMercator(Cartographic coordinates)`
Converts the location given in terms of planetodetic cartographic coordinates to Universal Transverse Mercator (UTM) coordinates.
`UniversalTransverseMercator` ```cartographicToUniversalTransverseMercator(double longitude, double latitude)```
Converts the location given in terms of planetodetic longitude and latitude to Universal Transverse Mercator (UTM) coordinates.
`double` `computeApproximateHeight(Cartesian position)`
Compute an approximate value of the height above the surface.
`double` `computeSurfaceArea(CartographicExtent extent)`
Computes an approximation of the surface area of a given cartographic extent on the surface of this ellipsoid using Gauss Legendre 10th order quadrature.
`double` ```computeSurfaceArea(double minLongitude, double minLatitude, double maxLongitude, double maxLatitude)```
Computes an approximation of the surface area of a given section of the surface of an ellipsoid using Gauss Legendre 10th order quadrature.
`UnitQuaternion` `eastNorthUpTransformation(Cartesian surfacePosition)`
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic east-north-up axes at the given position on the surface.
`double` ```ellipsoidSeparationDistance(Ellipsoid other, Cartesian centerPointsDisplacement, Matrix3By3 thisToOtherRotation)```
If the given `Ellipsoid` does not intersect with this ellipsoid this method returns the minimum separation between the surfaces of the two ellipsoids.
`double` ```ellipsoidSeparationDistance(Ellipsoid other, Cartesian centerPointsDisplacement, Matrix3By3 thisToOtherRotation, Cartesian[] pointOnThisSurface, Cartesian[] pointOnOtherSurface)```
If the given `Ellipsoid` does not intersect with this ellipsoid this method returns the minimum separation between the surfaces of the two ellipsoids.
`double` `getCenterTolerance()`
Gets the numerical tolerance used to determine if a point is located near the center of the ellipsoid.
`int` `getDefinitionHashCode()`
Gets a hash code representing the definition of this object.
`double` ```getDegreeOfObstruction(Cartesian thisFixed, Cartesian otherFixed)```
Gets the obstruction value given two positions.
`double` ```getDegreeOfObstruction(Cartesian thisFixed, Cartesian otherFixed, double[] nearDistance)```
Gets the obstruction value given two positions.
`EllipsoidType` `getEllipsoidType()`
Gets the type of the ellipsoid based on the semiaxis lengths.
`Cartesian` `getSemiaxisLengths()`
Gets the semiaxis lengths.
`double` `getSemimajorAxisLength()`
Gets the largest semiaxis length.
`double` `getSemiminorAxisLength()`
Gets the smallest semiaxis length.
`double` `getSurfaceTolerance()`
Gets the numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
`double` `getVolume()`
Gets the volume of the ellipsoid.
`Cartesian` `gradient(Cartesian position)`
The gradient of the ellipsoid evaluated at the provided position.
`double` ```grazingAltitude(Cartographic initial, Cartographic _final)```
Provides the point on the line segment between the initial and final points which is nearest to the ellipsoid.
`double` ```grazingAltitude(Cartographic location, UnitCartesian direction)```
Provides the nearest distance between the ellipsoid and the line segment from the provided location and along the indicated direction.
`Cartographic` ```grazingAltitudeLocation(Cartographic initial, Cartographic _final)```
Provides the nearest distance between the ellipsoid and the line segment between the initial and final points.
`Cartographic` ```grazingAltitudeLocation(Cartographic location, UnitCartesian direction)```
Provides the point on the line segment from the provided location and along the indicated direction which is nearest to the ellipsoid.
`Cartesian[]` ```grazingAngleLocations(Cartesian point, UnitCartesian direction)```
Provides the two points on the limb of the ellipsoid with the smallest and largest apparent angular separation with respect to the indicated direction, as viewed from the provided point.
`double[]` ```grazingAngles(Cartesian point, UnitCartesian direction)```
Provides the angles from the indicated direction to the two points on the limb of the ellipsoid with the smallest and largest apparent angular separation, as viewed from the provided point.
`double[]` ```intersections(Cartesian position, UnitCartesian direction)```
Computes the intersection of the line of sight vector emanating from a given external point with the ellipsoid.
`boolean` `isAtCenter(Cartesian position)`
Gets a value indicating if the provided position is within the `CenterTolerance` (`get`) of the center of the ellipsoid.
`boolean` `isAtOrBeneathSurface(Cartesian position)`
Gets a value indicating if the provided position is within the `SurfaceTolerance` (`get`) of the surface of the ellipsoid, or is beneath the surface of the ellipsoid.
`boolean` `isAtSurface(Cartesian position)`
Gets a value indicating if the provided position is within the `SurfaceTolerance` (`get`) of the surface of the ellipsoid.
`boolean` `isSameDefinition(Ellipsoid other)`
Determines if this object has the same definition as another object.
`boolean` `isSameDefinition(Object other)`
Determines if this object has the same definition as another object.
`double` `norm(Cartesian position)`
The ellipsoid norm evaluated at the provided position.
`double` `normSquared(Cartesian position)`
The square of the ellipsoid `Ellipsoid.norm(agi.foundation.coordinates.Cartesian)` evaluated at the provided position.
`UnitQuaternion` `northEastDownTransformation(Cartesian surfacePosition)`
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic north-east-down axes at the given position on the surface.
`double` `pointSeparationDistance(Cartesian centerToPoint)`
If the given `Cartesian` does not lie within this ellipsoid this method returns the minimum separation between the this ellipsoid on the given point.
`double` ```pointSeparationDistance(Cartesian centerToPoint, Cartesian[] pointOnSurface)```
If the given `Cartesian` does not lie within this ellipsoid this method returns the minimum separation between the this ellipsoid on the given point.
`Cartesian` `radialProjection(Cartesian position)`
Computes the radial projection of the position vector onto the surface of the ellipsoid.
`double` ```surfaceDistance(Cartographic first, Cartographic second)```
Computes the shortest distance as measured on the surface of the ellipsoid between two planetodetic cartographic positions.
`static UnitCartesian` `surfaceNormal(Cartographic position)`
The unit Cartesian vector directed along the surface normal at the provided cartographic position.
`static UnitCartesian` ```surfaceNormal(double longitude, double latitude)```
The unit Cartesian vector directed along the surface normal at the provided cartographic longitude and latitude.
`UnitCartesian` `surfaceNormalMotion(Cartesian surfacePosition)`
Converts the position given in terms of a surface point to the surface normal vector.
`Motion2<UnitCartesian,Cartesian>` ```surfaceNormalMotion(Motion1<Cartesian> surfaceMotion, int order)```
Converts the motion given in terms of a surface point to motion of the surface normal vector.
`Cartographic` ```surfacePosition(Cartographic initial, double heading, double distance)```
Computes the location of a second surface point along the geodesic passing through the provided surface point having the indicated heading at the provided surface point and located at the specified distance from the provided surface point.
`Cartesian` `surfaceProjection(Cartesian position)`
Computes the projection of the cartesian position onto the ellipsoid surface.
`Cartesian` `surfaceProjection(Cartographic position)`
Computes the projection of the cartographic position onto the ellipsoid surface.
`Motion1<Cartesian>` ```surfaceProjection(Motion1<Cartesian> motion, int order)```
Computes the projection of the cartesian motion onto the ellipsoid surface.
`Motion1<Cartesian>` ```surfaceProjectionCartographic(Motion1<Cartographic> cartographicMotion, int order)```
Computes the projection of the cartographic motion onto the ellipsoid surface.
`Cartesian[]` ```tangents(Cartesian position, UnitCartesian normal)```
From the indicated position, provides the points of tangency on an ellipsoid which also lie in the plane defined by the indicated normal.
`Cartesian[]` ```tangents(Cartesian position, UnitCartesian axis, double halfAngle)```
From the indicated position, provides the points of tangency on an ellipsoid which also lie on an axisymmetric cone defined by the indicated axis and half angle.
`boolean` ```tangentTotal(Cartesian sensorPosition, UnitCartesian sensorHeading, double halfAngle)```
Determines whether the cone emanating from sensor at the given position and with the given heading and half angle lies completely tangent to the Ellipsoid.
`Cartographic` ```universalPolarStereographicToCartographic(PoleIndicator hemisphere, double easting, double northing)```
Converts the location given in terms of Universal Polar Stereographic (UPS) hemisphere, easting, and northing to planetodetic cartographic coordinates.
`Cartographic` `universalPolarStereographicToCartographic(UniversalPolarStereographic coordinates)`
Converts the location given in terms of Universal Polar Stereographic (UPS) coordinates to planetodetic cartographic coordinates.
`Cartographic` ```universalTransverseMercatorToCartographic(int zone, PoleIndicator hemisphere, double easting, double northing)```
Converts the location given in terms of Universal Transverse Mercator (UTM) zone, hemisphere, easting, and northing to planetodetic cartographic coordinates.
`Cartographic` `universalTransverseMercatorToCartographic(UniversalTransverseMercator coordinates)`
Converts the location given in terms of Universal Transverse Mercator (UTM) coordinates to planetodetic cartographic coordinates.
`UnitQuaternion` `upEastNorthTransformation(Cartesian surfacePosition)`
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic up-east-north axes at the given position on the surface.
• Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
• Constructor Detail

• Ellipsoid

```public Ellipsoid(double centerTolerance,
double surfaceTolerance)```
Initializes an ellipsoid as a unit sphere.
Parameters:
`centerTolerance` - The numerical tolerance used to determine if a point is located at the center of the ellipsoid.
`surfaceTolerance` - The numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameters `centerTolerance` or `surfaceTolerance` are less than or equal to 0.
• Ellipsoid

`public Ellipsoid()`
Initializes an ellipsoid as a unit sphere.
• Ellipsoid

```public Ellipsoid(double x,
double y,
double z,
double centerTolerance,
double surfaceTolerance)```
Initializes an ellipsoid as a scalene ellipsoid.
Parameters:
`x` - The semiaxis length along the x-axis of the ellipsoid.
`y` - The semiaxis length along the y-axis of the ellipsoid.
`z` - The semiaxis length along the z-axis of the ellipsoid.
`centerTolerance` - The numerical tolerance used to determine if a point is located at the center of the ellipsoid.
`surfaceTolerance` - The numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameters `x`, `y`, or `z` are less than or equal to 0.
`ArgumentOutOfRangeException` - Thrown when the parameters `centerTolerance` or `surfaceTolerance` are less than or equal to 0.
• Ellipsoid

```public Ellipsoid(double x,
double y,
double z)```
Initializes an ellipsoid as a scalene ellipsoid.
Parameters:
`x` - The semiaxis length along the x-axis of the ellipsoid.
`y` - The semiaxis length along the y-axis of the ellipsoid.
`z` - The semiaxis length along the z-axis of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameters `x`, `y`, or `z` are less than or equal to 0.
• Ellipsoid

```public Ellipsoid(@Nonnull
Cartesian semiaxisLengths,
double centerTolerance,
double surfaceTolerance)```
Initializes an ellipsoid as a scalene ellipsoid.
Parameters:
`semiaxisLengths` - The semiaxis lengths along the x, y, and z axes of the ellipsoid.
`centerTolerance` - The numerical tolerance used to determine if a point is located at the center of the ellipsoid.
`surfaceTolerance` - The numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameter `semiaxisLengths` has an `X` (`get`), `Y` (`get`), or `Z` (`get`) component that is less than or equal to 0.
`ArgumentOutOfRangeException` - Thrown when the parameters `centerTolerance` or `surfaceTolerance` are less than or equal to 0.
• Ellipsoid

```public Ellipsoid(@Nonnull
Cartesian semiaxisLengths)```
Initializes an ellipsoid as a scalene ellipsoid.
Parameters:
`semiaxisLengths` - The semiaxis lengths along the x, y, and z axes of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameter `semiaxisLengths` has an `X` (`get`), `Y` (`get`), or `Z` (`get`) component that is less than or equal to 0.
• Ellipsoid

```public Ellipsoid(double equatorialRadius,
@Nonnull
AxisIndicator polarAxis,
double centerTolerance,
double surfaceTolerance)```
Initializes an ellipsoid as a spheroid.

If the equatorial radius is larger than the polar radius, the ellipsoid is an oblate spheroid. If the equatorial radius is smaller than the polar radius, the ellipsoid is a prolate spheroid.

The conversions between cartesian and cartographic coordinates define longitude measured in the xy-plane. Therefore, the z-axis will, in general, be indicated as the polar axis.

Parameters:
`equatorialRadius` - The lengths of the two equal semiaxis.
`polarRadius` - The length of the semiaxis which is unequal to the rest.
`polarAxis` - The axis which corresponds to the semiaxis which is unequal to the rest.
`centerTolerance` - The numerical tolerance used to determine if a point is located at the center of the ellipsoid.
`surfaceTolerance` - The numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameters `equatorialRadius` or `polarRadius` are less than or equal to 0.
`ArgumentOutOfRangeException` - Thrown when the parameters `centerTolerance` or `surfaceTolerance` are less than or equal to 0.
• Ellipsoid

```public Ellipsoid(double equatorialRadius,
@Nonnull
AxisIndicator polarAxis)```
Initializes an ellipsoid as a spheroid.

If the equatorial radius is larger than the polar radius, the ellipsoid is an oblate spheroid. If the equatorial radius is smaller than the polar radius, the ellipsoid is a prolate spheroid.

The conversions between cartesian and cartographic coordinates define longitude measured in the xy-plane. Therefore, the z-axis will, in general, be indicated as the polar axis.

Parameters:
`equatorialRadius` - The lengths of the two equal semiaxis.
`polarRadius` - The length of the semiaxis which is unequal to the rest.
`polarAxis` - The axis which corresponds to the semiaxis which is unequal to the rest.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameters `equatorialRadius` or `polarRadius` are less than or equal to 0.
• Ellipsoid

`public Ellipsoid(double radius)`
Initializes an ellipsoid as a sphere.
Parameters:
`radius` - The radius of the sphere.
Throws:
`ArgumentOutOfRangeException` - Thrown when the parameter `radius` is less than or equal to 0.
• Method Detail

• isSameDefinition

`public final boolean isSameDefinition(Ellipsoid other)`
Determines if this object has the same definition as another object.

This method is very similar to `Object.equals(Object)` except that it explicitly considers the "definitions" of the two objects for objects that do not typically act like values. The definition of an object typically includes all of the fields of the object.

Parameters:
`other` - The other instance to compare to this one.
Returns:
`true` if this object has the same definition as the specified one. `false` if the other object is `null`, a different type than this one, or if this object and the specified one have different definitions.
• isSameDefinition

`public final boolean isSameDefinition(Object other)`
Determines if this object has the same definition as another object.

This method is very similar to `Object.equals(Object)` except that it explicitly considers the "definitions" of the two objects for objects that do not typically act like values. The definition of an object typically includes all of the fields of the object.

Specified by:
`isSameDefinition` in interface `IEquatableDefinition`
Parameters:
`other` - The other instance to compare to this one.
Returns:
`true` if this object has the same definition as the specified one. `false` if the other object is `null`, a different type than this one, or if this object and the specified one have different definitions.
• getDefinitionHashCode

`public final int getDefinitionHashCode()`
Gets a hash code representing the definition of this object.

This method is very similar to `Object.hashCode()` except that it explicitly includes the "definition" of the object even if the object does not typically act like a value. The definition of an object typically includes all of the fields of the object. The value returned by this method should NOT change. This means that two objects for which `Ellipsoid.isSameDefinition(agi.foundation.geometry.shapes.Ellipsoid)` returns `true` will not necessarily have the same hash code if one or the other was changed after the hash code was first obtained.

Specified by:
`getDefinitionHashCode` in interface `IEquatableDefinition`
Returns:
The hash code.
• getSemiaxisLengths

```@Nonnull
public final Cartesian getSemiaxisLengths()```
Gets the semiaxis lengths.
• getEllipsoidType

```@Nonnull
public final EllipsoidType getEllipsoidType()```
Gets the type of the ellipsoid based on the semiaxis lengths.
`EllipsoidType`
• getCenterTolerance

`public final double getCenterTolerance()`
Gets the numerical tolerance used to determine if a point is located near the center of the ellipsoid. The value is expressed as a percentage with respect to the unit sphere representing the scaled ellipsoid. By default, the value is approximately 30%.
• isAtCenter

```public final boolean isAtCenter(@Nonnull
Cartesian position)```
Gets a value indicating if the provided position is within the `CenterTolerance` (`get`) of the center of the ellipsoid. The `CenterTolerance` (`get`) is expressed as a percentage with respect to the unit sphere representing the scaled ellipsoid.
Parameters:
`position` - The position.
Returns:
Returns `true` if the position is within tolerance of the center of the ellipsoid. Otherwise, returns `false`.
• getSurfaceTolerance

`public final double getSurfaceTolerance()`
Gets the numerical tolerance used to determine if a point is located on the surface of the ellipsoid.
• isAtSurface

```public final boolean isAtSurface(@Nonnull
Cartesian position)```
Gets a value indicating if the provided position is within the `SurfaceTolerance` (`get`) of the surface of the ellipsoid.
Parameters:
`position` - The position.
Returns:
Returns `true` if the position is within tolerance of the surface of the ellipsoid. Otherwise, returns `false`.
• isAtOrBeneathSurface

```public final boolean isAtOrBeneathSurface(@Nonnull
Cartesian position)```
Gets a value indicating if the provided position is within the `SurfaceTolerance` (`get`) of the surface of the ellipsoid, or is beneath the surface of the ellipsoid.
Parameters:
`position` - The position.
Returns:
Returns `true` if the position is within tolerance of the surface of the ellipsoid, or beneath it. Otherwise, returns `false`.
• getSemimajorAxisLength

`public final double getSemimajorAxisLength()`
Gets the largest semiaxis length.
• getSemiminorAxisLength

`public final double getSemiminorAxisLength()`
Gets the smallest semiaxis length.
• getVolume

`public final double getVolume()`
Gets the volume of the ellipsoid.
• norm

```public final double norm(@Nonnull
Cartesian position)```
The ellipsoid norm evaluated at the provided position.
Parameters:
`position` - The position.
Returns:
The norm.

```@Nonnull
Cartesian position)```
The gradient of the ellipsoid evaluated at the provided position.
Parameters:
`position` - The position.
Returns:
• tangents

```public final Cartesian[] tangents(@Nonnull
Cartesian position,
@Nonnull
UnitCartesian normal)```
From the indicated position, provides the points of tangency on an ellipsoid which also lie in the plane defined by the indicated normal.
Parameters:
`position` - The reference point.
`normal` - The normal to the plane passing through the reference point.
Returns:
The points of tangency on the ellipsoid.
• tangents

```public final Cartesian[] tangents(@Nonnull
Cartesian position,
@Nonnull
UnitCartesian axis,
double halfAngle)```
From the indicated position, provides the points of tangency on an ellipsoid which also lie on an axisymmetric cone defined by the indicated axis and half angle.
Parameters:
`position` - The reference point.
`axis` - The axis of the cone.
`halfAngle` - The half angle of the cone.
Returns:
The points of tangency on the ellipsoid.
• tangentTotal

```public final boolean tangentTotal(@Nonnull
Cartesian sensorPosition,
@Nonnull
double halfAngle)```
Determines whether the cone emanating from sensor at the given position and with the given heading and half angle lies completely tangent to the Ellipsoid.
Parameters:
`sensorPosition` - The position of the sensor.
`sensorHeading` - The heading of the sensor.
`halfAngle` - The half angle of the sensor cone.
Returns:
True if the sensor cone is tangent, false if it is not.
• grazingAltitudeLocation

```@Nonnull
public final Cartographic grazingAltitudeLocation(@Nonnull
Cartographic initial,
@Nonnull
Cartographic _final)```
Provides the nearest distance between the ellipsoid and the line segment between the initial and final points. The line segment is considered to be finite in length. This means that possibly closer points which are not between the initial and final points are not reported.
Parameters:
`initial` - The initial planetodetic point of the line segment.
`_final` - The final planetodetic point of the line segment.
Returns:
The nearest planetodetic point on the line segment.
• grazingAltitude

```public final double grazingAltitude(@Nonnull
Cartographic initial,
@Nonnull
Cartographic _final)```
Provides the point on the line segment between the initial and final points which is nearest to the ellipsoid. The line segment is considered to be finite in length. This means that possibly closer points which are not between the initial and final points are not reported.
Parameters:
`initial` - The initial planetodetic point of the line segment.
`_final` - The final planetodetic point of the line segment.
Returns:
The nearest distance.
• grazingAltitudeLocation

```@Nonnull
public final Cartographic grazingAltitudeLocation(@Nonnull
Cartographic location,
@Nonnull
UnitCartesian direction)```
Provides the point on the line segment from the provided location and along the indicated direction which is nearest to the ellipsoid. The line segment is considered to be infinite in length but starting at the provided location. This means that possibly closer points in the opposite direction are not reported.
Parameters:
`location` - The planetodetic position exterior to the ellipsoid.
`direction` - The reference direction.
Returns:
The nearest planetodetic point on the line segment.
• grazingAltitude

```public final double grazingAltitude(@Nonnull
Cartographic location,
@Nonnull
UnitCartesian direction)```
Provides the nearest distance between the ellipsoid and the line segment from the provided location and along the indicated direction. The line segment is considered to be infinite in length but starting at the provided location. This means that possibly smaller grazing altitudes along the opposite direction are not reported.
Parameters:
`location` - The planetodetic position exterior to the ellipsoid.
`direction` - The reference direction.
Returns:
The nearest distance.
• grazingAngleLocations

```public final Cartesian[] grazingAngleLocations(@Nonnull
Cartesian point,
@Nonnull
UnitCartesian direction)```
Provides the two points on the limb of the ellipsoid with the smallest and largest apparent angular separation with respect to the indicated direction, as viewed from the provided point. The point must be exterior to the ellipsoid.
Parameters:
`point` - The position exterior to the ellipsoid.
`direction` - The reference direction.
Returns:
The locations of the two points on the ellipsoid with the smallest and largest apparent angular separation, respectively.
`Ellipsoid.grazingAngles(agi.foundation.coordinates.Cartesian, agi.foundation.coordinates.UnitCartesian)`
• grazingAngles

```public final double[] grazingAngles(@Nonnull
Cartesian point,
@Nonnull
UnitCartesian direction)```
Provides the angles from the indicated direction to the two points on the limb of the ellipsoid with the smallest and largest apparent angular separation, as viewed from the provided point. The point must be exterior to the ellipsoid.
Parameters:
`point` - The position exterior to the ellipsoid.
`direction` - The reference direction.
Returns:
The smallest and largest apparent angular separation, respectively.
`Ellipsoid.grazingAngleLocations(agi.foundation.coordinates.Cartesian, agi.foundation.coordinates.UnitCartesian)`
• intersections

```public final double[] intersections(@Nonnull
Cartesian position,
@Nonnull
UnitCartesian direction)```
Computes the intersection of the line of sight vector emanating from a given external point with the ellipsoid.

The length of the array of distances indicates how many points of intersection exist:

• A length of zero indicates that there are no intersections.
• A length of one indicates the case of a degenerate ellipse.
• A length of two indicates two points of intersection.
In the case of two intersections, the distances are ordered from most negative (i.e. "furthest behind") to most positive (i.e. "furthest before"). If the two distances are equal, the points of intersection indicate a single point of tangency to the ellipsoid.
Parameters:
`position` - The reference point for the direction.
`direction` - The direction along which the intersections are to be determined.
Returns:
If intersections exist, the distances along the direction to the points of intersection.

```@Nonnull
Cartesian position)```
Computes the radial projection of the position vector onto the surface of the ellipsoid.

The projection is onto the side of the ellipsoid surface closest to the provided point.

Parameters:
`position` - The position vector.
Returns:
The Cartesian position of the surface point.
• surfaceProjection

```@Nonnull
public final Cartesian surfaceProjection(@Nonnull
Cartesian position)```
Computes the projection of the cartesian position onto the ellipsoid surface.
Parameters:
`position` - The cartesian position.
Returns:
The cartesian position of the surface projection.
Throws:
`ArgumentException` - Thrown when the `position` parameter is near the center of the ellipsoid. Use the `Ellipsoid.isAtCenter(agi.foundation.coordinates.Cartesian)` member to test any such points if they will exist in the domain of the calling function.
• surfaceProjection

```@Nonnull
public final Motion1<Cartesian> surfaceProjection(@Nonnull
Motion1<Cartesian> motion,
int order)```
Computes the projection of the cartesian motion onto the ellipsoid surface.
Parameters:
`motion` - The cartesian motion.
`order` - The order of the highest derivative to project. To project just the position, pass 0 for this value. To project velocity as well, pass 1.
Returns:
The cartesian motion of the surface projection.
Throws:
`ArgumentException` - Thrown when the `Value` (`get`) is near the center of the ellipsoid. Use the `Ellipsoid.isAtCenter(agi.foundation.coordinates.Cartesian)` member to test any such points if they will exist in the domain of the calling function.
• surfaceProjection

```@Nonnull
public final Cartesian surfaceProjection(@Nonnull
Cartographic position)```
Computes the projection of the cartographic position onto the ellipsoid surface.
Parameters:
`position` - The planetodetic cartographic position.
Returns:
The cartesian motion of the surface projection.
• surfaceProjectionCartographic

```@Nonnull
public final Motion1<Cartesian> surfaceProjectionCartographic(@Nonnull
Motion1<Cartographic> cartographicMotion,
int order)```
Computes the projection of the cartographic motion onto the ellipsoid surface.
Parameters:
`cartographicMotion` - The planetodetic cartographic motion.
`order` - The order of the highest derivative to project. To project just the position, pass 0 for this value. To convert velocity as well, pass 1.
Returns:
The cartesian motion of the surface projection.
• cartographicToUniversalTransverseMercator

```@Nonnull
public final UniversalTransverseMercator cartographicToUniversalTransverseMercator(double longitude,
double latitude)```
Converts the location given in terms of planetodetic longitude and latitude to Universal Transverse Mercator (UTM) coordinates.

The planetodetic coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`longitude` - The planetodetic longitude in radians.
`latitude` - The planetodetic latitude in radians.
Returns:
The UTM equivalent of the specified planetodetic coordinates.
• cartographicToUniversalTransverseMercator

```@Nonnull
public final UniversalTransverseMercator cartographicToUniversalTransverseMercator(@Nonnull
Cartographic coordinates)```
Converts the location given in terms of planetodetic cartographic coordinates to Universal Transverse Mercator (UTM) coordinates.

The planetodetic cartographic coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`coordinates` - The planetodetic cartographic coordinates to convert.
Returns:
The UTM equivalent of the specified planetodetic cartographic coordinates.
• universalTransverseMercatorToCartographic

```@Nonnull
public final Cartographic universalTransverseMercatorToCartographic(int zone,
@Nonnull
PoleIndicator hemisphere,
double easting,
double northing)```
Converts the location given in terms of Universal Transverse Mercator (UTM) zone, hemisphere, easting, and northing to planetodetic cartographic coordinates.
Parameters:
`zone` - The longitude zone indicator.
`hemisphere` - The hemisphere indicator.
`easting` - The eastward distance of the location into the zone.
`northing` - The northward distance of the location into the zone.
Returns:
The planetodetic cartographic equivalent of the specified UTM coordinates.
• universalTransverseMercatorToCartographic

```@Nonnull
public final Cartographic universalTransverseMercatorToCartographic(@Nonnull
UniversalTransverseMercator coordinates)```
Converts the location given in terms of Universal Transverse Mercator (UTM) coordinates to planetodetic cartographic coordinates.
Parameters:
`coordinates` - The UTM coordinates to convert.
Returns:
The planetodetic cartographic equivalent of the specified UTM coordinates.
• cartographicToUniversalPolarStereographic

```@Nonnull
public final UniversalPolarStereographic cartographicToUniversalPolarStereographic(double longitude,
double latitude)```
Converts the location given in terms of planetodetic longitude and latitude to Universal Polar Stereographic (UPS) coordinates.

The planetodetic coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`longitude` - The planetodetic longitude in radians.
`latitude` - The planetodetic latitude in radians.
Returns:
The UPS equivalent of the specified planetodetic coordinates.
• cartographicToUniversalPolarStereographic

```@Nonnull
public final UniversalPolarStereographic cartographicToUniversalPolarStereographic(@Nonnull
Cartographic coordinates)```
Converts the location given in terms of planetodetic cartographic coordinates to Universal Polar Stereographic (UPS) coordinates.

The planetodetic cartographic coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`coordinates` - The planetodetic cartographic coordinates to convert.
Returns:
The UPS equivalent of the specified planetodetic cartographic coordinates.
• universalPolarStereographicToCartographic

```@Nonnull
public final Cartographic universalPolarStereographicToCartographic(@Nonnull
PoleIndicator hemisphere,
double easting,
double northing)```
Converts the location given in terms of Universal Polar Stereographic (UPS) hemisphere, easting, and northing to planetodetic cartographic coordinates.
Parameters:
`hemisphere` - The hemisphere indicator.
`easting` - The eastward distance of the location into the zone.
`northing` - The northward distance of the location into the zone.
Returns:
The planetodetic cartographic equivalent of the specified UPS coordinates.
• universalPolarStereographicToCartographic

```@Nonnull
public final Cartographic universalPolarStereographicToCartographic(@Nonnull
UniversalPolarStereographic coordinates)```
Converts the location given in terms of Universal Polar Stereographic (UPS) coordinates to planetodetic cartographic coordinates.
Parameters:
`coordinates` - The UPS coordinates to convert.
Returns:
The planetodetic cartographic equivalent of the specified UPS coordinates.
• cartographicToCartesian

```@Nonnull
public final Cartesian cartographicToCartesian(@Nonnull
Cartographic position)```
Converts the motion given in terms of planetodetic cartographic coordinates to motion in cartesian coordinates.

The planetodetic cartographic coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`position` - The planetodetic cartographic coordinates to convert.
Returns:
The cartesian equivalent of the specified cartographic coordinates.
• cartographicToCartesian

```@Nonnull
public final Motion1<Cartesian> cartographicToCartesian(@Nonnull
Motion1<Cartographic> cartographicMotion,
int order)```
Converts the motion given in terms of planetodetic cartographic coordinates to motion in cartesian coordinates.

The cartographic position and velocity must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`cartographicMotion` - The planetodetic cartographic motion to convert.
`order` - The order of the highest derivative to convert. To convert just the position, pass 0 for this value. To convert velocity as well, pass 1.
Returns:
The cartesian equivalent of the specified cartographic motion.
• cartographicToCartesian

```@Nonnull
public final Cartesian cartographicToCartesian(double longitude,
double latitude)```
Converts the specified planetodetic surface location into a cartesian vector in the fixed frame of the ellipsoid.
Parameters:
`longitude` - The planetodetic longitude, in radians.
`latitude` - The planetodetic latitude, in radians.
Returns:
The fixed surface position at the given planetodetic location.
• cartesianToCartographic

```@Nonnull
public final Cartographic cartesianToCartographic(@Nonnull
Cartesian position)```
Converts the motion given in terms of cartesian coordinates to motion in cartographic coordinates.

The cartesian coordinates must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`position` - The cartesian coordinates to convert.
Returns:
The cartographic equivalent of the specified cartesian coordinates.
Throws:
`ArgumentException` - Thrown when the `position` parameter is near the center of the ellipsoid. Use the `Ellipsoid.isAtCenter(agi.foundation.coordinates.Cartesian)` member to test any such points if they will exist in the domain of the calling function.
• cartesianToCartographic

```@Nonnull
public final Motion1<Cartographic> cartesianToCartographic(@Nonnull
Motion1<Cartesian> cartesianMotion,
int order)```
Converts the motion given in terms of cartesian coordinates to motion in cartographic coordinates.

The cartesian position and velocity must be in a fixed reference frame centered on the center of mass of this ellipsoid.

Parameters:
`cartesianMotion` - The cartesian motion to convert.
`order` - The order of the highest derivative to convert. To convert just the position, pass 0 for this value. To convert velocity as well, pass 1.
Returns:
The cartographic equivalent of the specified cartesian motion.
Throws:
`ArgumentException` - Thrown when the `Value` (`get`) is near the center of the ellipsoid. Use the `Ellipsoid.isAtCenter(agi.foundation.coordinates.Cartesian)` member to test any such points if they will exist in the domain of the calling function.
• surfaceNormal

```@Nonnull
public static UnitCartesian surfaceNormal(double longitude,
double latitude)```
The unit Cartesian vector directed along the surface normal at the provided cartographic longitude and latitude.
Parameters:
`longitude` - The longitude coordinate measured from the prime meridian about the z-axis.
`latitude` - The planetodetic latitude coordinate measured from the x-y plane to the surface normal.
Returns:
The motion of the normal.
• surfaceNormal

```@Nonnull
public static UnitCartesian surfaceNormal(@Nonnull
Cartographic position)```
The unit Cartesian vector directed along the surface normal at the provided cartographic position.
Parameters:
`position` - The cartographic (planetodetic) position.
Returns:
The motion of the normal.
• surfaceDistance

```public final double surfaceDistance(@Nonnull
Cartographic first,
@Nonnull
Cartographic second)```
Computes the shortest distance as measured on the surface of the ellipsoid between two planetodetic cartographic positions.

Since the distance is measured on the surface of the ellipsoid, the height coordinate information is ignored.

Parameters:
`first` - The initial planetodetic cartographic position.
`second` - The final planetodetic cartographic position.
Returns:
The surface distance.
Throws:
`UnsupportedCaseException` - The scalene case of a geodesic ellipsoid is not currently modeled and will be in a future release.
• surfacePosition

```@Nonnull
public final Cartographic surfacePosition(@Nonnull
Cartographic initial,
double distance)```
Computes the location of a second surface point along the geodesic passing through the provided surface point having the indicated heading at the provided surface point and located at the specified distance from the provided surface point.

Since the distance is measured on the surface of the ellipsoid, the height coordinate information is ignored.

Parameters:
`initial` - The initial planetodetic surface point.
`heading` - The initial heading.
`distance` - The surface distance separating the two surface points.
Returns:
The planetodetic location of the second surface coordinate.
Throws:
`UnsupportedCaseException` - The scalene case of a geodesic ellipsoid is not currently modeled and will be in a future release.
• surfaceNormalMotion

```@Nonnull
public final UnitCartesian surfaceNormalMotion(@Nonnull
Cartesian surfacePosition)```
Converts the position given in terms of a surface point to the surface normal vector.

The `surfacePosition` must be in a fixed reference frame centered on the center of mass of this ellipsoid and must be the motion of a surface point.

Parameters:
`surfacePosition` - The position of the surface point.
Returns:
The surface normal vector.
• surfaceNormalMotion

```@Nonnull
public final Motion2<UnitCartesian,Cartesian> surfaceNormalMotion(@Nonnull
Motion1<Cartesian> surfaceMotion,
int order)```
Converts the motion given in terms of a surface point to motion of the surface normal vector.

The `surfaceMotion` must be in a fixed reference frame centered on the center of mass of this ellipsoid and must be the motion of a surface point.

Parameters:
`surfaceMotion` - The motion of the surface point.
`order` - The order of the highest derivative to convert. To convert just the position, pass 0 for this value. To convert velocity as well, pass 1.
Returns:
The motion of the surface normal vector.
• northEastDownTransformation

```@Nonnull
public final UnitQuaternion northEastDownTransformation(@Nonnull
Cartesian surfacePosition)```
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic north-east-down axes at the given position on the surface.
Parameters:
`surfacePosition` - The position of interest on the surface of the ellipsoid.
Returns:
The transformation from x-y-z coordinates to north-east-down coordinates.
• upEastNorthTransformation

```@Nonnull
public final UnitQuaternion upEastNorthTransformation(@Nonnull
Cartesian surfacePosition)```
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic up-east-north axes at the given position on the surface.
Parameters:
`surfacePosition` - The position of interest on the surface of the ellipsoid.
Returns:
The transformation from x-y-z coordinates to up-east-north coordinates.
• eastNorthUpTransformation

```@Nonnull
public final UnitQuaternion eastNorthUpTransformation(@Nonnull
Cartesian surfacePosition)```
Returns the quaternion transformation between the x-y-z axes of the ellipsoid to the axes oriented to the cartographic east-north-up axes at the given position on the surface.
Parameters:
`surfacePosition` - The position of interest on the surface of the ellipsoid.
Returns:
The transformation from x-y-z coordinates to east-north-up coordinates.
• computeSurfaceArea

`public final double computeSurfaceArea(CartographicExtent extent)`
Computes an approximation of the surface area of a given cartographic extent on the surface of this ellipsoid using Gauss Legendre 10th order quadrature.
Parameters:
`extent` - The extent of the region to compute.
Returns:
The area of the extent.
• computeSurfaceArea

```public final double computeSurfaceArea(double minLongitude,
double minLatitude,
double maxLongitude,
double maxLatitude)```
Computes an approximation of the surface area of a given section of the surface of an ellipsoid using Gauss Legendre 10th order quadrature.
Parameters:
`minLongitude` - The west most longitude which bounds the region.
`minLatitude` - The south most longitude which bounds the region.
`maxLongitude` - The east most longitude which bounds the region.
`maxLatitude` - The north most longitude which bounds the region.
Returns:
The approximate area of the section on the surface of this ellipsoid.
• computeApproximateHeight

```public final double computeApproximateHeight(@Nonnull
Cartesian position)```
Compute an approximate value of the height above the surface.

In general, for Oblate Spheroids, this will be faster than calling `Ellipsoid.cartesianToCartographic(Cartesian)` while providing a height which is still extremely close to the true value.

Parameters:
`position` - The position in the fixed frame of the shape.
Returns:
The approximate height above the surface.
• ellipsoidSeparationDistance

```public final double ellipsoidSeparationDistance(Ellipsoid other,
@Nonnull
Cartesian centerPointsDisplacement,
@Nonnull
Matrix3By3 thisToOtherRotation)```
If the given `Ellipsoid` does not intersect with this ellipsoid this method returns the minimum separation between the surfaces of the two ellipsoids. If the ellipsoids do intersect, the resulting negative separation is the depth that the other ellipsoid intersects into this ellipsoid (calculated as the distance between the two points on the ellipsoid chosen in the same manner as in the non-intersecting case).
Parameters:
`other` - The method finds the separation from the calling ellipsoid and this parameter ellipsoid.
`centerPointsDisplacement` - The vector from the center of this ellipsoid to the center of the `other` ellipsoid, in the local frame of this ellipsoid.
`thisToOtherRotation` - The rotation matrix which represents the orientation of the `other` ellipsoid with respect to this one, corresponding to the result of `GetAxesTransformation` where this is the 'from' axes and the other axes is 'to'.
Returns:
The separation between the closest point of this ellipsoid and the closest point of the given ellipsoid.
• ellipsoidSeparationDistance

```public final double ellipsoidSeparationDistance(Ellipsoid other,
@Nonnull
Cartesian centerPointsDisplacement,
@Nonnull
Matrix3By3 thisToOtherRotation,
@Nonnull
Cartesian[] pointOnThisSurface,
@Nonnull
Cartesian[] pointOnOtherSurface)```
If the given `Ellipsoid` does not intersect with this ellipsoid this method returns the minimum separation between the surfaces of the two ellipsoids. If the ellipsoids do intersect, the resulting negative separation is the depth that the other ellipsoid intersects into this ellipsoid (calculated as the distance between the two points on the ellipsoid chosen in the same manner as in the non-intersecting case).
Parameters:
`other` - The method finds the separation from the calling ellipsoid and this parameter ellipsoid.
`centerPointsDisplacement` - The vector from the center of this ellipsoid to the center of the `other` ellipsoid, in the local frame of this ellipsoid.
`thisToOtherRotation` - The rotation matrix which represents the orientation of the `other` ellipsoid with respect to this one, corresponding to the result of `GetAxesTransformation` where this is the 'from' axes and the other axes is 'to'.
`pointOnThisSurface` - The location on this ellipsoid's surface, in its body frame, which was determined to be the closest point to the other ellipsoid.
`pointOnOtherSurface` - The location on the other ellipsoid's surface, in its body frame, which was determined to be the closest point to the this ellipsoid.
Returns:
The separation between the closest point of this ellipsoid and the closest point of the given ellipsoid.
• pointSeparationDistance

```public final double pointSeparationDistance(@Nonnull
Cartesian centerToPoint)```
If the given `Cartesian` does not lie within this ellipsoid this method returns the minimum separation between the this ellipsoid on the given point. If the point is within the ellipsoid do intersect, the resulting negative separation is the depth that the point lies within this ellipsoid's surface.
Parameters:
`centerToPoint` - The vector from the center of this ellipsoid to the point, in the local frame of this ellipsoid.
Returns:
The minimum separation between the surface of this ellipsoid and the given point.
• pointSeparationDistance

```public final double pointSeparationDistance(@Nonnull
Cartesian centerToPoint,
@Nonnull
Cartesian[] pointOnSurface)```
If the given `Cartesian` does not lie within this ellipsoid this method returns the minimum separation between the this ellipsoid on the given point. If the point is within the ellipsoid do intersect, the resulting negative separation is the depth that the point lies within this ellipsoid's surface.
Parameters:
`centerToPoint` - The vector from the center of this ellipsoid to the point, in the local frame of this ellipsoid.
`pointOnSurface` - The location on this ellipsoid's surface, in its body frame, which was determined to be closest to the given point.
Returns:
The minimum separation between the surface of this ellipsoid and the given point.
• getDegreeOfObstruction

```public final double getDegreeOfObstruction(@Nonnull
Cartesian thisFixed,
@Nonnull
Cartesian otherFixed)```
Gets the obstruction value given two positions.
Parameters:
`thisFixed` - The first position in a reference frame fixed to the shape.
`otherFixed` - The second position in a reference frame fixed to the shape.
Returns:
The degree of obstruction. Values above zero indicate that the view is not obstructed. Values below zero indicate that it is obstructed. The magnitude of the value has no physical meaning, but it is a continuous function.
• getDegreeOfObstruction

```public final double getDegreeOfObstruction(@Nonnull
Cartesian thisFixed,
@Nonnull
Cartesian otherFixed,
@Nonnull
double[] nearDistance)```
Gets the obstruction value given two positions.
Parameters:
`thisFixed` - The first position in a reference frame fixed to the shape.
`otherFixed` - The second position in a reference frame fixed to the shape.
`nearDistance` - Outputs the distance along the relative vector at which that vector is closest to this `Ellipsoid`.
Returns:
The degree of obstruction. Values above zero indicate that the view is not obstructed. Values below zero indicate that it is obstructed. The magnitude of the value has no physical meaning, but it is a continuous function.