LuciadCPillar 2024.0.08
All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
luciad::GeodesyCalculations Class Referenceabstract

Provides geodesy calculations. More...

#include <luciad/geodesy/GeodesyCalculations.h>

Public Member Functions

virtual ~GeodesyCalculations ()=default
 
virtual std::optional< double > distance2D (const Coordinate &p1, const Coordinate &p2)=0
 Calculates the distance to go from point p1 to point p2. More...
 
virtual std::optional< double > distance3D (const Coordinate &p1, const Coordinate &p2)=0
 Calculates the distance to go from point p1 to point p2. More...
 
virtual std::optional< Coordinateextrapolate2D (const Coordinate &p1, luciad::Azimuth azimuth, double distance)=0
 Determines the point located in the given direction and distance from point p1. More...
 
virtual std::optional< luciad::AzimuthforwardAzimuth2D (const Coordinate &p1, const Coordinate &p2)=0
 Calculates the forward azimuth to go from point p1 to point p2. More...
 
virtual std::optional< Coordinateinterpolate (const Coordinate &p1, const Coordinate &p2, double fraction)=0
 Calculates the point at a fraction of the distance (over ground) between point p1 and point p2. More...
 

Static Public Member Functions

static std::shared_ptr< luciad::GeodesyCalculationscreate (std::shared_ptr< luciad::CoordinateReference > reference, luciad::LineInterpolationType lineType)
 Factory to create geodesy implementations for a given coordinate reference and line type. More...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ ~GeodesyCalculations()

virtual luciad::GeodesyCalculations::~GeodesyCalculations ( )
virtualdefault

Member Function Documentation

◆ create()

static std::shared_ptr< luciad::GeodesyCalculations > luciad::GeodesyCalculations::create ( std::shared_ptr< luciad::CoordinateReference reference,
luciad::LineInterpolationType  lineType 
)
static

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

std::string identifier = "EPSG:4326";
auto coordinateRef = CoordinateReferenceProvider::create(identifier);
auto geodesy = GeodesyCalculations::create(coordinateRef.value(), LineInterpolationType::Geodesic);
Coordinate p1 = Coordinate(3.0, 50.0, 30.0);
Coordinate p2 = Coordinate(4.0, 52.0, 55.0);
double dist12 = geodesy->distance2D(p1, p2).value();
double azim12 = geodesy->forwardAzimuth2D(p1, p2).value().getDegrees();
static luciad::expected< std::shared_ptr< CoordinateReference >, ErrorInfo > create(const std::string &identifier)
Creates the coordinate reference from a given EPSG, WKT (version 1) or OGC identifier.
static std::shared_ptr< luciad::GeodesyCalculations > create(std::shared_ptr< luciad::CoordinateReference > reference, luciad::LineInterpolationType lineType)
Factory to create geodesy implementations for a given coordinate reference and line type.
@ Geodesic
Geodesic interpolation between points.
A "POD" for a 3D coordinate.
Definition: Coordinate.h:14
Parameters
referencethe coordinate reference on which to perform the geodesy calculations, cannot be nullptr.
lineTypethe type of interpolation for the lines.
Exceptions
InvalidArgumentExceptionwhen 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 nullptr.

◆ distance2D()

virtual std::optional< double > luciad::GeodesyCalculations::distance2D ( const Coordinate p1,
const Coordinate p2 
)
pure virtual

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 std::nullopt 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
p1The start point.
p2The end point.
Returns
the distance, or std::nullopt.

◆ distance3D()

virtual std::optional< double > luciad::GeodesyCalculations::distance3D ( const Coordinate p1,
const Coordinate p2 
)
pure virtual

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 std::nullopt 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
p1The start point.
p2The end point.
Returns
the distance, or std::nullopt.

◆ extrapolate2D()

virtual std::optional< Coordinate > luciad::GeodesyCalculations::extrapolate2D ( const Coordinate p1,
luciad::Azimuth  azimuth,
double  distance 
)
pure virtual

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 std::nullopt. 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
p1The start point.
azimuthThe forward azimuth.
distanceThe distance (over ground).
Returns
the point located located in the given direction and distance from point p1, or std::nullopt.

◆ forwardAzimuth2D()

virtual std::optional< luciad::Azimuth > luciad::GeodesyCalculations::forwardAzimuth2D ( const Coordinate p1,
const Coordinate p2 
)
pure virtual

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

This method can return std::nullopt 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
p1The start point.
p2The end point.
Returns
the forward azimuth, or std::nullopt.

◆ interpolate()

virtual std::optional< Coordinate > luciad::GeodesyCalculations::interpolate ( const Coordinate p1,
const Coordinate p2,
double  fraction 
)
pure virtual

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 std::nullopt. 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
p1The start point.
p2The end point.
fractionThe fraction value within the range [0,1].
Returns
the point located at the fraction along the line [p1,p2], or std::nullopt.