gov.nasa.worldwind.geom
Class LatLon

java.lang.Object
  gov.nasa.worldwind.geom.LatLon

Direct Known Subclasses:

Position

public class LatLon
extends Object

Represents a point on the two-dimensional surface of a globe. Latitude is the degrees North and ranges between [-90, 90], while longitude refers to degrees East, and ranges between (-180, 180].

Instances of LatLon are immutable.

Field Summary

Angle	latitude
Angle	longitude
static LatLon	ZERO

Constructor Summary

LatLon(Angle latitude, Angle longitude)
Constructs a new LatLon from two angles.

LatLon(LatLon latLon)

Method Summary

LatLon	add(LatLon that)
LatLon	add(Position that)
double[]	asDegreesArray() Returns an array of this object's latitude and longitude in degrees.
double[]	asRadiansArray() Returns an array of this object's latitude and longitude in radians.
static List<LatLon>	computeShiftedLocations(Position oldLocation, Position newLocation, Iterable<? extends LatLon> locations) Computes a new set of locations translated from a specified location to a new location.
static double	ellipsoidalDistance(LatLon p1, LatLon p2, double equatorialRadius, double polarRadius) Computes the distance between two points on an ellipsoid iteratively.
static Angle	ellipsoidalForwardAzimuth(LatLon p1, LatLon p2, double equatorialRadius, double polarRadius) Compute the forward azimuth between two positions
static boolean	equals(LatLon a, LatLon b)
boolean	equals(Object o)
static LatLon	fromDegrees(double latitude, double longitude) Factory method for obtaining a new LatLon from two angles expressed in degrees.
static LatLon	fromRadians(double latitude, double longitude) Factor method for obtaining a new LatLon from two angles expressed in radians.
static Angle	getAverageDistance(Iterable<? extends LatLon> locations) Compute the average rhumb distance between locations.
Angle	getLatitude() Obtains the latitude of this LatLon.
Angle	getLongitude() Obtains the longitude of this LatLon.
static LatLon[]	greatCircleArcExtremeLocations(Iterable<? extends LatLon> locations) Returns two locations with the most extreme latitudes on the sequence of great circle arcs defined by each pair of locations in the specified iterable.
static LatLon[]	greatCircleArcExtremeLocations(LatLon begin, LatLon end) Returns two locations with the most extreme latitudes on the great circle arc defined by, and limited to, the two locations.
static Angle	greatCircleAzimuth(LatLon p1, LatLon p2) Computes the azimuth angle (clockwise from North) that points from the first location to the second location.
static Angle	greatCircleDistance(LatLon p1, LatLon p2) Computes the great circle angular distance between two locations.
static LatLon	greatCircleEndPosition(LatLon p, Angle greatCircleAzimuth, Angle pathLength) Computes the location on a great circle arc with the given starting location, azimuth, and arc distance.
static LatLon	greatCircleEndPosition(LatLon p, double greatCircleAzimuthRadians, double pathLengthRadians) Computes the location on a great circle arc with the given starting location, azimuth, and arc distance.
static LatLon[]	greatCircleExtremeLocations(LatLon location, Angle azimuth) Returns two locations with the most extreme latitudes on the great circle with the given starting location and azimuth.
int	hashCode()
static LatLon	interpolate(double amount, LatLon value1, LatLon value2) Returns the linear interpolation of value1 and value2, treating the geographic locations as simple 2D coordinate pairs.
static LatLon	interpolate(String pathType, double amount, LatLon value1, LatLon value2) Returns an interpolated location between value1 and value2, according to the specified path type.
static LatLon	interpolateGreatCircle(double amount, LatLon value1, LatLon value2) Returns the an interpolated location along the great-arc between value1 and value2.
static LatLon	interpolateRhumb(double amount, LatLon value1, LatLon value2) Returns the an interpolated location along the rhumb line between value1 and value2.
static Angle	linearAzimuth(LatLon p1, LatLon p2) Computes the azimuth angle (clockwise from North) of a linear path two locations.
static Angle	linearDistance(LatLon p1, LatLon p2) Computes the length of the linear path between two locations.
static LatLon	linearEndPosition(LatLon p, Angle linearAzimuth, Angle pathLength) Computes the location on a linear path given a starting location, azimuth, and arc distance along the line.
static boolean	locationsCrossDateLine(Iterable<? extends LatLon> locations)
static boolean	locationsCrossDateline(LatLon p1, LatLon p2)
static List<LatLon>	makeDatelineCrossingLocationsPositive(Iterable<? extends LatLon> locations) Transform the negative longitudes of a dateline-spanning location list to positive values that maintain the relationship with the other locations in the list.
LatLon	parseLatLon(String latLonString) Parses a string containing latitude and longitude coordinates in either Degrees-minutes-seconds or decimal degrees.
static Angle	rhumbAzimuth(LatLon p1, LatLon p2) Computes the azimuth angle (clockwise from North) of a rhumb line (a line of constant heading) between two locations.
static Angle	rhumbDistance(LatLon p1, LatLon p2) Computes the length of the rhumb line between two locations.
static LatLon	rhumbEndPosition(LatLon p, Angle rhumbAzimuth, Angle pathLength) Computes the location on a rhumb line with the given starting location, rhumb azimuth, and arc distance along the line.
static LatLon	rhumbEndPosition(LatLon p, double rhumbAzimuthRadians, double pathLengthRadians) Computes the location on a rhumb line with the given starting location, rhumb azimuth, and arc distance along the line.
LatLon	subtract(LatLon that)
LatLon	subtract(Position that)
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

latitude

public final Angle latitude

longitude

public final Angle longitude

ZERO

public static final LatLon ZERO

Constructor Detail

LatLon

public LatLon(Angle latitude,
              Angle longitude)

Constructs a new LatLon from two angles. Neither angle may be null.

Parameters:

latitude - latitude

longitude - longitude

Throws:

IllegalArgumentException - if latitude or longitude is null

LatLon

public LatLon(LatLon latLon)

Method Detail

add

public LatLon add(LatLon that)

add

public LatLon add(Position that)

asDegreesArray

public double[] asDegreesArray()

Returns an array of this object's latitude and longitude in degrees.

Returns:

the array of latitude and longitude, arranged in that order.

asRadiansArray

public double[] asRadiansArray()

Returns an array of this object's latitude and longitude in radians.

Returns:

the array of latitude and longitude, arranged in that order.

computeShiftedLocations

public static List<LatLon> computeShiftedLocations(Position oldLocation,
                                                   Position newLocation,
                                                   Iterable<? extends LatLon> locations)

Computes a new set of locations translated from a specified location to a new location.

Parameters:

oldLocation - the original reference location.

newLocation - the new reference location.

locations - the locations to translate.

Returns:

the translated locations, or null if the locations could not be translated.

Throws:

IllegalArgumentException - if any argument is null.

ellipsoidalDistance

public static double ellipsoidalDistance(LatLon p1,
                                         LatLon p2,
                                         double equatorialRadius,
                                         double polarRadius)

Computes the distance between two points on an ellipsoid iteratively.

NOTE: This method was copied from the UniData NetCDF Java library. http://www.unidata.ucar.edu/software/netcdf-java/

Algorithm from U.S. National Geodetic Survey, FORTRAN program "inverse," subroutine "INVER1," by L. PFEIFER and JOHN G. GERGEN. See http://www.ngs.noaa.gov/TOOLS/Inv_Fwd/Inv_Fwd.html

Original documentation: SOLUTION OF THE GEODETIC INVERSE PROBLEM AFTER T.VINCENTY MODIFIED RAINSFORD'S METHOD WITH HELMERT'S ELLIPTICAL TERMS EFFECTIVE IN ANY AZIMUTH AND AT ANY DISTANCE SHORT OF ANTIPODAL STANDPOINT/FOREPOINT MUST NOT BE THE GEOGRAPHIC POLE

Requires close to 1.4 E-5 seconds wall clock time per call on a 550 MHz Pentium with Linux 7.2.

Parameters:

p1 - first position

p2 - second position

equatorialRadius - the equatorial radius of the globe in meters

polarRadius - the polar radius of the globe in meters

Returns:

distance in meters between the two points

ellipsoidalForwardAzimuth

public static Angle ellipsoidalForwardAzimuth(LatLon p1,
                                              LatLon p2,
                                              double equatorialRadius,
                                              double polarRadius)

Compute the forward azimuth between two positions

Parameters:

p1 - first position

p2 - second position

equatorialRadius - the equatorial radius of the globe in meters

polarRadius - the polar radius of the globe in meters

Returns:

the azimuth

equals

public static boolean equals(LatLon a,
                             LatLon b)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

fromDegrees

public static LatLon fromDegrees(double latitude,
                                 double longitude)

Factory method for obtaining a new LatLon from two angles expressed in degrees.

Parameters:

latitude - in degrees

longitude - in degrees

Returns:

a new LatLon from the given angles, which are expressed as degrees

fromRadians

public static LatLon fromRadians(double latitude,
                                 double longitude)

Factor method for obtaining a new LatLon from two angles expressed in radians.

Parameters:

latitude - in radians

longitude - in radians

Returns:

a new LatLon from the given angles, which are expressed as radians

getAverageDistance

public static Angle getAverageDistance(Iterable<? extends LatLon> locations)

Compute the average rhumb distance between locations.

Parameters:

locations - Locations of which to compute average.

Returns:

Average rhumb line distance between locations, as an angular distance.

getLatitude

public final Angle getLatitude()

Obtains the latitude of this LatLon.

Returns:

this LatLon's latitude

getLongitude

public final Angle getLongitude()

Obtains the longitude of this LatLon.

Returns:

this LatLon's longitude

greatCircleArcExtremeLocations

public static LatLon[] greatCircleArcExtremeLocations(Iterable<? extends LatLon> locations)

Returns two locations with the most extreme latitudes on the sequence of great circle arcs defined by each pair of locations in the specified iterable.

Parameters:

locations - the pairs of locations defining a sequence of great circle arcs.

Returns:

two locations with the most extreme latitudes on the great circle arcs.

Throws:

IllegalArgumentException - if locations is null.

greatCircleArcExtremeLocations

public static LatLon[] greatCircleArcExtremeLocations(LatLon begin,
                                                      LatLon end)

Returns two locations with the most extreme latitudes on the great circle arc defined by, and limited to, the two locations.

Parameters:

begin - beginning location on the great circle arc.

end - ending location on the great circle arc.

Returns:

two locations with the most extreme latitudes on the great circle arc.

Throws:

IllegalArgumentException - if either begin or end are null.

greatCircleAzimuth

public static Angle greatCircleAzimuth(LatLon p1,
                                       LatLon p2)

Computes the azimuth angle (clockwise from North) that points from the first location to the second location. This angle can be used as the starting azimuth for a great circle arc that begins at the first location, and passes through the second location.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

Angle that points from the first location to the second location.

greatCircleDistance

public static Angle greatCircleDistance(LatLon p1,
                                        LatLon p2)

Computes the great circle angular distance between two locations. The return value gives the distance as the angle between the two positions on the pi radius circle. In radians, this angle is also the arc length of the segment between the two positions on that circle. To compute a distance in meters from this value, multiply it by the radius of the globe.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

the angular distance between the two locations. In radians, this value is the arc length on the radius pi circle.

greatCircleEndPosition

public static LatLon greatCircleEndPosition(LatLon p,
                                            Angle greatCircleAzimuth,
                                            Angle pathLength)

Computes the location on a great circle arc with the given starting location, azimuth, and arc distance.

Parameters:

p - LatLon of the starting location

greatCircleAzimuth - great circle azimuth angle (clockwise from North)

pathLength - arc distance to travel

Returns:

LatLon location on the great circle arc.

greatCircleEndPosition

public static LatLon greatCircleEndPosition(LatLon p,
                                            double greatCircleAzimuthRadians,
                                            double pathLengthRadians)

Computes the location on a great circle arc with the given starting location, azimuth, and arc distance.

Parameters:

p - LatLon of the starting location

greatCircleAzimuthRadians - great circle azimuth angle (clockwise from North), in radians

pathLengthRadians - arc distance to travel, in radians

Returns:

LatLon location on the great circle arc.

greatCircleExtremeLocations

public static LatLon[] greatCircleExtremeLocations(LatLon location,
                                                   Angle azimuth)

Returns two locations with the most extreme latitudes on the great circle with the given starting location and azimuth.

Parameters:

location - location on the great circle.

azimuth - great circle azimuth angle (clockwise from North).

Returns:

two locations where the great circle has its extreme latitudes.

Throws:

IllegalArgumentException - if either location or azimuth are null.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

interpolate

public static LatLon interpolate(double amount,
                                 LatLon value1,
                                 LatLon value2)

Returns the linear interpolation of value1 and value2, treating the geographic locations as simple 2D coordinate pairs.

Parameters:

amount - the interpolation factor

value1 - the first location.

value2 - the second location.

Returns:

the linear interpolation of value1 and value2.

Throws:

IllegalArgumentException - if either location is null.

interpolate

public static LatLon interpolate(String pathType,
                                 double amount,
                                 LatLon value1,
                                 LatLon value2)

Returns an interpolated location between value1 and value2, according to the specified path type. If the path type is AVKey.GREAT_CIRCLE this returns an interpolated value on the great arc that spans the two locations (see interpolateGreatCircle(double, LatLon, LatLon)). If the path type is AVKey.RHUMB_LINE or AVKey.LOXODROME this returns an interpolated value on the rhumb line that spans the two locations (see interpolateRhumb(double, LatLon, LatLon). Otherwise, this returns the linear interpolation of the two locations (see interpolate(double, LatLon, LatLon).

Parameters:

pathType - the path type used to interpolate between geographic locations.

amount - the interpolation factor

value1 - the first location.

value2 - the second location.

Returns:

an interpolated location between value1 and value2, according to the specified path type.

Throws:

IllegalArgumentException - if the path type or either location is null.

interpolateGreatCircle

public static LatLon interpolateGreatCircle(double amount,
                                            LatLon value1,
                                            LatLon value2)

Returns the an interpolated location along the great-arc between value1 and value2. The interpolation factor amount defines the weight given to each value, and is clamped to the range [0, 1]. If a is 0 or less, this returns value1. If amount is 1 or more, this returns value2. Otherwise, this returns the location on the great-arc between value1 and value2 corresponding to the specified interpolation factor.

Parameters:

amount - the interpolation factor

value1 - the first location.

value2 - the second location.

Returns:

an interpolated location along the great-arc between value1 and value2.

Throws:

IllegalArgumentException - if either location is null.

interpolateRhumb

public static LatLon interpolateRhumb(double amount,
                                      LatLon value1,
                                      LatLon value2)

Returns the an interpolated location along the rhumb line between value1 and value2. The interpolation factor amount defines the weight given to each value, and is clamped to the range [0, 1]. If a is 0 or less, this returns value1. If amount is 1 or more, this returns value2. Otherwise, this returns the location on the rhumb line between value1 and value2 corresponding to the specified interpolation factor.

Parameters:

amount - the interpolation factor

value1 - the first location.

value2 - the second location.

Returns:

an interpolated location along the rhumb line between value1 and value2

Throws:

IllegalArgumentException - if either location is null.

linearAzimuth

public static Angle linearAzimuth(LatLon p1,
                                  LatLon p2)

Computes the azimuth angle (clockwise from North) of a linear path two locations.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

azimuth Angle of a linear path between the two locations.

linearDistance

public static Angle linearDistance(LatLon p1,
                                   LatLon p2)

Computes the length of the linear path between two locations. The return value gives the distance as the angular distance between the two positions on the pi radius circle. In radians, this angle is also the arc length of the segment between the two positions on that circle. To compute a distance in meters from this value, multiply it by the radius of the globe.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

the arc length of the line between the two locations. In radians, this value is the arc length on the radius pi circle.

linearEndPosition

public static LatLon linearEndPosition(LatLon p,
                                       Angle linearAzimuth,
                                       Angle pathLength)

Computes the location on a linear path given a starting location, azimuth, and arc distance along the line. A linear path is determined by treating latitude and longitude as a rectangular grid. This type of path is a straight line in the equidistant cylindrical map projection (also called equirectangular).

Parameters:

p - LatLon of the starting location

linearAzimuth - azimuth angle (clockwise from North)

pathLength - arc distance to travel

Returns:

LatLon location on the line.

locationsCrossDateLine

public static boolean locationsCrossDateLine(Iterable<? extends LatLon> locations)

locationsCrossDateline

public static boolean locationsCrossDateline(LatLon p1,
                                             LatLon p2)

makeDatelineCrossingLocationsPositive

public static List<LatLon> makeDatelineCrossingLocationsPositive(Iterable<? extends LatLon> locations)

Transform the negative longitudes of a dateline-spanning location list to positive values that maintain the relationship with the other locations in the list. Negative longitudes are transformed to values greater than 180 degrees, as though longitude spanned [0, 360] rather than [-180, 180]. This enables arithmetic operations to be performed on the locations without having to take into account the longitude jump at the dateline.

Parameters:

locations - the locations to transform. This list is not modified.

Returns:

a new list of locations transformed as described above.

Throws:

IllegalArgumentException - if the location list is null.

parseLatLon

public LatLon parseLatLon(String latLonString)

Parses a string containing latitude and longitude coordinates in either Degrees-minutes-seconds or decimal degrees. The latitude must precede the longitude and the angles must be separated by a comma.

Parameters:

latLonString - a string containing the comma separated latitude and longitude in either DMS or decimal degrees.

Returns:

a LatLon instance with the parsed angles.

Throws:

IllegalArgumentException - if latLonString is null.

NumberFormatException - if the string does not form a latitude, longitude pair.

rhumbAzimuth

public static Angle rhumbAzimuth(LatLon p1,
                                 LatLon p2)

Computes the azimuth angle (clockwise from North) of a rhumb line (a line of constant heading) between two locations.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

azimuth Angle of a rhumb line between the two locations.

rhumbDistance

public static Angle rhumbDistance(LatLon p1,
                                  LatLon p2)

Computes the length of the rhumb line between two locations. The return value gives the distance as the angular distance between the two positions on the pi radius circle. In radians, this angle is also the arc length of the segment between the two positions on that circle. To compute a distance in meters from this value, multiply it by the radius of the globe.

Parameters:

p1 - LatLon of the first location

p2 - LatLon of the second location

Returns:

the arc length of the rhumb line between the two locations. In radians, this value is the arc length on the radius pi circle.

rhumbEndPosition

public static LatLon rhumbEndPosition(LatLon p,
                                      Angle rhumbAzimuth,
                                      Angle pathLength)

Computes the location on a rhumb line with the given starting location, rhumb azimuth, and arc distance along the line.

Parameters:

p - LatLon of the starting location

rhumbAzimuth - rhumb azimuth angle (clockwise from North)

pathLength - arc distance to travel

Returns:

LatLon location on the rhumb line.

rhumbEndPosition

public static LatLon rhumbEndPosition(LatLon p,
                                      double rhumbAzimuthRadians,
                                      double pathLengthRadians)

Computes the location on a rhumb line with the given starting location, rhumb azimuth, and arc distance along the line.

Parameters:

p - LatLon of the starting location

rhumbAzimuthRadians - rhumb azimuth angle (clockwise from North), in radians

pathLengthRadians - arc distance to travel, in radians

Returns:

LatLon location on the rhumb line.

subtract

public LatLon subtract(LatLon that)

subtract

public LatLon subtract(Position that)

toString

public String toString()

Overrides:

toString in class Object