Package 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.
Note: This class is not threadsafe. If geodetic calculations are needed in a multithreads environment, create one distinct instance of
GeodeticCalculator
for each thread. Since:
 2.1
 Author:
 Daniele Franzoni, Martin Desruisseaux


Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Concrete Methods Modifier and Type Method Description double
getAzimuth()
Returns the azimuth.CoordinateReferenceSystem
getCoordinateReferenceSystem()
Returns the coordinate reference system for all methods working onPosition
objects.Point2D
getDestinationGeographicPoint()
Returns the destination point.Position
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 onPoint2D
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.Position
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.



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 thePosition
objects. Since:
 2.2


Method Detail

getCoordinateReferenceSystem
public CoordinateReferenceSystem getCoordinateReferenceSystem()
Returns the coordinate reference system for all methods working onPosition
objects. This is the CRS specified at construction time. Returns:
 The CRS for all
Position
s.  Since:
 2.2

getGeographicCRS
public GeographicCRS getGeographicCRS()
Returns the geographic coordinate reference system for all methods working onPoint2D
objects. This is inferred from the CRS specified at construction time. Returns:
 The CRS for
Point2D
s.  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 Position 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 timegetAzimuth()
orgetOrthodromicDistance()
are invoked. Parameters:
longitude
 The longitude in decimal degreeslatitude
 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 asetDestinationGeographicPoint(...)
method, except ifsetDirection(...)
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 Position 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 timegetDestinationGeographicPoint()
is invoked. Parameters:
azimuth
 The azimuth in decimal degreesdistance
 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 tosetDirection(azimuth,distance)
, except ifsetDestinationGeographicPoint(...)
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 tosetDirection(azimuth,distance)
, except ifsetDestinationGeographicPoint(...)
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

