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 Details Link icon

    • finalize Link icon

      protected void finalize()
      Overrides:
      finalize in class Object
    • close Link icon

      public void close()
      Specified by:
      close in interface AutoCloseable
    • forwardAzimuth2D Link icon

      @Nullable public Azimuth forwardAzimuth2D(@NotNull Coordinate p1, @NotNull Coordinate p2)
      Calculates the forward azimuth to go from point p1 to point p2.

      This method can return null when the azimuth can not be calculated. This can happen in these cases:

      • The input coordinates are not correct. For example: a latitude higher than 90 or lower than -90 is specified.
      • When using a geodesic or rhumb LineInterpolationType, the input coordinate may need to be converted to geodetic coordinates first when the input reference is not geodetic. This is not always possible, for example when the input points are outside the projection bounds of the input reference.
      Parameters:
      p1 - The start point.
      p2 - The end point.
      Returns:
      the forward azimuth, or null.
    • distance2D Link icon

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

      This method can return null when the distance can not be calculated. This can happen in these cases:

      • The input coordinates are not correct. For example: a latitude higher than 90 or lower than -90 is specified.
      • When using a geodesic or rhumb LineInterpolationType, the input coordinate may need to be converted to geodetic coordinates first when the input reference is not geodetic. This is not always possible, for example when the input points are outside the projection bounds of the input reference.
      Parameters:
      p1 - The start point.
      p2 - The end point.
      Returns:
      the distance, or null.
    • distance3D Link icon

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

      This method can return null when the distance can not be calculated. This can happen in these cases:

      • The input coordinates are not correct. For example: a latitude higher than 90 or lower than -90 is specified.
      • When using a geodesic or rhumb LineInterpolationType, the input coordinate may need to be converted to geodetic coordinates first when the input reference is not geodetic. This is not always possible, for example when the input points are outside the projection bounds of the input reference.
      Parameters:
      p1 - The start point.
      p2 - The end point.
      Returns:
      the distance, or null.
    • interpolate Link icon

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

      This method can return null. This can happen in these cases:

      • The input coordinates are not correct. For example: a latitude higher than 90 or lower than -90 is specified.
      • When using a geodesic or rhumb LineInterpolationType, the input coordinate may need to be converted to geodetic coordinates first when the input reference is not geodetic. This is not always possible, for example when the input points are outside the projection bounds of the input reference.
      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 Link icon

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

      This method can return null. This can happen in these cases:

      • The input coordinates are not correct. For example: a latitude higher than 90 or lower than -90 is specified.
      • When using a geodesic or rhumb LineInterpolationType, the input coordinate may need to be converted to geodetic coordinates first when the input reference is not geodetic. This is not always possible, for example when the input points are outside the projection bounds of the input reference.
      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 Link icon

      @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 Link icon

      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 Link icon

      Geographic, Projected, Geocentric - Geodesic, Rhumbline Link icon

      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 Link icon

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

      Geographic - Linear Link icon

      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 Link icon

      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.