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:

U.S. Geological Survey

See Also:

Location

Field Summary

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

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static double`	`angle(Location p1, Location p2)`	Calculates the angle between two `Location`s using the Haversine formula.
`static double`	`area(LocationList border)`	Compute the signed area of a closed path in km².
`static boolean`	`areSimilar(Location p1, Location p2)`	Returns `true` if the supplied `Location`s 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 `Location`s 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 `Location`s 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 `Location`s.
`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 `Location`s using spherical geometry.
`static double`	`linearDistanceFast(Location p1, Location p2)`	Calculates the approximate linear distance in three dimensions between two `Location`s.
`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 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 `Location`s.

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
  - area
```
public static double area(LocationList border)
```
    Compute the signed area of a closed path in km². Method returns zero if supplied border has less than three coordinates. Supplied polygon does not need to be closed (the first and last points do not need to be the same). Calculation uses Coordinates.EARTH_RADIUS_MEAN to compute area and does not consider depths of border coordinates at this time.
    
    Parameters:
    
    border -
    
    radius -
    
    See Also:
    
    com.google.maps.android.SphericalUtil
  - 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 ±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)
  - 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 ±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 point
    
    p2 - the second point
    
    p3 - the third 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 -
  - 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

Class Locations

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TOLERANCE

Method Detail

area

angle

horzDistance

horzDistanceFast

vertDistance

linearDistance

linearDistanceFast

distanceToLine

distanceToLineFast

distanceToSegment

distanceToSegmentFast

azimuthRad

azimuth

location

location

plunge

bisect

isPole

areSimilar

bounds

centroid

toPath

closestPoint

minDistanceToLocations

minDistanceToLine

minDistanceIndex

distanceFilter

distanceAndRectangleFilter

rectangleFilter