agi.foundation.geometry.shapes

(agi.foundation.core-2024r3.jar)

Class EllipsoidGeodesic

java.lang.Object

agi.foundation.geometry.shapes.EllipsoidSurfaceCurve

agi.foundation.geometry.shapes.EllipsoidGeodesic

All Implemented Interfaces:

IEquatable<EllipsoidSurfaceCurve>

public class EllipsoidGeodesic
extends EllipsoidSurfaceCurve

A minimum length path conforming to the surface of an ellipsoid and connecting two planetodetic surface points.

This class utilizes the direct and indirect formulations for defining geodesics on an ellipsoid, as discussed in "Geodesics on an ellipsoid of revolution.", C. F. Karney, 7 February 2011. The algorithms have been adapted from GeographicLib version 1.44 to optimize performance for the .NET and Java frameworks.

Constructor Summary

Constructors

Constructor and Description
EllipsoidGeodesic(Ellipsoid ellipsoid, Cartographic initial, Cartographic _final) Initializes a geodesic on the ellipsoid connecting the two provided planetodetic points.
EllipsoidGeodesic(Ellipsoid ellipsoid, Cartographic initial, double heading, double distance) Initializes a geodesic on the ellipsoid starting at the provided point and which has the indicated heading at that point and ends at a point located at the provided distance from the starting point.

Method Summary

Modifier and Type	Method and Description
CartographicExtent	computeCartographicExtent() Computes the cartographic bounding box which contains the surface curve.
Cartographic	findClosestPointOnCurve(Cartographic point, double[] distance) Finds the closest point on the curve from the input point.
Ellipsoid	getEllipsoid() Gets the ellipsoid on which the geodesic lies.
double	getFinalHeading() Gets the heading at the final point.
Cartographic	getFinalPoint() Gets the final planetodetic point on the path.
double	getInitialHeading() Gets the heading at the initial point.
Cartographic	getInitialPoint() Gets the initial planetodetic point on the path.
double	getSurfaceDistance() Gets the total distance along the geodesic to the location of the final point.
double	heading(Cartographic location) Provides the heading at a location on the geodesic.
Motion1<Double>	headingMotion(Cartographic location, double groundSpeed) Provides the heading and rate of change of heading at a location on the geodesic.
Cartographic	interpolateUsingFraction(double fraction) Provides the location of a point at the indicated portion along the geodesic.
Cartographic	interpolateUsingSurfaceDistance(double surfaceDistance) Provides the location of a point at the indicated distance along the geodesic.
Cartesian	surfaceMotion(double distance) Converts the motion given in terms of motion on the geodesic curve to motion of the surface point.
Motion1<Cartesian>	surfaceMotion(double distance, double groundSpeed, double groundAcceleration) Converts the motion given in terms of motion on the geodesic curve to motion of the surface point.

Methods inherited from class agi.foundation.geometry.shapes.EllipsoidSurfaceCurve

computeHashCode, computeIntersection, equals, equalsType, findClosestPointOnCurve, getDiscretePoints, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EllipsoidGeodesic

public EllipsoidGeodesic(@Nonnull
                         Ellipsoid ellipsoid,
                         @Nonnull
                         Cartographic initial,
                         @Nonnull
                         Cartographic _final)

Initializes a geodesic on the ellipsoid connecting the two provided planetodetic points.

If the initial point lies at a pole, the longitude of the initial point is used to determine the meridian on which the geodesic lies. If the _final point lies at a pole, the FinalHeading (get) and longitude of the FinalPoint (get) of the geodesic will be consistent with the rest of the points on the geodesic curve.

Parameters:

ellipsoid - The ellipsoid on which the geodesic lies.

initial - The initial planetodetic point on the path. The InitialPoint (get) will be on the ellipsoid surface at this location.

_final - The final planetodetic point on the path. The FinalPoint (get) will be on the ellipsoid surface at this location.

Throws:

ArgumentNullException - Thrown when the parameter ellipsoid is null.

ArgumentException - Thrown when there is no unique geodesic curve connecting the initial and _final points. This usually occurs when the two points are in opposition.

UnsupportedCaseException - The scalene case of a geodesic ellipsoid is not currently modeled and will be in a future release.

EllipsoidGeodesic

public EllipsoidGeodesic(@Nonnull
                         Ellipsoid ellipsoid,
                         @Nonnull
                         Cartographic initial,
                         double heading,
                         double distance)

Initializes a geodesic on the ellipsoid starting at the provided point and which has the indicated heading at that point and ends at a point located at the provided distance from the starting point.

If the initial point lies at a pole, the sum of the longitude of the initial point and the heading is used to determine the meridian on which the geodesic lies. If the final point determined for the geodesic lies at a pole, the FinalPoint (get) of the geodesic will report longitude and heading consistent with the rest of the points on the geodesic curve.

Parameters:

ellipsoid - The ellipsoid on which the geodesic lies.

initial - The initial planetodetic point on the path. The InitialPoint (get) will be on the ellipsoid surface at this location.

heading - The heading at the initial point.

distance - The distance along the geodesic to the location of the final point.

Throws:

ArgumentNullException - Thrown when the parameter ellipsoid is null.

UnsupportedCaseException - The scalene case of a geodesic ellipsoid is not currently modeled and will be in a future release.

Method Detail

getEllipsoid

public Ellipsoid getEllipsoid()

Gets the ellipsoid on which the geodesic lies.

Specified by:

getEllipsoid in class EllipsoidSurfaceCurve

getInitialPoint

@Nonnull
public Cartographic getInitialPoint()

Gets the initial planetodetic point on the path.

Specified by:

getInitialPoint in class EllipsoidSurfaceCurve

getInitialHeading

public final double getInitialHeading()

Gets the heading at the initial point.

getFinalPoint

@Nonnull
public Cartographic getFinalPoint()

Gets the final planetodetic point on the path.

Specified by:

getFinalPoint in class EllipsoidSurfaceCurve

getFinalHeading

public final double getFinalHeading()

Gets the heading at the final point.

getSurfaceDistance

public double getSurfaceDistance()

Gets the total distance along the geodesic to the location of the final point.

Specified by:

getSurfaceDistance in class EllipsoidSurfaceCurve

computeCartographicExtent

public CartographicExtent computeCartographicExtent()

Computes the cartographic bounding box which contains the surface curve. This includes looking for the minimum and maximum latitudes which may lie above or below the initial and final points due to oblateness in the Ellipsoid (get).

Specified by:

computeCartographicExtent in class EllipsoidSurfaceCurve

Returns:

An object representing the bounding box.

findClosestPointOnCurve

@Nonnull
public Cartographic findClosestPointOnCurve(@Nonnull
                                                      Cartographic point,
                                                      @Nonnull
                                                      double[] distance)

Finds the closest point on the curve from the input point.

The default implementation is a golden section search on the curve. The built-in types (geodesic, rhumb, and complex) have their own precise algorithms.

Overrides:

findClosestPointOnCurve in class EllipsoidSurfaceCurve

Parameters:

point - The input point. The point will be on the ellipsoid surface at this location.

distance - The surface distance between the point and the point on the curve.

Returns:

The closest point on the curve.

interpolateUsingFraction

@Nonnull
public Cartographic interpolateUsingFraction(double fraction)

Provides the location of a point at the indicated portion along the geodesic.

Specified by:

interpolateUsingFraction in class EllipsoidSurfaceCurve

Parameters:

fraction - The portion of the distance between the initial and final points.

Returns:

The planetodetic location of the point along the geodesic.

interpolateUsingSurfaceDistance

@Nonnull
public Cartographic interpolateUsingSurfaceDistance(double surfaceDistance)

Provides the location of a point at the indicated distance along the geodesic.

Specified by:

interpolateUsingSurfaceDistance in class EllipsoidSurfaceCurve

Parameters:

surfaceDistance - The distance from the initial point to the point of interest along the geodesic.

Returns:

The planetodetic location of the point along the geodesic.

heading

public final double heading(@Nonnull
                            Cartographic location)

Provides the heading at a location on the geodesic.

Parameters:

location - The planetodetic location of interest.

Returns:

The heading.

headingMotion

@Nonnull
public final Motion1<Double> headingMotion(@Nonnull
                                                     Cartographic location,
                                                     double groundSpeed)

Provides the heading and rate of change of heading at a location on the geodesic.

The location must be a point on the geodesic.

Parameters:

location - The planetodetic location of interest.

groundSpeed - The speed on the geodesic (ground speed) at the indicated location.

Returns:

The motion of the heading angle.

surfaceMotion

@Nonnull
public final Motion1<Cartesian> surfaceMotion(double distance,
                                                        double groundSpeed,
                                                        double groundAcceleration)

Converts the motion given in terms of motion on the geodesic curve to motion of the surface point.

Parameters:

distance - The distance from the initial point to the point of interest along the geodesic.

groundSpeed - The velocity on the geodesic.

groundAcceleration - The acceleration on the geodesic.

Returns:

The motion of the surface point.

surfaceMotion

@Nonnull
public final Cartesian surfaceMotion(double distance)

Converts the motion given in terms of motion on the geodesic curve to motion of the surface point.

Parameters:

distance - The distance from the initial point to the point of interest along the geodesic.

Returns:

The distance from the initial point to the location of the surface point.