org.geotools.referencing
Class GeodeticCalculator

java.lang.Object
  org.geotools.referencing.GeodeticCalculator

public class GeodeticCalculator

extends java.lang.Object

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

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

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

Since:

2.1

Version:

$Id: GeodeticCalculator.java 18776 2006-03-22 11:36:21Z desruisseaux $

Author:

Daniele Franzoni, Martin Desruisseaux

Constructor Summary

GeodeticCalculator()
Constructs a new geodetic calculator associated with the WGS84 ellipsoid.

GeodeticCalculator(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
Constructs a new geodetic calculator expecting coordinates in the supplied CRS.

GeodeticCalculator(org.opengis.referencing.datum.Ellipsoid ellipsoid)
Constructs a new geodetic calculator associated with the specified ellipsoid.

Method Summary

java.awt.geom.Point2D	getAnchorPoint() Returns the anchor point.
org.opengis.spatialschema.geometry.DirectPosition	getAnchorPosition() Returns the anchor position in user coordinates, which doesn't need to be geographic.
double	getAzimuth() Returns the azimuth.
org.opengis.referencing.crs.CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the coordinate reference system for all methods working on Position objects.
java.awt.geom.Point2D	getDestinationPoint() Returns the destination point.
org.opengis.spatialschema.geometry.DirectPosition	getDestinationPosition() Returns the destination position in user coordinates, which doesn't need to be geographic.
org.opengis.referencing.datum.Ellipsoid	getEllipsoid() Returns the referenced ellipsoid.
java.awt.Shape	getGeodeticCurve() Calculates the geodetic curve between two points in the referenced ellipsoid.
java.awt.Shape	getGeodeticCurve(int numberOfPoints) Calculates the geodetic curve between two points in the referenced ellipsoid.
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.
void	setAnchorPoint(double longitude, double latitude) Set the anchor point.
void	setAnchorPoint(java.awt.geom.Point2D point) Set the anchor point.
void	setAnchorPosition(org.opengis.spatialschema.geometry.geometry.Position position) Set the anchor position in user coordinates, which doesn't need to be geographic.
void	setDestinationPoint(double longitude, double latitude) Set the destination point.
void	setDestinationPoint(java.awt.geom.Point2D point) Set the destination point.
void	setDestinationPosition(org.opengis.spatialschema.geometry.geometry.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 anchor point.
java.lang.String	toString() Returns a string representation of the current state of this calculator.

Methods inherited from class java.lang.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(org.opengis.referencing.datum.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 reference to the ellipsoid onto which calculates distances and azimuths.

GeodeticCalculator

public GeodeticCalculator(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
                   throws org.opengis.referencing.FactoryException

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.

Throws:

org.opengis.referencing.FactoryException - if no transform to a geodetic CRS can be created for the specified CRS.

Since:

2.2

Method Detail

getCoordinateReferenceSystem

public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem()

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

Since:

2.2

getEllipsoid

public org.opengis.referencing.datum.Ellipsoid getEllipsoid()

Returns the referenced ellipsoid.

Returns:

The referenced ellipsoid.

setAnchorPoint

public void setAnchorPoint(double longitude,
                           double latitude)
                    throws java.lang.IllegalArgumentException

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

Parameters:

longitude - The longitude in degrees between -180 and +180?

latitude - The latitude in degrees between -90 and +90?

Throws:

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

setAnchorPoint

public void setAnchorPoint(java.awt.geom.Point2D point)
                    throws java.lang.IllegalArgumentException

Set the anchor point. The x and y coordinates must be the longitude and latitude in degrees, respectively. This is a convenience method for setAnchorPoint(x,y).

Parameters:

point - The anchor point.

Throws:

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

setAnchorPosition

public void setAnchorPosition(org.opengis.spatialschema.geometry.geometry.Position position)
                       throws org.opengis.referencing.operation.TransformException

Set the anchor 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:

org.opengis.referencing.operation.TransformException - if the position can't be transformed.

Since:

2.2

getAnchorPoint

public java.awt.geom.Point2D getAnchorPoint()

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

Returns:

The anchor point.

getAnchorPosition

public org.opengis.spatialschema.geometry.DirectPosition getAnchorPosition()
                                                                    throws org.opengis.referencing.operation.TransformException

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

Throws:

org.opengis.referencing.operation.TransformException - if the position can't be transformed to user coordinates.

Since:

2.2

setDestinationPoint

public void setDestinationPoint(double longitude,
                                double latitude)
                         throws java.lang.IllegalArgumentException

Set the destination point. 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 degrees between -180 and +180?

latitude - The latgitude in degrees between -90 and +90?

Throws:

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

setDestinationPoint

public void setDestinationPoint(java.awt.geom.Point2D point)
                         throws java.lang.IllegalArgumentException

Set the destination point. The x and y coordinates must be the longitude and latitude in degrees, respectively. This is a convenience method for setDestinationPoint(x,y).

Parameters:

point - The destination point.

Throws:

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

setDestinationPosition

public void setDestinationPosition(org.opengis.spatialschema.geometry.geometry.Position position)
                            throws org.opengis.referencing.operation.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:

org.opengis.referencing.operation.TransformException - if the position can't be transformed.

Since:

2.2

getDestinationPoint

public java.awt.geom.Point2D getDestinationPoint()
                                          throws java.lang.IllegalStateException

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

Returns:

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

Throws:

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

getDestinationPosition

public org.opengis.spatialschema.geometry.DirectPosition getDestinationPosition()
                                                                         throws org.opengis.referencing.operation.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.

Throws:

org.opengis.referencing.operation.TransformException - if the position can't be transformed to user coordinates.

Since:

2.2

setDirection

public void setDirection(double azimuth,
                         double distance)
                  throws java.lang.IllegalArgumentException

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

Parameters:

azimuth - The azimuth in degrees from -180? to 180?.

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

Throws:

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

See Also:

getAzimuth(), getOrthodromicDistance()

getAzimuth

public double getAzimuth()
                  throws java.lang.IllegalStateException

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

Returns:

The azimuth, in degrees from -180? to +180?.

Throws:

java.lang.IllegalStateException - if the destination point has not been set.

getOrthodromicDistance

public double getOrthodromicDistance()
                              throws java.lang.IllegalStateException

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

Returns:

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

Throws:

java.lang.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 degrees).

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

Returns:

Returned the meridian arc length between latitude1 and latitude2

getGeodeticCurve

public java.awt.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 anchor 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 anchor point to the destination point.

To Do:

We should check for cases where the path cross the 90?N, 90?S, 90?E or 90?W boundaries.

getGeodeticCurve

public java.awt.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 anchor point to the destination point.

Returns:

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

toString

public java.lang.String toString()

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