Package lejos.hardware.gps

Class Coordinates

java.lang.Object

lejos.hardware.gps.Coordinates

public class Coordinates
extends java.lang.Object

This class has been designed to manage coordinates using JSR-179 Location API http://www.jcp.org/en/jsr/detail?id=179

Field Summary

Fields

Modifier and Type	Field and Description
private double	altitude
(package private) static float	calculatedAzimuth
(package private) static float	calculatedDistance
static int	DD_MM Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute See Also:Constant Field Values
static int	DD_MM_SS Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second See Also:Constant Field Values
(package private) static double	EARTH_RADIUS
private double	latitude
private double	longitude

Constructor Summary

Constructors

Constructor and Description
Coordinates(double latitude, double longitude)
Coordinates(double latitude, double longitude, double altitude) Create a Coordinate object with 3 parameters: latitude, longitude and altitude

Method Summary

Modifier and Type	Method and Description
double	azimuthTo(Coordinates to) Calculates the azimuth between the two points according to the ellipsoid model of WGS84.
private static void	calculateDistanceAndAzimuth(double d, double d1, double d2, double d3)
static java.lang.String	convert(double coordinate, int outputType) UNTESTED as of April 7, 2009 - BB / /** Converts a double representation of a coordinate with decimal degrees into a string representation.
static double	convert(java.lang.String coordinate) Converts a String representation of a coordinate into the double representation as used in this API.
private static boolean	convertIsValidChar(char element) Helper method for convert(String)
private static java.lang.String[]	convertSplit(java.lang.String in) Helper method for convert(String)
double	distance(Coordinates to) Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84.
private static java.lang.String	dropTrailingZeros(int number) Takes an integer and removes trailing zeros.
double	getAltitude() Altitude above mean sea level.
double	getLatitude() Returns the latitude component of this coordinate.
double	getLongitude() Returns the longitude component of this coordinate.
private static double	mod(double d, double d1)
void	setAltitude(double altitude)
void	setLatitude(double latitude)
void	setLongitude(double longitude)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

latitude

private double latitude

longitude

private double longitude

altitude

private double altitude

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

See Also:

Constant Field Values

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

See Also:

Constant Field Values

EARTH_RADIUS

static final double EARTH_RADIUS

See Also:

Constant Field Values

calculatedDistance

static float calculatedDistance

calculatedAzimuth

static float calculatedAzimuth

Constructor Detail

Coordinates

public Coordinates(double latitude,
                   double longitude,
                   double altitude)

Create a Coordinate object with 3 parameters: latitude, longitude and altitude

Parameters:

latitude -

longitude -

altitude -

Coordinates

public Coordinates(double latitude,
                   double longitude)

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)

setLatitude

public void setLatitude(double latitude)

setLongitude

public void setLongitude(double longitude)

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)

setAltitude

public void setAltitude(double altitude)

getAltitude

public double getAltitude()

Altitude above mean sea level.

Returns:

the altitude

azimuthTo

public double 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.

The azimuth (in degrees) increases clockwise. On this coordinate system, north is 0 degrees, east is 90 degrees, south is 180 degrees, and west is 270 degrees.

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.

convert

public static java.lang.String convert(double coordinate,
                                       int outputType)
                                throws java.lang.IllegalArgumentException

UNTESTED as of April 7, 2009 - BB / /** 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. The implementation shall provide as many significant digits for the decimal fractions as are allowed by the string syntax definition.

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:

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

dropTrailingZeros

private static java.lang.String dropTrailingZeros(int number)

Takes an integer and removes trailing zeros.

Parameters:

number - must be positive

Returns:

the number as a String, with trailing zeros removed. Returns null if the number was zero or negative.

convert

public static double convert(java.lang.String coordinate)
                      throws java.lang.IllegalArgumentException,
                             java.lang.NullPointerException

Converts a String representation of a coordinate into the double representation as used in this API. There are two string syntaxes supported:

1. Degrees, minutes, seconds and decimal fractions of seconds. This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179, 179] and the minutes and seconds are within the range [0, 59], or the degrees is -180 and the minutes, seconds and decimal fractions are 0:

coordinate = degrees ":" minutes ":" seconds "." decimalfrac | degrees ":" minutes ":" seconds | degrees ":" minutes
degrees = degreedigits | "-" degreedigits
degreedigits = digit | nonzerodigit digit | "1" digit digit
minutes = minsecfirstdigit digit
seconds = minsecfirstdigit digit
decimalfrac = 1*3digit
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
nonzerodigit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
minsecfirstdigit = "0" | "1" | "2" | "3" | "4" | "5"

2. Degrees, minutes and decimal fractions of minutes. This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179, 179] and the minutes are within the range [0, 59], or the degrees is -180 and the minutes and decimal fractions are 0:

coordinate = degrees ":" minutes "." decimalfrac | degrees ":" minutes
degrees = degreedigits | "-" degreedigits
degreedigits = digit | nonzerodigit digit | "1" digit digit
minutes = minsecfirstdigit digit
decimalfrac = 1*5digit
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
nonzerodigit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
minsecfirstdigit = "0" | "1" | "2" | "3" | "4" | "5"

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:

java.lang.IllegalArgumentException - if the coordinate input parameter does not comply with the defined syntax for the specified types

java.lang.NullPointerException - if the coordinate string is null convert

convertIsValidChar

private static boolean convertIsValidChar(char element)

Helper method for convert(String)

Parameters:

element -

Returns:

convertSplit

private static java.lang.String[] convertSplit(java.lang.String in)
                                        throws java.lang.IllegalArgumentException

Helper method for convert(String)

Parameters:

in -

Returns:

Throws:

java.lang.IllegalArgumentException

distance

public double 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.36% of the correct result.

Parameters:

to - the point to calculate the geodetic to

Returns:

the distance in meters

calculateDistanceAndAzimuth

private static void calculateDistanceAndAzimuth(double d,
                                                double d1,
                                                double d2,
                                                double d3)

mod

private static double mod(double d,
                          double d1)