gov.usgs.earthquake.nshmp.geo

Class Locations

java.lang.Object

gov.usgs.earthquake.nshmp.geo.Locations

public final class Locations
extends Object

Static utility methods to operate on geographic Location data.

See: Aviation Formulary for formulae implemented in this class as well as Moveable Type Scripts for other implementations.

Author:

Peter Powers

See Also:

Location

Field Summary

Fields

Modifier and Type	Field and Description
static double	TOLERANCE Tolerance used for location comparisons; 0.000000000001 which in decimal-degrees, radians, and km is comparable to micron-scale precision.

Method Summary

Modifier and Type	Method and Description
static double	angle(Location p1, Location p2) Calculates the angle between two Locations using the Haversine formula.
static boolean	areSimilar(Location p1, Location p2) Returns true if the supplied Locations are very, very close to one another.
static double	azimuth(Location p1, Location p2) Computes the initial azimuth (bearing) when moving from one Location to another in degrees.
static double	azimuthRad(Location p1, Location p2) Computes the initial azimuth (bearing) when moving from one Location to another.
static LocationVector	bisect(Location p1, Location p2, Location p3) Method returns a unit LocationVector that bisects the angle defined by the line segments p2p1 and p2p3.
static Bounds	bounds(Iterable<Location> locs) Compute the Bounds of the supplied iterable.
static Location	centroid(Iterable<Location> locs) Computes a centroid for a group of Locations as the average of latitude, longitude, and depth;
static Location	closestPoint(Location loc, LocationList locs) Return the point in a LocationList that is that closest to the supplied Location.
static Predicate<Location>	distanceAndRectangleFilter(Location origin, double distance) Return a radial distance Location filter that preprocesses Locations through a rectangleFilter(Location, double).
static Predicate<Location>	distanceFilter(Location origin, double distance) Return a radial distance Location filter.
static double	distanceToLine(Location p1, Location p2, Location p3) Computes the shortest distance between a point and a line (great-circle).
static double	distanceToLineFast(Location p1, Location p2, Location p3) Computes the shortest distance between a point and a line.
static double	distanceToSegment(Location p1, Location p2, Location p3) Computes the shortest distance between a point and a line segment (i.e.
static double	distanceToSegmentFast(Location p1, Location p2, Location p3) Computes the shortest distance between a point and a line segment.
static double	horzDistance(Location p1, Location p2) Calculates the great circle surface distance between two Location s using the Haversine formula for computing the angle between two points.
static double	horzDistanceFast(Location p1, Location p2) Calculates approximate distance between two Locations.
static boolean	isPole(Location p) Returns whether the supplied Location coincides with one of the poles.
static double	linearDistance(Location p1, Location p2) Calculates the distance in three dimensions between two Locations using spherical geometry.
static double	linearDistanceFast(Location p1, Location p2) Calculates the approximate linear distance in three dimensions between two Locations.
static Location	location(Location p, double azimuth, double distance) Computes a Location given an origin point, bearing, and distance.
static Location	location(Location p, LocationVector d) Computes a Location given an origin point and a LocationVector.
static void	main(String[] args)
static int	minDistanceIndex(Location loc, LocationList locs) Compute the segment index that is closest to a Location.
static double	minDistanceToLine(Location loc, LocationList locs) Compute the shortest horizontal distance (in km) from a Location to the line defined by connecting the points in a LocationList.
static double	minDistanceToLocations(Location loc, LocationList locs) Compute the horizontal distance (in km) from a Location to the closest point in a LocationList.
static double	plunge(Location p1, Location p2) Returns the angle (in decimal degrees) of a line between the first and second location relative to horizontal.
static Predicate<Location>	rectangleFilter(Location origin, double distance) Return a rectangular Location filter.
static Path2D	toPath(LocationList locs) Return a closed, straight-line Path2D representation of the supplied list, ignoring depth.
static double	vertDistance(Location p1, Location p2) Returns the vertical separation between two Locations.

Methods inherited from class java.lang.Object

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

Field Detail

TOLERANCE

public static final double TOLERANCE

Tolerance used for location comparisons; 0.000000000001 which in decimal-degrees, radians, and km is comparable to micron-scale precision.

See Also:

Constant Field Values

Method Detail

angle

public static double angle(Location p1,
                           Location p2)

Calculates the angle between two Locations using the Haversine formula. This method properly handles values spanning ±180°. See Aviation Formulary for source. Result is returned in radians.

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the angle between the points (in radians)

horzDistance

public static double horzDistance(Location p1,
                                  Location p2)

Calculates the great circle surface distance between two Location s using the Haversine formula for computing the angle between two points. For a faster, but less accurate implementation at large separations, see horzDistanceFast(Location, Location).

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the distance between the points in km

See Also:

angle(Location, Location), horzDistanceFast(Location, Location)

horzDistanceFast

public static double horzDistanceFast(Location p1,
                                      Location p2)

Calculates approximate distance between two Locations. This method is about 2 orders of magnitude faster than horzDistance(), but is imprecise at large distances. Method uses the latitudinal and longitudinal differences between the points as the sides of a right triangle. The longitudinal distance is scaled by the cosine of the mean latitude.

Note: This method does NOT support values spanning #177;180° and fails where the numeric angle exceeds 180°. Convert data to the 0-360° interval or use horzDistance(Location, Location) in such instances.

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the distance between the points in km

See Also:

horzDistance(Location, Location)

main

public static void main(String[] args)

vertDistance

public static double vertDistance(Location p1,
                                  Location p2)

Returns the vertical separation between two Locations. The returned value is not absolute and preserves the sign of the difference between the points.

Parameters:

p1 - the first Location point

p2 - the first Location point

Returns:

the vertical separation between the points

linearDistance

public static double linearDistance(Location p1,
                                    Location p2)

Calculates the distance in three dimensions between two Locations using spherical geometry. Method returns the straight line distance taking into account the depths of the points. For a faster, but less accurate implementation at large separations, see linearDistanceFast(Location, Location).

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the distance in km between the points

See Also:

linearDistanceFast(Location, Location)

linearDistanceFast

public static double linearDistanceFast(Location p1,
                                        Location p2)

Calculates the approximate linear distance in three dimensions between two Locations. This simple and speedy implementation uses the Pythagorean theorem, treating horizontal and vertical separations as orthogonal.

Note: This method is very imprecise at large separations and should not be used for points >200km apart. If an estimate of separation distance is not known in advance use linearDistance(Location, Location) for more reliable results.

Note: This method fails for values spanning ±180°; see horzDistanceFast(Location, Location).

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the distance in km between the points

See Also:

linearDistance(Location, Location)

distanceToLine

public static double distanceToLine(Location p1,
                                    Location p2,
                                    Location p3)

Computes the shortest distance between a point and a line (great-circle). that extends infinitely in both directions. Both the line and point are assumed to be at the earth's surface; the depth component of each Location is ignored. This method uses the true spherical geometric function for 'off-track distance'; See Aviation Formulary for source. The sign of the result indicates which side of the supplied line p3 is on (right:[+] left:[-]).

This method, though more accurate over longer distances and line lengths, is up to 20x slower than distanceToLineFast(Location, Location, Location). However, this method returns accurate results for values spanning #177;180°.

If the line should instead be treated as a segment such that the result will be a distance to an endpoint if p3 does not project onto the segment, use distanceToSegment(Location, Location, Location) instead.

Parameters:

p1 - the first Location point on the line

p2 - the second Location point on the line

p3 - the Location point for which distance will be calculated

Returns:

the shortest distance in km between the supplied point and line

See Also:

distanceToLineFast(Location, Location, Location), distanceToSegment(Location, Location, Location)

distanceToLineFast

public static double distanceToLineFast(Location p1,
                                        Location p2,
                                        Location p3)

Computes the shortest distance between a point and a line. Both the line and point are assumed to be at the earth's surface; the depth component of each Location is ignored. This is a fast, geometric, cartesion (flat-earth approximation) solution in which longitude of the line points are scaled by the cosine of latitude; it is only appropriate for use over short distances (e.g. <200 km). The sign of the result indicates which side of the supplied line p3 is on (right:[+] left:[-]).

Note: This method does NOT support values spanning ±180° and results for such input values are not guaranteed. Convert data to the 0-360° interval or use distanceToLine(Location, Location, Location) in such instances.

If the line should instead be treated as a segment such that the result will be a distance to an endpoint if p3 does not project onto the segment, use distanceToSegmentFast(Location, Location, Location) instead.

Parameters:

p1 - the first Location point on the line

p2 - the second Location point on the line

p3 - the Location point for which distance will be calculated

Returns:

the shortest distance in km between the supplied point and line

See Also:

distanceToLine(Location, Location, Location), distanceToSegmentFast(Location, Location, Location)

distanceToSegment

public static double distanceToSegment(Location p1,
                                       Location p2,
                                       Location p3)

Computes the shortest distance between a point and a line segment (i.e. great-circle segment). Both the line and point are assumed to be at the earth's surface; the depth component of each Location is ignored. This method uses the true spherical geometric function for 'off-track distance'; See Aviation Formulary for source. This method always returns a positive result.

This method, though more accurate over longer distances and line lengths, is up to 20x slower than distanceToSegmentFast(Location, Location, Location). However, this method returns accurate results for values spanning ±180°.

If the line should instead be treated as infinite, use distanceToLine(Location, Location, Location) instead.

Parameters:

p1 - the first Location point on the line

p2 - the second Location point on the line

p3 - the Location point for which distance will be calculated

Returns:

the shortest distance in km between the supplied point and line

See Also:

distanceToLineFast(Location, Location, Location), distanceToLine(Location, Location, Location)

distanceToSegmentFast

public static double distanceToSegmentFast(Location p1,
                                           Location p2,
                                           Location p3)

Computes the shortest distance between a point and a line segment. Both the line and point are assumed to be at the earth's surface; the depth component of each Location is ignored. This is a fast, geometric, cartesion (flat-earth approximation) solution in which longitude of the line points are scaled by the cosine of latitude; it is only appropriate for use over short distances (e.g. <200 km).

Note: This method fails for values spanning ±180°; see distanceToSegment(Location, Location, Location).

If the line should instead be treated as infinite, use distanceToLineFast(Location, Location, Location) instead.

Parameters:

p1 - the first Location point on the line

p2 - the second Location point on the line

p3 - the Location point for which distance will be calculated

Returns:

the shortest distance in km between the supplied point and line

See Also:

distanceToSegment(Location, Location, Location), distanceToLineFast(Location, Location, Location)

azimuthRad

public static double azimuthRad(Location p1,
                                Location p2)

Computes the initial azimuth (bearing) when moving from one Location to another. See Aviation Formulary for source. For back azimuth, reverse the Location arguments. Result is returned in radians over the interval [0, 2π).

Note: It is more efficient to use this method for computation because Locations store lat and lon in radians internally. Use azimuth(Location, Location) for presentation.

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the azimuth (bearing) from p1 to p2 in radians

See Also:

azimuth(Location, Location)

azimuth

public static double azimuth(Location p1,
                             Location p2)

Computes the initial azimuth (bearing) when moving from one Location to another in degrees. See Aviation Formulary for source. For back azimuth, reverse the Location arguments. Result is returned in decimal degrees over the interval 0° to 360°.

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the azimuth (bearing) from p1 to p2 in decimal degrees

See Also:

azimuthRad(Location, Location)

location

public static Location location(Location p,
                                double azimuth,
                                double distance)

Computes a Location given an origin point, bearing, and distance. See Aviation Formulary for source. Note that azimuth is expected in radians.

Parameters:

p - starting location point

azimuth - (bearing) in radians away from origin

distance - (horizontal) along bearing in km

Returns:

the end location

location

public static Location location(Location p,
                                LocationVector d)

Computes a Location given an origin point and a LocationVector. See Aviation Formulary for source.

Parameters:

p - starting location point

d - distance along bearing

Returns:

the end location

plunge

public static double plunge(Location p1,
                            Location p2)

Returns the angle (in decimal degrees) of a line between the first and second location relative to horizontal. This method is intended for use at relatively short separations ( e.g. ≤200km) as it degrades at large distances where curvature is not considered. Note that positive angles are down, negative angles are up.

Parameters:

p1 - the first Location point

p2 - the second Location point

Returns:

the plunge of this vector

bisect

public static LocationVector bisect(Location p1,
                                    Location p2,
                                    Location p3)

Method returns a unit LocationVector that bisects the angle defined by the line segments p2p1 and p2p3.

Parameters:

p1 - the first Location point

p2 - the second Location point

p3 - the third Location point

Returns:

the bisecting LocationVector

isPole

public static boolean isPole(Location p)

Returns whether the supplied Location coincides with one of the poles. Any supplied Locations that are very close (less than a mm) will return true.

Parameters:

p - Location to check

Returns:

true if loc coincides with one of the earth's poles, false otherwise.

areSimilar

public static boolean areSimilar(Location p1,
                                 Location p2)

Returns true if the supplied Locations are very, very close to one another. Internally, lat, lon, and depth values must be within <1mm of each other.

Parameters:

p1 - the first Location to compare

p2 - the second Location to compare

Returns:

true if the supplied Locations are very close, false otherwise.

bounds

public static Bounds bounds(Iterable<Location> locs)

Compute the Bounds of the supplied iterable. If locs contains only 1 element, Bounds.min() and Bounds.max() of the returned object will be the same.

Parameters:

locs - to compute bounds for

Throws:

IllegalArgumentException - if locs is empty

centroid

public static Location centroid(Iterable<Location> locs)

Computes a centroid for a group of Locations as the average of latitude, longitude, and depth;

Parameters:

locs - locations to process

toPath

public static Path2D toPath(LocationList locs)

Return a closed, straight-line Path2D representation of the supplied list, ignoring depth.

closestPoint

public static Location closestPoint(Location loc,
                                    LocationList locs)

Return the point in a LocationList that is that closest to the supplied Location. This method uses horzDistanceFast(Location, Location) to compute the distance.

Parameters:

loc - @code Location} of interest

locs - LocationList to search for closest point in

See Also:

horzDistanceFast(Location, Location)

minDistanceToLocations

public static double minDistanceToLocations(Location loc,
                                            LocationList locs)

Compute the horizontal distance (in km) from a Location to the closest point in a LocationList. This method uses horzDistanceFast(Location, Location) to compute the distance.

Parameters:

loc - Location of interest

locs - LocationList to compute distance to

See Also:

horzDistanceFast(Location, Location)

minDistanceToLine

public static double minDistanceToLine(Location loc,
                                       LocationList locs)

Compute the shortest horizontal distance (in km) from a Location to the line defined by connecting the points in a LocationList. This method uses distanceToSegmentFast(Location, Location, Location) and is inappropriate for for use at large separations (e.g. >200 km).

Parameters:

loc - Location of interest

locs - LocationList to compute distance to

See Also:

distanceToSegmentFast(Location, Location, Location)

minDistanceIndex

public static int minDistanceIndex(Location loc,
                                   LocationList locs)

Compute the segment index that is closest to a Location. There are locs.size() - 1 segment indices. The indices of the segment endpoints in the original location list are [n, n+1].

Parameters:

loc - Location of interest

locs - LocationList for which to compute the closest segment index

Throws:

IllegalArgumentException - if locs.size() < 2

distanceFilter

public static Predicate<Location> distanceFilter(Location origin,
                                                 double distance)

Return a radial distance Location filter.

Parameters:

origin - of filter

distance - beyond which the filter will return false

distanceAndRectangleFilter

public static Predicate<Location> distanceAndRectangleFilter(Location origin,
                                                             double distance)

Return a radial distance Location filter that preprocesses Locations through a rectangleFilter(Location, double).

Parameters:

origin - of filter

distance - beyond which the filter will return false

See Also:

rectangleFilter(Location, double)

rectangleFilter

public static Predicate<Location> rectangleFilter(Location origin,
                                                  double distance)

Return a rectangular Location filter. The filter is definied in geographic (lat,lon) space and is constrained to Coordinates.LAT_RANGE and Coordinates.LON_RANGE. The filter has dimensions of 2 * distance for both height and width, and is centered on the supplied Location . This filter is for use as a fast, first-pass filter before more computationally intensive distance filtering.

Parameters:

origin - (center) of filter

distance - half-width and half-height of rectangle outside of which the filter will return false

See Also:

Coordinates