* The org.osgi.util.measurement.Measurement class is used to
* represent the values that make up a position.
*
*
* A given position object may lack any of it's components, i.e. the altitude * may not be known. Such missing values will be represented by null. *
* Position does not override the implementation of either equals() or
* hashCode() because it is not clear how missing values should be handled. It
* is up to the user of a position to determine how best to compare two position
* objects. A Position object is immutable.
*/
public class Position {
private Measurement altitude;
private Measurement longitude;
private Measurement latitude;
private Measurement speed;
private Measurement track;
/**
* Contructs a Position object with the given values.
*
* @param lat a Measurement object specifying the latitude in
* radians, or null
* @param lon a Measurement object specifying the longitude in
* radians, or null
* @param alt a Measurement object specifying the altitude in
* meters, or null
* @param speed a Measurement object specifying the speed in
* meters per second, or null
* @param track a Measurement object specifying the track in
* radians, or null
*/
public Position(Measurement lat, Measurement lon, Measurement alt,
Measurement speed, Measurement track) {
if (lat != null) {
if (!Unit.rad.equals(lat.getUnit())) {
throw new IllegalArgumentException("Invalid Latitude");
}
this.latitude = lat;
}
if (lon != null) {
if (!Unit.rad.equals(lon.getUnit())) {
throw new IllegalArgumentException("Invalid Longitude");
}
this.longitude = lon;
}
normalizeLatLon();
if (alt != null) {
if (!Unit.m.equals(alt.getUnit())) {
throw new IllegalArgumentException("Invalid Altitude");
}
this.altitude = alt;
}
if (speed != null) {
if (!Unit.m_s.equals(speed.getUnit())) {
throw new IllegalArgumentException("Invalid Speed");
}
this.speed = speed;
}
if (track != null) {
if (!Unit.rad.equals(track.getUnit())) {
throw new IllegalArgumentException("Invalid Track");
}
this.track = normalizeTrack(track);
}
}
/**
* Returns the altitude of this position in meters.
*
* @return a Measurement object in Unit.m representing
* the altitude in meters above the ellipsoid null if the
* altitude is not known.
*/
public Measurement getAltitude() {
return altitude;
}
/**
* Returns the longitude of this position in radians.
*
* @return a Measurement object in Unit.rad
* representing the longitude, or null if the longitude
* is not known.
*/
public Measurement getLongitude() {
return longitude;
}
/**
* Returns the latitude of this position in radians.
*
* @return a Measurement object in Unit.rad
* representing the latitude, or null if the latitude is
* not known..
*/
public Measurement getLatitude() {
return latitude;
}
/**
* Returns the ground speed of this position in meters per second.
*
* @return a Measurement object in Unit.m_s
* representing the speed, or null if the speed is not
* known..
*/
public Measurement getSpeed() {
return speed;
}
/**
* Returns the track of this position in radians as a compass heading. The
* track is the extrapolation of previous previously measured positions to a
* future position.
*
* @return a Measurement object in Unit.rad
* representing the track, or null if the track is not
* known..
*/
public Measurement getTrack() {
return track;
}
private static final double LON_RANGE = Math.PI;
private static final double LAT_RANGE = Math.PI / 2.0D;
/**
* Verify the longitude and latitude parameters so they fit the normal
* coordinate system. A latitude is between -90 (south) and +90 (north). A A
* longitude is between -180 (Western hemisphere) and +180 (eastern
* hemisphere). This method first normalizes the latitude and longitude
* between +/- 180. If the |latitude| > 90, then the longitude is added 180
* and the latitude is normalized to fit +/-90. (Example are with degrees
* though radians are used)
* No normalization takes place when either lon or lat is null.
*/
private void normalizeLatLon() {
if (longitude == null || latitude == null)
return;
double dlon = longitude.getValue();
double dlat = latitude.getValue();
if (dlon >= -LON_RANGE && dlon < LON_RANGE && dlat >= -LAT_RANGE
&& dlat <= LAT_RANGE)
return;
dlon = normalize(dlon, LON_RANGE);
dlat = normalize(dlat, LAT_RANGE * 2.0D); // First over 180 degree
// Check if we have to move to other side of the earth
if (dlat > LAT_RANGE || dlat < -LAT_RANGE) {
dlon = normalize(dlon - LON_RANGE, LON_RANGE);
dlat = normalize((LAT_RANGE * 2.0D) - dlat, LAT_RANGE);
}
longitude = new Measurement(dlon, longitude.getError(), longitude
.getUnit(), longitude.getTime());
latitude = new Measurement(dlat, latitude.getError(), latitude
.getUnit(), latitude.getTime());
}
/**
* This function normalizes the a value according to a range. This is not
* simple modulo (as I thought when I started), but requires some special
* handling. For positive numbers we subtract 2*range from the number so
* that end up between -/+ range. For negative numbers we add this value.
* For example, if the value is 270 and the range is +/- 180. Then sign=1 so
* the (int) factor becomes 270+180/360 = 1. This means that 270-360=-90 is
* the result. (degrees are only used to make it easier to understand, this
* function is agnostic for radians/degrees). The result will be in
* [range,range> The algorithm is not very fast, but it handling the
* [> ranges made it very messy using integer arithmetic, and this is
* very readable. Note that it is highly unlikely that this method is called
* in normal situations. Normally input values to position are already
* normalized because they come from a GPS. And this is much more readable.
*
* @param value The value that needs adjusting
* @param range -range = < value < range
*/
private double normalize(double value, double range) {
double twiceRange = 2.0D * range;
while (value >= range) {
value -= twiceRange;
}
while (value < -range) {
value += twiceRange;
}
return value;
}
private static final double TRACK_RANGE = Math.PI * 2.0D;
/**
* Normalize track to be a value such that: 0 <= value < +2PI. This
* corresponds to 0 deg to +360 deg. 0 is North 0.5*PI is East PI is South
* 1.5*PI is West
*
* @param track Value to be normalized
* @return Normalized value
*/
private Measurement normalizeTrack(Measurement track) {
double value = track.getValue();
if ((0.0D <= value) && (value < TRACK_RANGE)) {
return track; /* value is already normalized */
}
value %= TRACK_RANGE;
if (value < 0.0D) {
value += TRACK_RANGE;
}
return new Measurement(value, track.getError(), track.getUnit(), track
.getTime());
}
}