org.geotools.referencing

Class GeodeticCalculator

Object

GeodeticCalculator

public class GeodeticCalculator
extends Object

Performs geodetic calculations on an ellipsoid. This class encapsulates a generic ellipsoid and calculates the following properties:

• Distance and azimuth between two points.
• Point located at a given distance and azimuth from an other point.

The calculation uses the following information:

• The starting position, which is always considered valid. It is initially set at (0,0) and can only be changed to another legitimate value.
• Only one of the following:
  • The destination position, or
  • An azimuth and distance.
  The last one set overrides the other and determines what will be calculated.

Note: This class is not thread-safe. If geodetic calculations are needed in a multi-threads environment, create one distinct instance of GeodeticCalculator for each thread.

Since:

2.1

Author:

Daniele Franzoni, Martin Desruisseaux

Constructor Summary

Constructors

Constructor and Description
GeodeticCalculator() Constructs a new geodetic calculator associated with the WGS84 ellipsoid.
GeodeticCalculator(CoordinateReferenceSystem crs) Constructs a new geodetic calculator expecting coordinates in the supplied CRS.
GeodeticCalculator(Ellipsoid ellipsoid) Constructs a new geodetic calculator associated with the specified ellipsoid.

Method Summary

Modifier and Type	Method and Description
double	getAzimuth() Returns the azimuth.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system for all methods working on Position objects.
Point2D	getDestinationGeographicPoint() Returns the destination point.
DirectPosition	getDestinationPosition() Returns the destination position in user coordinates, which doesn't need to be geographic.
Ellipsoid	getEllipsoid() Returns the referenced ellipsoid.
Shape	getGeodeticCurve() Calculates the geodetic curve between two points in the referenced ellipsoid.
Shape	getGeodeticCurve(int numberOfPoints) Calculates the geodetic curve between two points in the referenced ellipsoid.
List<Point2D>	getGeodeticPath(int numPoints) Calculates the geodetic curve between two points in the referenced ellipsoid.
GeographicCRS	getGeographicCRS() Returns the geographic coordinate reference system for all methods working on Point2D objects.
double	getMeridianArcLength(double latitude1, double latitude2) Calculates the meridian arc length between two points in the same meridian in the referenced ellipsoid.
double	getOrthodromicDistance() Returns the orthodromic distance (expressed in meters).
Point2D	getStartingGeographicPoint() Returns the starting point in geographic coordinates.
DirectPosition	getStartingPosition() Returns the starting position in user coordinates, which doesn't need to be geographic.
void	setDestinationGeographicPoint(double longitude, double latitude) Set the destination point in geographic coordinates.
void	setDestinationGeographicPoint(Point2D point) Set the destination point in geographic coordinates.
void	setDestinationPosition(Position position) Set the destination position in user coordinates, which doesn't need to be geographic.
void	setDirection(double azimuth, double distance) Set the azimuth and the distance from the starting point.
void	setStartingGeographicPoint(double longitude, double latitude) Set the starting point in geographic coordinates.
void	setStartingGeographicPoint(Point2D point) Set the starting point in geographic coordinates.
void	setStartingPosition(Position position) Set the starting position in user coordinates, which doesn't need to be geographic.
String	toString() Returns a string representation of the current state of this calculator.

Methods inherited from class Object

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

Constructor Detail

GeodeticCalculator

public GeodeticCalculator()

Constructs a new geodetic calculator associated with the WGS84 ellipsoid.

GeodeticCalculator

public GeodeticCalculator(Ellipsoid ellipsoid)

Constructs a new geodetic calculator associated with the specified ellipsoid. All calculations done by the new instance are referenced to this ellipsoid.

Parameters:

ellipsoid - The ellipsoid onto which calculates distances and azimuths.

GeodeticCalculator

public GeodeticCalculator(CoordinateReferenceSystem crs)

Constructs a new geodetic calculator expecting coordinates in the supplied CRS. The ellipsoid will be inferred from the CRS.

Parameters:

crs - The reference system for the Position objects.

Since:

2.2

Method Detail

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the coordinate reference system for all methods working on Position objects. This is the CRS specified at construction time.

Returns:

The CRS for all Positions.

Since:

2.2

getGeographicCRS

public GeographicCRS getGeographicCRS()

Returns the geographic coordinate reference system for all methods working on Point2D objects. This is inferred from the CRS specified at construction time.

Returns:

The CRS for Point2Ds.

Since:

2.3

getEllipsoid

public Ellipsoid getEllipsoid()

Returns the referenced ellipsoid.

Returns:

The referenced ellipsoid.

setStartingGeographicPoint

public void setStartingGeographicPoint(double longitude,
                                       double latitude)
                                throws IllegalArgumentException

Set the starting point in geographic coordinates. The azimuth, the orthodromic distance and the destination point are discarted. They will need to be specified again.

Parameters:

longitude - The longitude in decimal degrees between -180 and +180°

latitude - The latitude in decimal degrees between -90 and +90°

Throws:

IllegalArgumentException - if the longitude or the latitude is out of bounds.

Since:

2.3

setStartingGeographicPoint

public void setStartingGeographicPoint(Point2D point)
                                throws IllegalArgumentException

Set the starting point in geographic coordinates. The x and y coordinates must be the longitude and latitude in decimal degrees, respectively.

This is a convenience method for setStartingGeographicPoint(x,y).

Parameters:

point - The starting point.

Throws:

IllegalArgumentException - if the longitude or the latitude is out of bounds.

Since:

2.3

setStartingPosition

public void setStartingPosition(Position position)
                         throws TransformException

Set the starting position in user coordinates, which doesn't need to be geographic. The coordinate reference system is the one specified to the constructor.

Parameters:

position - The position in user coordinate reference system.

Throws:

TransformException - if the position can't be transformed.

Since:

2.3

getStartingGeographicPoint

public Point2D getStartingGeographicPoint()

Returns the starting point in geographic coordinates. The x and y coordinates are the longitude and latitude in decimal degrees, respectively. If the starting point has never been set, then the default value is (0,0).

Returns:

The starting point in geographic coordinates.

Since:

2.3

getStartingPosition

public DirectPosition getStartingPosition()
                                   throws TransformException

Returns the starting position in user coordinates, which doesn't need to be geographic. The coordinate reference system is the one specified to the constructor.

Returns:

The starting position in user CRS.

Throws:

TransformException - if the position can't be transformed to user coordinates.

Since:

2.3

setDestinationGeographicPoint

public void setDestinationGeographicPoint(double longitude,
                                          double latitude)
                                   throws IllegalArgumentException

Set the destination point in geographic coordinates. The azimuth and distance values will be updated as a side effect of this call. They will be recomputed the next time getAzimuth() or getOrthodromicDistance() are invoked.

Parameters:

longitude - The longitude in decimal degrees

latitude - The latitude in decimal degrees between -90 and +90°

Throws:

IllegalArgumentException - if the longitude or the latitude is out of bounds.

Since:

2.3

setDestinationGeographicPoint

public void setDestinationGeographicPoint(Point2D point)
                                   throws IllegalArgumentException

Set the destination point in geographic coordinates. The x and y coordinates must be the longitude and latitude in decimal degrees, respectively.

This is a convenience method for setDestinationGeographicPoint(x,y).

Parameters:

point - The destination point.

Throws:

IllegalArgumentException - if the longitude or the latitude is out of bounds.

Since:

2.3

setDestinationPosition

public void setDestinationPosition(Position position)
                            throws TransformException

Set the destination position in user coordinates, which doesn't need to be geographic. The coordinate reference system is the one specified to the constructor.

Parameters:

position - The position in user coordinate reference system.

Throws:

TransformException - if the position can't be transformed.

Since:

2.2

getDestinationGeographicPoint

public Point2D getDestinationGeographicPoint()
                                      throws IllegalStateException

Returns the destination point. This method returns the point set by the last call to a setDestinationGeographicPoint(...) method, except if setDirection(...) has been invoked after. In this later case, the destination point will be computed from the starting point to the azimuth and distance specified.

Returns:

The destination point. The x and y coordinates are the longitude and latitude in decimal degrees, respectively.

Throws:

IllegalStateException - if the azimuth and the distance have not been set.

Since:

2.3

getDestinationPosition

public DirectPosition getDestinationPosition()
                                      throws TransformException

Returns the destination position in user coordinates, which doesn't need to be geographic. The coordinate reference system is the one specified to the constructor.

Returns:

The destination position in user CRS.

Throws:

TransformException - if the position can't be transformed to user coordinates.

Since:

2.2

setDirection

public void setDirection(double azimuth,
                         double distance)
                  throws IllegalArgumentException

Set the azimuth and the distance from the starting point. The destination point will be updated as a side effect of this call. It will be recomputed the next time getDestinationGeographicPoint() is invoked.

Parameters:

azimuth - The azimuth in decimal degrees

distance - The orthodromic distance in the same units as the ellipsoid axis (meters by default)

Throws:

IllegalArgumentException - if the azimuth or the distance is out of bounds.

See Also:

getAzimuth(), getOrthodromicDistance()

getAzimuth

public double getAzimuth()
                  throws IllegalStateException

Returns the azimuth. This method returns the value set by the last call to setDirection(azimuth,distance), except if setDestinationGeographicPoint(...) has been invoked after. In this later case, the azimuth will be computed from the starting point to the destination point.

Returns:

The azimuth, in decimal degrees from -180° to +180°.

Throws:

IllegalStateException - if the destination point has not been set.

getOrthodromicDistance

public double getOrthodromicDistance()
                              throws IllegalStateException

Returns the orthodromic distance (expressed in meters). This method returns the value set by the last call to setDirection(azimuth,distance), except if setDestinationGeographicPoint(...) has been invoked after. In this later case, the distance will be computed from the starting point to the destination point.

Returns:

The orthodromic distance, in the same units as the ellipsoid axis.

Throws:

IllegalStateException - if the destination point has not been set.

getMeridianArcLength

public double getMeridianArcLength(double latitude1,
                                   double latitude2)

Calculates the meridian arc length between two points in the same meridian in the referenced ellipsoid.

Parameters:

latitude1 - The latitude of the first point (in decimal degrees).

latitude2 - The latitude of the second point (in decimal degrees).

Returns:

Returned the meridian arc length between latitude1 and latitude2

getGeodeticCurve

public Shape getGeodeticCurve(int numberOfPoints)

Calculates the geodetic curve between two points in the referenced ellipsoid. A curve in the ellipsoid is a path which points contain the longitude and latitude of the points in the geodetic curve. The geodetic curve is computed from the starting point to the destination point.

Parameters:

numberOfPoints - The number of vertex in the geodetic curve. NOTE: This argument is only a hint and may be ignored in future version (if we compute a real curve rather than a list of line segments).

Returns:

The path that represents the geodetic curve from the starting point to the destination point.

getGeodeticCurve

public Shape getGeodeticCurve()

Calculates the geodetic curve between two points in the referenced ellipsoid. A curve in the ellipsoid is a path which points contain the longitude and latitude of the points in the geodetic curve. The geodetic curve is computed from the starting point to the destination point.

Returns:

The path that represents the geodetic curve from the starting point to the destination point.

getGeodeticPath

public List<Point2D> getGeodeticPath(int numPoints)

Calculates the geodetic curve between two points in the referenced ellipsoid. A curve in the ellipsoid is a path which points contain the longitude and latitude of the points in the geodetic curve. The geodetic curve is computed from the starting point to the destination point.

Parameters:

numPoints - The number of vertices between the start and destination points

Returns:

vertices approximating the curve

toString

public String toString()

Returns a string representation of the current state of this calculator.

Overrides:

toString in class Object