com.luciad.geodesy

Class GeodesyCalculations

java.lang.Object

com.luciad.geodesy.GeodesyCalculations

All Implemented Interfaces:

AutoCloseable

public final class GeodesyCalculations
extends Object
implements AutoCloseable

Provides geodesy calculations.

• Distance between two points.
• Azimuth to go from one point to another.
• Calculate point from a given start point, azimuth and distance.

All methods return an optional value. As transformations may be involved during the calculations, there may not always be a result.

Method Summary

Modifier and Type	Method and Description
void	close()
static GeodesyCalculations	create(CoordinateReference reference, LineInterpolationType lineType) Factory to create geodesy implementations for a given coordinate reference and line type.
Double	distance2D(Coordinate p1, Coordinate p2) Calculates the distance to go from point p1 to point p2.
Double	distance3D(Coordinate p1, Coordinate p2) Calculates the distance to go from point p1 to point p2.
Coordinate	extrapolate2D(Coordinate p1, Azimuth azimuth, double distance) Determines the point located in the given direction and distance from point p1.
protected void	finalize()
Azimuth	forwardAzimuth2D(Coordinate p1, Coordinate p2) Calculates the forward azimuth to go from point p1 to point p2.
Coordinate	interpolate(Coordinate p1, Coordinate p2, double fraction) Calculates the point at a fraction of the distance (over ground) between point p1 and point p2.

Methods inherited from class java.lang.Object

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

Method Detail

finalize

protected void finalize()

Overrides:

finalize in class Object

close

public void close()

Specified by:

close in interface AutoCloseable

forwardAzimuth2D

@Nullable
public Azimuth forwardAzimuth2D(@NotNull
                                          Coordinate p1,
                                          @NotNull
                                          Coordinate p2)

Calculates the forward azimuth to go from point p1 to point p2.

Parameters:

p1 - The start point.

p2 - The end point.

Returns:

the forward azimuth, or null.

distance2D

@Nullable
public Double distance2D(@NotNull
                                   Coordinate p1,
                                   @NotNull
                                   Coordinate p2)

Calculates the distance to go from point p1 to point p2.

This is the distance over ground. The height information is ignored.

Parameters:

p1 - The start point.

p2 - The end point.

Returns:

the distance, or null.

distance3D

@Nullable
public Double distance3D(@NotNull
                                   Coordinate p1,
                                   @NotNull
                                   Coordinate p2)

Calculates the distance to go from point p1 to point p2.

The distance calculations take the heights of the given points into account.

Parameters:

p1 - The start point.

p2 - The end point.

Returns:

the distance, or null.

interpolate

@Nullable
public Coordinate interpolate(@NotNull
                                        Coordinate p1,
                                        @NotNull
                                        Coordinate p2,
                                        double fraction)

Calculates the point at a fraction of the distance (over ground) between point p1 and point p2.

The height information is linearly interpolated.

Parameters:

p1 - The start point.

p2 - The end point.

fraction - The fraction value within the range [0,1].

Returns:

the point located at the fraction along the line [p1,p2], or null.

extrapolate2D

@Nullable
public Coordinate extrapolate2D(@NotNull
                                          Coordinate p1,
                                          @NotNull
                                          Azimuth azimuth,
                                          double distance)

Determines the point located in the given direction and distance from point p1.

The height information is assumed to be constant.

Parameters:

p1 - The start point.

azimuth - The forward azimuth.

distance - The distance (over ground).

Returns:

the point located located in the given direction and distance from point p1, or null.

create

@NotNull
public static GeodesyCalculations create(@NotNull
                                                  CoordinateReference reference,
                                                  @NotNull
                                                  LineInterpolationType lineType)
                                           throws IllegalArgumentException

Factory to create geodesy implementations for a given coordinate reference and line type.

The reference can be ellipsoidal or cartesian.

Overview of supported combinations

The following table shows which combinations of coordinate references and line types are supported by the factory.

Coordinate Reference	Linear	Geodesic	Rhumbline
Geographic CRS	yes	yes	yes
Projected CRS	yes	yes	yes
Geocentric CRS	yes	yes	yes
non-georeferenced	no	no	no

Implementation notes

Geographic, Projected, Geocentric - Geodesic, Rhumbline

The calculations are performed on the ellipsoid associated with the coordinate reference. Points are first transformed to the ellipsoid coordinates to perform the calculation. Results are transformed back to the coordinate reference.

Projected, Geocentric - Linear

The standard cartesian implementation of the methods. No specific (point) transformations are done.

Geographic - Linear

Performs cartesian calculations on the geographic points. The implementation takes following characteristics of geographic coordinates into account:

• wrap-around over the 180° meridian.
• stop at 90° latitude and -90° latitude.

Example usage

    String identifier = "EPSG:4326";
    CoordinateReference coordinateRef = CoordinateReferenceProvider.create(identifier);
    GeodesyCalculations geodesy = GeodesyCalculations.create(coordinateRef, LineInterpolationType.Geodesic);
    Coordinate p1 = new Coordinate(3.0, 50.0, 30.0);
    Coordinate p2 = new Coordinate(4.0, 52.0, 55.0);
    double dist12 = geodesy.distance2D(p1, p2);
    double azim12 = geodesy.forwardAzimuth2D(p1, p2).getDegrees();

Parameters:

reference - the coordinate reference on which to perform the geodesy calculations, cannot be null.

lineType - the type of interpolation for the lines.

Throws:

IllegalArgumentException - when no GeodesyCalculations can be created. This may be due to an unsupported combination of reference and line interpolation type or when the coordinate reference is null.