com.cinterion.location

Class Coordinates

java.lang.Object

com.cinterion.location.Coordinates

Direct Known Subclasses:

QualifiedCoordinates

public class Coordinates
extends Object

The Coordinates class can hold coordinates for latitude, longitude and altitude. The coordinates are defined with the World Geodetic System 1984 (WGS84).

There are methods for converting between a string coordinate representation and the representation used in this class.

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
Coordinates(double latitude, double longitude, float altitude) Constructor for a new Coordinates object.

Method Summary

Methods

Modifier and Type	Method and Description
float	azimuthTo(Coordinates to) Calculates the azimuth between the two points according to the ellipsoid model of WGS84.
static String	convert(double coordinate, int outputType) Converts a double representation of a coordinate with decimal degrees into a string representation.
static double	convert(String coordinate) Converts a String representation of a coordinate into the double representation used by this class.
float	distance(Coordinates to) Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84.
float	getAltitude() Returns the altitude.
double	getLatitude() Returns the latitude (given in WGS84).
double	getLongitude() Returns the longitude (given in WGS84).
void	setAltitude(float altitude) Sets altitude.
void	setLatitude(double latitude) Sets the latitude.
void	setLongitude(double longitude) Sets the longitude.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, 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)

Constructor for a new Coordinates object.

The coordinate values are given in the World Geodetic System 1984 (WGS84).

The altitude can be set to unknown with Float.NaN

Parameters:

latitude - latitude, range is from -90.0 to 90.0.

longitude - longitude, range is from -180.0 to 180.0.

altitude - altitude in meters, defined as height above the WGS84 ellipsoid. Can be set to unknown with Float.NaN

Throws:

IllegalArgumentException - if an input parameter is out of the valid range

Method Detail

getLatitude

public double getLatitude()

Returns the latitude (given in WGS84).

Returns:

latitude

See Also:

setLatitude(double)

getLongitude

public double getLongitude()

Returns the longitude (given in WGS84).

Returns:

longitude

See Also:

setLongitude(double)

getAltitude

public float getAltitude()

Returns the altitude. It is defined to mean height above the WGS84 reference ellipsoid. Float.NaN indicates, that the altitude is not available.

Returns:

the altitude in meters above the reference ellipsoid

See Also:

setAltitude(float)

setAltitude

public void setAltitude(float altitude)

Sets altitude.

Parameters:

altitude - the altitude of the location in meters, defined as height above the WGS84 ellipsoid. Float.NaN indicates, that the altitude is not available.

See Also:

getAltitude()

setLatitude

public void setLatitude(double latitude)

Sets the latitude. 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:

IllegalArgumentException - if latitude is out of the valid range

See Also:

getLatitude()

setLongitude

public void setLongitude(double longitude)

Sets the longitude. 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:

IllegalArgumentException - if longitude is out of the valid range

See Also:

getLongitude()

convert

public static double convert(String coordinate)

Converts a String representation of a coordinate into the double representation used by this class.

There are two string syntaxes supported:

1. "Degrees:minutes:seconds.decimal fractions of seconds"

2. "Degrees:minutes.decimal fractions of minutes"

For example, for the double value of the coordinate 61.51d, the corresponding syntax 1 string is "61:30:36" and the corresponding syntax 2 string is "61:30.6".

Parameters:

coordinate - a String in either of the two representation specified above

Returns:

a double value with decimal degrees that matches the string representation given as the parameter

Throws:

IllegalArgumentException - if the coordinate input parameter does not comply with the defined syntax for the indicated type

NullPointerException - if the coordinate string is null

convert

public static String convert(double coordinate,
             int outputType)

Converts a double representation of a coordinate with decimal degrees into a string representation.

There are string syntaxes supported are the same as for the convert(String) method.

Parameters:

coordinate - a double representation of a coordinate

outputType - identifier of the type of the string representation wanted for output The constant DD_MM_SS identifies the syntax 1 and the constant DD_MM identifies the syntax 2.

Returns:

a string representation of the coordinate in a representation indicated by the parameter

Throws:

IllegalArgumentException - if the outputType is not one of the two constant values defined in this class or if the coordinate value is not within the range [-180.0, 180.0) or is Double.NaN

See Also:

convert(String)

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.

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:

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.

Parameters:

to - the Coordinates of the destination

Returns:

the distance to the destination in meters

Throws:

NullPointerException - if the parameter is null