org.hermit.geo
Class Position

java.lang.Object
  extended by org.hermit.geo.Position

public class Position
extends java.lang.Object

This class represents a geographic position -- ie. a latitude and longitude. It provides utility methods for the common geodetic operations of finding distance and azimuth between points, or projecting to a point given a distance and azimuth. The geodetic operations in this class are based on a simple spherical model of the Earth, using the haversine formulae; this is fast, and provides accuracy of about 0.5%, which will be adequate for many purposes. Users desiring greater accuracy should use the VincentyCalculator subclass. References:

Author:
Ian Cameron Smith

Field Summary
static Position UNKNOWN
          Constant representing an unknown position.
 
Constructor Summary
Position(double latRadians, double lonRadians)
          Create a Position from a geographic latitude and longitude.
Position(Position pos)
          Create a Position from a Position.
 
Method Summary
 Azimuth azimuth(Position pos)
          Calculate the azimuth (bearing) from this position to another, using the haversine formula, which is based on a spherical approximation of the Earth.
 Distance distance(Position pos)
          Calculate the distance between this position and another, using the haversine formula, which is based on a spherical approximation of the Earth.
 java.lang.String formatDegMin()
          Format this position for user display in degrees and minutes.
 java.lang.String formatDegMinSec()
          Format this position for user display in degrees and minutes.
static Position fromDegrees(double latDegrees, double lonDegrees)
          Create a Position from a geographic latitude and longitude given in degrees.
 double getCentreDistance()
          Get the distance from the centre of the Earth to this Position.
 double getGeocentricLat()
          Get the geocentric latitude of this Position in radians.
 double getLatDegs()
          Get the geographic latitude of this Position in degrees.
 double getLatRads()
          Get the geographic latitude of this Position in radians.
 double getLonDegs()
          Get the longitude of this Position in degrees.
 double getLonRads()
          Get the longitude of this Position in radians.
 Distance latDistance(double lat)
          Calculate the distance between this position and a given latitude, based on a spherical approximation of the Earth.
 Position offset(Distance distance, Azimuth azimuth)
          Calculate a second position given its offset from this one, using the current geodetic calculator -- see GeoCalculator.
 Position offset(Vector vector)
          Calculate a second position given its offset from this one, using the current geodetic calculator -- see GeoCalculator.
 java.lang.String toString()
          Format this position as a String.
 Vector vector(Position pos)
          Calculate the distance and azimuth from this position to another, using the haversine formula, which is based on a spherical approximation of the Earth.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

UNKNOWN

public static final Position UNKNOWN
Constant representing an unknown position.

Constructor Detail

Position

public Position(double latRadians,
                double lonRadians)
Create a Position from a geographic latitude and longitude.

Parameters:
latRadians - Geographic latitude in radians of the desired position, positive north.
lonRadians - Longitude in radians of the desired position, positive east.

Position

public Position(Position pos)
Create a Position from a Position. This is useful for converting between subclasses and superclasses.

Parameters:
pos - The Position to copy.
Method Detail

fromDegrees

public static Position fromDegrees(double latDegrees,
                                   double lonDegrees)
Create a Position from a geographic latitude and longitude given in degrees.

Parameters:
latDegrees - Geographic latitude in degrees of the desired position, positive north.
lonDegrees - Longitude in degrees of the desired position, positive east.
Returns:
The new Position.

getLatRads

public double getLatRads()
Get the geographic latitude of this Position in radians.

Returns:
The geographic latitude of this Position in radians, positive north. NaN if this is UNKNOWN.

getGeocentricLat

public double getGeocentricLat()
Get the geocentric latitude of this Position in radians.

From AA chapter 11.

Returns:
The geocentric latitude of this Position in radians, positive north. NaN if this is UNKNOWN.

getLonRads

public double getLonRads()
Get the longitude of this Position in radians.

Returns:
The longitude of this Position in radians, positive east. NaN if this is UNKNOWN.

getLatDegs

public double getLatDegs()
Get the geographic latitude of this Position in degrees.

Returns:
The geographic latitude of this Position in degrees, positive north. NaN if this is UNKNOWN.

getLonDegs

public double getLonDegs()
Get the longitude of this Position in degrees.

Returns:
The longitude of this Position in degrees, positive east. NaN if this is UNKNOWN.

getCentreDistance

public double getCentreDistance()
Get the distance from the centre of the Earth to this Position.

From AA chapter 11.

Returns:
The distance to the centre of the Earth, in units of EQUATORIAL_RADIUS. NaN if this is UNKNOWN.

vector

public Vector vector(Position pos)
Calculate the distance and azimuth from this position to another, using the haversine formula, which is based on a spherical approximation of the Earth. This should give an accuracy within 0.5% or so. In some subclasses, this function may be significantly faster than calling distance(pos) and azimuth(pos).

Parameters:
pos - Position to calculate the vector to.
Returns:
The Vector to the given position. null if either position is UNKNOWN.

distance

public Distance distance(Position pos)
Calculate the distance between this position and another, using the haversine formula, which is based on a spherical approximation of the Earth. This should give an accuracy within 0.5% or so.

Parameters:
pos - Position to calculate the distance to.
Returns:
The distance of pos from this Position. null if either position is UNKNOWN.

latDistance

public Distance latDistance(double lat)
Calculate the distance between this position and a given latitude, based on a spherical approximation of the Earth. This should give an accuracy within 0.5% or so.

Parameters:
lat - Latitude in radians to calculate the distance to.
Returns:
The distance of this Position from lat. null if this position is UNKNOWN.

azimuth

public Azimuth azimuth(Position pos)
Calculate the azimuth (bearing) from this position to another, using the haversine formula, which is based on a spherical approximation of the Earth. This should give an accuracy within 0.5% or so.

Parameters:
pos - Position to calculate the azimuth to.
Returns:
The azimuth of pos from this Position. null if either position is UNKNOWN.

offset

public Position offset(Vector vector)
Calculate a second position given its offset from this one, using the current geodetic calculator -- see GeoCalculator.

Parameters:
vector - The Vector to the desired position.
Returns:
The position given by the azimuth and distance from this one. Returns null if the result could not be computed, including if this position is UNKNOWN.

offset

public Position offset(Distance distance,
                       Azimuth azimuth)
Calculate a second position given its offset from this one, using the current geodetic calculator -- see GeoCalculator.

Parameters:
distance - The Distance to the desired position.
azimuth - The Azimuth to the desired position.
Returns:
The position given by the azimuth and distance from this one. Returns null if the result could not be computed, including if this position is UNKNOWN.

formatDegMin

public java.lang.String formatDegMin()
Format this position for user display in degrees and minutes.

Returns:
The formatted angle.

formatDegMinSec

public java.lang.String formatDegMinSec()
Format this position for user display in degrees and minutes.

Returns:
The formatted angle.

toString

public java.lang.String toString()
Format this position as a String.

Overrides:
toString in class java.lang.Object
Returns:
This position as a string, in degrees and minutes.