org.j4me.bluetoothgps
Class Coordinates

java.lang.Object
  extended by org.j4me.bluetoothgps.Coordinates
Direct Known Subclasses:
QualifiedCoordinates

public class Coordinates
extends java.lang.Object

The Coordinates class represents coordinates as latitude-longitude-altitude values. The latitude and longitude values are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds). The coordinates are given using the WGS84 datum.

This class also provides convenience methods for converting between a string coordinate representation and the double representation used in this class.


Field Summary
static int DD_MM
          Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute.
static int DD_MM_SS
          Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second.
 
Constructor Summary
Coordinates(double latitude, double longitude, float altitude)
          Constructs a new Coordinates object with the values specified.
 
Method Summary
 float azimuthTo(Coordinates to)
          Calculates the azimuth between the two points according to the ellipsoid model of WGS84.
 float distance(Coordinates to)
          Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84.
 boolean equals(java.lang.Object other)
          Compares if two Coordinates object reference the same location.
 float getAltitude()
          Returns the altitude component of this coordinate.
 double getLatitude()
          Returns the latitude component of this coordinate.
 double getLongitude()
          Returns the longitude component of this coordinate.
 void setAltitude(float altitude)
          Sets the geodetic altitude for this point.
 void setLatitude(double latitude)
          Sets the geodetic latitude for this point.
 void setLongitude(double longitude)
          Sets the geodetic longitude for this point.
 java.lang.String toString()
          Provides a string representation of the coordinates.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DD_MM_SS

public static final int DD_MM_SS
Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second.

See Also:
Constant Field Values

DD_MM

public static final int DD_MM
Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute.

See Also:
Constant Field Values
Constructor Detail

Coordinates

public Coordinates(double latitude,
                   double longitude,
                   float altitude)
Constructs a new Coordinates object with the values specified. The latitude and longitude parameters are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds).

The coordinate values always apply to the WGS84 datum.

The Float.NaN value can be used for altitude to indicate that altitude is not known.

Parameters:
latitude - - the latitude of the location. Valid range: [-90.0, 90.0]. Positive values indicate northern latitude and negative values southern latitude.
longitude - - the longitude of the location. Valid range: [-180.0, 180.0). Positive values indicate eastern longitude and negative values western longitude.
altitude - - the altitude of the location in meters, defined as height above WGS84 ellipsoid. Float.Nan can be used to indicate that altitude is not known.
Throws:
java.lang.IllegalArgumentException - - if an input parameter is out of the valid range.
Method Detail

getLatitude

public double getLatitude()
Returns the latitude component of this coordinate. Positive values indicate northern latitude and negative values southern latitude.

The latitude is given in WGS84 datum.

Returns:
the latitude in degrees
See Also:
setLatitude(double)

getLongitude

public double getLongitude()
Returns the longitude component of this coordinate. Positive values indicate eastern longitude and negative values western longitude.

The longitude is given in WGS84 datum.

Returns:
the longitude in degrees
See Also:
setLongitude(double)

getAltitude

public float getAltitude()
Returns the altitude component of this coordinate. Altitude is defined to mean height above the WGS84 reference ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.Nan that no altitude is not available.

Returns:
the altitude in meters above the reference ellipsoid
See Also:
setAltitude(float)

setAltitude

public void setAltitude(float altitude)
Sets the geodetic altitude for this point.

Parameters:
altitude - - the altitude of the location in meters, defined as height above the WGS84 ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.Nan that no altitude is not available
See Also:
getAltitude()

setLatitude

public void setLatitude(double latitude)
Sets the geodetic latitude for this point. Latitude is given as a double expressing the latitude in degrees in the WGS84 datum.

Parameters:
latitude - - the latitude component of this location in degrees. Valid range: [-90.0, 90.0].
Throws:
java.lang.IllegalArgumentException - - if latitude is out of the valid range
See Also:
getLatitude()

setLongitude

public void setLongitude(double longitude)
Sets the geodetic longitude for this point. Longitude is given as a double expressing the longitude in degrees in the WGS84 datum.

Parameters:
longitude - - the longitude of the location in degrees. Valid range: [-180.0, 180.0)
Throws:
java.lang.IllegalArgumentException - - if longitude is out of the valid range
See Also:
getLongitude()

azimuthTo

public float azimuthTo(Coordinates to)
Calculates the azimuth between the two points according to the ellipsoid model of WGS84. The azimuth is relative to true north. The Coordinates object on which this method is called is considered the origin for the calculation and the Coordinates object passed as a parameter is the destination which the azimuth is calculated to. When the origin is the North pole and the destination is not the North pole, this method returns 180.0. When the origin is the South pole and the destination is not the South pole, this method returns 0.0. If the origin is equal to the destination, this method returns 0.0. The implementation shall calculate the result as exactly as it can. However, it is required that the result is within 1 degree of the correct result.

Parameters:
to - - the Coordinates of the destination
Returns:
the azimuth to the destination in degrees. Result is within the range [0.0 ,360.0).
Throws:
java.lang.NullPointerException - - if the parameter is null

distance

public float distance(Coordinates to)
Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84. Altitude is neglected from calculations.

The implementation shall calculate this as exactly as it can. However, it is required that the result is within 0.35% of the correct result.

Parameters:
to - - the Coordinates of the destination
Returns:
the distance to the destination in meters
Throws:
java.lang.NullPointerException - - if the parameter is null

equals

public boolean equals(java.lang.Object other)
Compares if two Coordinates object reference the same location.

Overrides:
equals in class java.lang.Object
Parameters:
other - is another Coordinates object.
Returns:
true if the two reference the same location; false otherwise.

toString

public java.lang.String toString()
Provides a string representation of the coordinates.

Overrides:
toString in class java.lang.Object
Returns:
A string such as "79.32°N 169.8°W 25.7m" where the words are the latitude, longitude, and altitude (in meters).