Package org.apache.sis.referencing

Class GeodesicsOnEllipsoid

java.lang.Object

org.apache.sis.referencing.GeodeticCalculator

org.apache.sis.referencing.GeodesicsOnEllipsoid

class GeodesicsOnEllipsoid
extends GeodeticCalculator

Performs geodetic calculations on an ellipsoid. This class overrides the spherical formulas implemented in the parent class, replacing them by ellipsoidal formulas. The methods for direct and inverse geodesic problem use the formulas described in the following publication:

Charles F. F. Karney, 2013. Algorithms for geodesics, SRI International.

The following symbols are used with the same meaning than in Karney's article, except λ₁₂ which is represented by ∆λ:

• a: equatorial radius of the ellipsoid of revolution.
• b: polar semi-axis of the ellipsoid of revolution.
• ℯ: first eccentricity: ℯ = √[(a²-b²)/a²].
• ℯ′: second eccentricity: ℯ′ = √[(a²-b²)/b²].
• n: third flattening: n = (a-b)/(a+b).
• E: the point at which the geodesic crosses the equator in the northward direction.
• P: the start point (P₁) or end point (P₂).
• ∆λ: longitude difference between start point and end point (λ₁₂ in Karney).
• β: reduced latitude, related to φ geodetic latitude on the ellipsoid.
• ω: spherical longitude, related to λ geodetic longitude on the ellipsoid.
• σ: spherical arc length, related to distance s on the ellipsoid.

Suffix 1 in variable names denotes values computed using starting point (P₁) and starting azimuth (α₁) while suffix 2 denotes values computed using ending point (P₂) and ending azimuth (α₂). All angular values stored in this class are in radians.

Limitations

Current implementation is still unable to compute the geodesics in some cases. In particular, calculation may fail for antipodal points. See SIS-467.

If the following cases where more than one geodesics exist, current implementation returns an arbitrary one:

• Coincident points (distance is zero but azimuths can be anything).
• Starting point and ending points are at opposite poles (there are infinitely many geodesics).
• φ₁ = -φ₂ and ∆λ is close to 180° (two geodesics may exist).
• ∆λ = ±180° (two geodesics may exist).

Since:

1.0

Version:

1.0

Field Summary

Fields

Modifier and Type	Field	Description
private double	A1	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	A2	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	A3	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
(package private) final double	axisRatio	Ration between the semi-minor and semi-major axis b/a.
private double	C31	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	C32	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	C33	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	C34	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	C35	Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)).
private double	cosα0	The α value computed from the starting point and starting azimuth.
(package private) final double	eccentricitySquared	The square of eccentricity: ℯ² = (a²-b²)/a² where ℯ is the eccentricity, a is the semi-major axis length and b is the semi-minor axis length.
private double	I1_σ1	Ellipsoidal arc length s₁/b computed from the spherical arc length σ₁.
(package private) static final double	ITERATION_TOLERANCE	Accuracy threshold for iterative computations, in radians.
private static final double	NEARLY_ANTIPODAL_Δλ	Difference between ending point and antipode of starting point for considering them as nearly antipodal.
private final double	R0	Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.
private final double	R2	Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.
private final double	R4	Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.
private final double	R6	Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.
(package private) final double	secondEccentricitySquared	The square of the second eccentricity: ℯ′² = (a²-b²)/b².
private double	sinα0	The α value computed from the starting point and starting azimuth.
(package private) static final boolean	STORE_LOCAL_VARIABLES	Whether to include code used for JUnit tests only.
(package private) final double	thirdFlattening	Third flattening of the ellipsoid: n = (a-b)/(a+b).
private double	ε	The term to be raised to powers (ε⁰, ε¹, ε², ε³, …) in series expansions.
private double	λ1E	Longitude angle from the equatorial point E to starting point P₁ on the ellipsoid.

Fields inherited from class org.apache.sis.referencing.GeodeticCalculator

COEFFICIENTS_FOR_START_POINT, ellipsoid, END_POINT, ENDING_AZIMUTH, GEODESIC_DISTANCE, geodesicDistance, LATITUDE_THRESHOLD, mcosα1, mcosα2, msinα1, msinα2, RHUMBLINE_LENGTH, rhumblineAzimuth, rhumblineLength, semiMajorAxis, START_POINT, STARTING_AZIMUTH, λ1, λ2, φ1, φ2

Constructor Summary

Constructors

Constructor	Description
GeodesicsOnEllipsoid(org.opengis.referencing.crs.CoordinateReferenceSystem crs, org.opengis.referencing.datum.Ellipsoid ellipsoid)	Constructs a new geodetic calculator expecting coordinates in the supplied CRS.

Method Summary

Modifier and Type	Method	Description
(package private) final void	computeDistance()	Computes the geodesic distance and azimuths from the start point and end point.
(package private) double	computedToGiven(double α1)	Replaces a computed value by the value given in Karney table.
(package private) final void	computeEndPoint()	Computes the end point from the start point, the azimuth and the geodesic distance.
(package private) final void	computeRhumbLine()	Computes rhumb line using series expansion.
private double	computeSeriesExpansionCoefficients()	Computes series expansions coefficients.
(package private) double	dφ_dy(double φ)	Computes (∂y/∂φ)⁻¹ at the given latitude on an ellipsoid with semi-major axis length of 1.
private double	ellipsoidalToSphericalAngle(double τ)	Computes the spherical arc length σ from the an ellipsoidal arc length s.
(package private) final String	getProjectionMethod()	The operation method to use for creating a map projection.
private double	m(double φ, double sinφ)	Computes Bennett (1996) equation 2 modified with Clenshaw summation.
private double	semiMinorAxis()	Length of semi-minor axis.
(package private) final void	snapshot()	Takes a snapshot of the current fields in this class.
private double	sphericalToEllipsoidalAngle(double σ, boolean minusI2)	Computes a term in calculation of ellipsoidal arc length s from the given spherical arc length σ.
private double	sphericalToGeodeticLongitude(double ω, double σ)	Computes the longitude angle λ from the equatorial point E to a point on the ellipsoid specified by the ω longitude on auxiliary sphere.
(package private) void	store(String name, double value)	Stores the value of a local variable or a field.
private void	α0(double sinα1, double cosα1, double sinβ1, double cosβ1)	Sets the sinα0 and cosα0 terms.
private static double	μ(double x2, double y2)	Computes the positive root of quartic equation for estimation of α₁ in nearly antipodal case.

Methods inherited from class org.apache.sis.referencing.GeodeticCalculator

canComputeDistance, canComputeEndPoint, create, createGeodesicCircle2D, createGeodesicPath2D, createProjectionAroundStart, getConstantAzimuth, getDistanceUnit, getEndingAzimuth, getEndPoint, getGeodesicDistance, getGeographicCRS, getPositionCRS, getRhumblineLength, getStartingAzimuth, getStartPoint, isInvalid, moveToEndPoint, setEndGeographicPoint, setEndPoint, setGeodesicDistance, setStartGeographicPoint, setStartingAzimuth, setStartPoint, setValid, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

STORE_LOCAL_VARIABLES

static final boolean STORE_LOCAL_VARIABLES

Whether to include code used for JUnit tests only. This field should be set to true during development and to false in releases.

See Also:

• snapshot()
• Constant Field Values

ITERATION_TOLERANCE

static final double ITERATION_TOLERANCE

Accuracy threshold for iterative computations, in radians. This accuracy must be at least 8.999280057595393E-8 degrees (converted to radians) for conformance with the accuracy reported in GeodeticCalculator class javadoc. Actually we take a finer accuracy than above value in order to met the accuracy of numbers published in Karney (2013), but this extra accuracy is not guaranteed because it is hard to achieve in all cases.

Note: when the iteration loop detects that it reached this requested accuracy, the loop completes the iteration step which was in progress. Consequently, the final accuracy is one iteration better than the accuracy computed from this value.

Maintenance

If this value is modified, the effect can be verified by executing the GeodesicsOnEllipsoidTest methods that compare computed values against Karney's tables. The GeodeticCalculator javadoc may need to be edited accordingly.

See Also:

• Constant Field Values

NEARLY_ANTIPODAL_Δλ

private static final double NEARLY_ANTIPODAL_Δλ

Difference between ending point and antipode of starting point for considering them as nearly antipodal. This is used only for finding an approximate position before to start iteration using Newton's method, so it is okay if the antipodal approximation has some inaccuracy.

See Also:

• Constant Field Values

eccentricitySquared

final double eccentricitySquared

The square of eccentricity: ℯ² = (a²-b²)/a² where ℯ is the eccentricity, a is the semi-major axis length and b is the semi-minor axis length.

secondEccentricitySquared

final double secondEccentricitySquared

The square of the second eccentricity: ℯ′² = (a²-b²)/b².

thirdFlattening

final double thirdFlattening

Third flattening of the ellipsoid: n = (a-b)/(a+b). Not to be confused with the third eccentricity squared ℯ″² = (a²-b²)/(a²+b²) which is not used in this class.

axisRatio

final double axisRatio

Ration between the semi-minor and semi-major axis b/a. This is related to flattening f = 1 - b/a.

sinα0

private double sinα0

The α value computed from the starting point and starting azimuth. We use the sine and cosine instead of the angles because those components are more frequently used than angles. Those values can be kept constant when computing many end points and end azimuths at different geodesic distances. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

cosα0

private double cosα0

The α value computed from the starting point and starting azimuth. We use the sine and cosine instead of the angles because those components are more frequently used than angles. Those values can be kept constant when computing many end points and end azimuths at different geodesic distances. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

λ1E

private double λ1E

Longitude angle from the equatorial point E to starting point P₁ on the ellipsoid. This longitude is computed from the ω₁ longitude on auxiliary sphere, which is itself computed from α₀, α₁, β₁ and ω₁ values computed from the starting point and starting azimuth. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether this field needs to be recomputed.

See Also:

• sphericalToGeodeticLongitude(double, double)

I1_σ1

private double I1_σ1

Ellipsoidal arc length s₁/b computed from the spherical arc length σ₁. The σ₁ value is an arc length on the auxiliary sphere between equatorial point E (the point on equator with forward direction toward azimuth α₀) and starting point P₁. This is computed by I₁(σ₁) in Karney equation 15 and is saved for reuse when the starting point and azimuth do not change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether this field needs to be recomputed.

See Also:

• sphericalToEllipsoidalAngle(double, boolean)

ε

private double ε

The term to be raised to powers (ε⁰, ε¹, ε², ε³, …) in series expansions. Defined in Karney equation 16 as ε = (√[k²+1] - 1) / (√[k²+1] + 1) where k² = ℯ′²⋅cos²α₀ (Karney 9). The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether this field needs to be recomputed.

A1

private double A1

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

A2

private double A2

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

A3

private double A3

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

C31

private double C31

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

C32

private double C32

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

C33

private double C33

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

C34

private double C34

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

C35

private double C35

Coefficients in series expansion of the form A × (σ + ∑Cₓ⋅sin(…⋅σ)). There is 3 series expansions used in this class:

• A₁ and C₁ₓ (Karney 15) are used for arc length conversions from auxiliary sphere to ellipsoid.
• A₂ and C₂ₓ (Karney 41) are used in calculation of reduced length.
• A₃ and C₃ₓ (Karney 23) are used for calculation of geodetic longitude from spherical angles.

The Cₓₓ coefficients are hard-coded, except the C₃ₓ coefficients (used together with A₃) which depend on sinα0 and cosα0. Note that the C coefficients differ from the ones published by Karney because they have been combined using Clenshaw summation.

All those coefficients must be recomputed when the starting point or starting azimuth change. The GeodeticCalculator.COEFFICIENTS_FOR_START_POINT flag specifies whether those fields need to be recomputed.

See Also:

• computeSeriesExpansionCoefficients()

R0

private final double R0

Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.

R2

private final double R2

Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.

R4

private final double R4

Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.

R6

private final double R6

Coefficients for Rhumb line calculation from Bennett (1996) equation 2, modified with Clenshaw summation.

Constructor Details

GeodesicsOnEllipsoid

GeodesicsOnEllipsoid(org.opengis.referencing.crs.CoordinateReferenceSystem crs,
 org.opengis.referencing.datum.Ellipsoid ellipsoid)

Constructs a new geodetic calculator expecting coordinates in the supplied CRS.

Parameters:

crs - the referencing system for the Position arguments and return values.

ellipsoid - ellipsoid associated to the geodetic component of given CRS.

Method Details

semiMinorAxis

private double semiMinorAxis()

Length of semi-minor axis.

See Also:

• Ellipsoid.getSemiMinorAxis()

computeSeriesExpansionCoefficients

private double computeSeriesExpansionCoefficients()

Computes series expansions coefficients.

Preconditions: The sinα0 and cosα0 fields shall be set before to invoke this method. It is caller's responsibility to ensure that sin(α₀)² + cos(α₀)² ≈ 1 (this is verified in assertion).

Post-conditions: this method sets the ε, A1, A2, A3, C31, C32, C33, C34, C35 fields.

It is caller's responsibility to invoke setValid(COEFFICIENTS_FOR_START_POINT) after it has updated λ1E and I1_σ1.

Returns:

k² = ℯ′²⋅cos²α₀ term (Karney 9).

sphericalToEllipsoidalAngle

private double sphericalToEllipsoidalAngle(double σ,
 boolean minusI2)

Computes a term in calculation of ellipsoidal arc length s from the given spherical arc length σ. The σ value is an arc length on the auxiliary sphere between equatorial point E (the point on equator with forward direction toward azimuth α₀) and another point.

If the minusI2 argument is false, then this method computes the ellipsoidal arc length s from the given spherical arc length σ. This value is computed by Karney's equation 7:

s/b = I₁(σ)

If the minusI2 argument is true, then this method is modified for computing Karney's equation 40 instead (a term in calculation of reduced length m):

J(σ) = I₁(σ) - I₂(σ)

Precondition: computeSeriesExpansionCoefficients() must have been invoked before this method.

Parameters:

\u03c3 - arc length on the auxiliary sphere since equatorial point E.

minusI2 - whether to subtract I₂(σ) after calculation of I₁(σ).

Returns:

I₁(σ) if minusI2 is false, or J(σ) if minusI2 is true.

ellipsoidalToSphericalAngle

private double ellipsoidalToSphericalAngle(double τ)

Computes the spherical arc length σ from the an ellipsoidal arc length s. This method is the converse of sphericalToEllipsoidalAngle(double, boolean). Input is τ = s/(b⋅A₁).

Precondition: computeSeriesExpansionCoefficients() must have been invoked before this method.

Parameters:

\u03c4 - arc length on the ellipsoid since equatorial point E divided by A1.

Returns:

arc length σ on the auxiliary sphere.

See Also:

• sphericalToEllipsoidalAngle(double, boolean)

sphericalToGeodeticLongitude

private double sphericalToGeodeticLongitude(double ω,
 double σ)

Computes the longitude angle λ from the equatorial point E to a point on the ellipsoid specified by the ω longitude on auxiliary sphere.

Precondition: computeSeriesExpansionCoefficients() must have been invoked before this method.

Parameters:

\u03c9 - longitude on the auxiliary sphere.

\u03c3 - spherical arc length from equatorial point E to point on auxiliary sphere along a geodesic with azimuth α₀ at equator.

Returns:

geodetic longitude λ from the equatorial point E to the point.

α0

private void α0(double sinα1,
 double cosα1,
 double sinβ1,
 double cosβ1)

Sets the sinα0 and cosα0 terms. Note that the GeodeticCalculator.msinα2 field is always set to the sinα0 value in this class. But those two fields may nevertheless have different values if msinα2 has been set independently, for example by GeodeticCalculator.createGeodesicPath2D(double).

computeEndPoint

final void computeEndPoint()

Computes the end point from the start point, the azimuth and the geodesic distance. This method should be invoked if the end point or ending azimuth is requested while GeodeticCalculator.END_POINT validity flag is not set.

This implementation computes GeodeticCalculator.φ2, GeodeticCalculator.λ2 and azimuths using the method described in Karney (2013) Algorithms for geodesics. The coefficients of Fourier and Taylor series expansions are given by equations 15 and 17.

Overrides:

computeEndPoint in class GeodeticCalculator

Throws:

IllegalStateException - if the start point, azimuth or distance has not been set.

computeDistance

final void computeDistance()

Computes the geodesic distance and azimuths from the start point and end point. This method should be invoked if the distance or an azimuth is requested while GeodeticCalculator.STARTING_AZIMUTH, GeodeticCalculator.ENDING_AZIMUTH or GeodeticCalculator.GEODESIC_DISTANCE validity flag is not set.

Reminder: given P₁ the starting point and E the intersection of the geodesic with equator:

• α₁ is the azimuth (0° oriented North) of the geodesic from E to P₁.
• σ₁ is the spherical arc length (in radians) between E and P₁.
• ω₁ is the spherical longitude (in radians) on the auxiliary sphere at P₁. Spherical longitude is the angle formed by the meridian of E and the meridian of P₁.

Overrides:

computeDistance in class GeodeticCalculator

Throws:

IllegalStateException - if the distance or azimuth has not been set.

GeodeticException - if an azimuth or the distance cannot be computed.

μ

private static double μ(double x2,
 double y2)

Computes the positive root of quartic equation for estimation of α₁ in nearly antipodal case. Formula is given in appendix B of C.F.F Karney (2011) given x and y the coordinates on a plane coordinate system centered on the antipodal point: The results should have only one positive root (μ > 0).

Condition on y value

This method is indeterminate when y → 0 (it returns Double.NaN). For values too close to zero, the result may be non-significative because of rounding errors. For choosing a threshold value for y, GeodesicsOnEllipsoidTest.Calculator compares the value computed by this method against the value computed by MathFunctions.polynomialRoots(double...). If the values differ too much, we presume that they are mostly noise caused by a y value too low.

Parameters:

x2 - the square of x.

y2 - the square of y.

dφ_dy

double dφ_dy(double φ)

Computes (∂y/∂φ)⁻¹ at the given latitude on an ellipsoid with semi-major axis length of 1. This derivative is close to cos(φ) for a slightly flattened sphere.

Overrides:

dφ_dy in class GeodeticCalculator

Returns:

the northing derivative of a Mercator projection at the given latitude on an ellipsoid with a=1.

See Also:

• ConformalProjection.dy_dφ(double, double)

snapshot

final void snapshot()

Takes a snapshot of the current fields in this class. This is used for JUnit tests only. During development phases, STORE_LOCAL_VARIABLES should be true for allowing GeodesicsOnEllipsoidTest to verify the values of a large range of local variables. But when the storage of locale variables is disabled, this method allows GeodesicsOnEllipsoidTest to still verify a few variables.

store

void store(String name,
 double value)

Stores the value of a local variable or a field. This is used in JUnit tests only.

Parameters:

name - name of the local variable.

value - value of the local variable.

computedToGiven

double computedToGiven(double α1)

Replaces a computed value by the value given in Karney table. This is used when the result published in Karney table 4 is used as input for Karney table 5. We need to truncate the value to the same numbers of digits than Karney, otherwise computation results will differ.

computeRhumbLine

final void computeRhumbLine()

Computes rhumb line using series expansion.

Source: G.G. Bennett, 1996. Practical Rhumb Line Calculations on the Spheroid. J. Navigation 49(1), 112-119.

Overrides:

computeRhumbLine in class GeodeticCalculator

See Also:

• Rhumb line on Wikipedia

m

private double m(double φ,
 double sinφ)

Computes Bennett (1996) equation 2 modified with Clenshaw summation.

getProjectionMethod

final String getProjectionMethod()

The operation method to use for creating a map projection. For the ellipsoidal case we use EPSG::9832. According EPSG documentation the precision is acceptable withing 800 km of projection natural origin.

Overrides:

getProjectionMethod in class GeodeticCalculator