org.opensha.commons.geo
Class LocationUtils

java.lang.Object
  extended by org.opensha.commons.geo.LocationUtils

public final class LocationUtils
extends Object

This class contains 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.

Version:
$Id: LocationUtils.java 10313 2013-09-24 21:50:21Z kmilner $
Author:
Peter Powers, Steven W. Rock
See Also:
Location

Nested Class Summary
static class LocationUtils.Side
          Enum used indicate sidedness of points with respect to a line.
 
Field Summary
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
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 double calcMaxLat(Collection<Location> locs)
          Calculates the maximum latitude in the supplied Collection of Location objects.
static double calcMaxLon(Collection<Location> locs)
          Calculates the maximum longitude in the supplied Collection of Location objects.
static double calcMinLat(Collection<Location> locs)
          Calculates the minimum latitude in the supplied Collection of Location objects.
static double calcMinLon(Collection<Location> locs)
          Calculates the minimum longitude in the supplied Collection of Location objects.
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 distanceToLineSegment(Location p1, Location p2, Location p3)
          Computes the shortest distance between a point and a line segment (i.e.
static double distanceToLineSegmentFast(Location p1, Location p2, Location p3)
          Computes the shortest distance between a point and a line segment.
static double distanceToSurf(Location loc, AbstractEvenlyGriddedSurface rupSurf)
          Calculates the distance between the supplied Location and the EventlyGridddedSurface by looping over all the locations in the surface and returning the smallest one determined by horzDistance(Location, Location).
static double distanceToSurfFast(Location loc, RuptureSurface rupSurf)
          Calculates the distance between the supplied Location and the EventlyGridddedSurface by looping over all the locations in the surface and returning the smallest one determined by horzDistanceFast(Location, Location).
static double horzDistance(Location p1, Location p2)
          Calculates the great circle surface distance between two Locations 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 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 LocationVector vector(Location p1, Location p2)
          Returns the LocationVector describing the move from one Location to another.
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 Locations 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°. 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.

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 distanceToLineSegment(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), distanceToLineSegment(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.

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 distanceToLineSegmentFast(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), distanceToLineSegmentFast(Location, Location, Location)

distanceToSurf

public static double distanceToSurf(Location loc,
                                    AbstractEvenlyGriddedSurface rupSurf)
Calculates the distance between the supplied Location and the EventlyGridddedSurface by looping over all the locations in the surface and returning the smallest one determined by horzDistance(Location, Location).

Parameters:
loc - a Location
rupSurf - an EvenlyGriddedSurfaceAPI
Returns:
the minimum distance to a surface from the supplied Location

distanceToSurfFast

public static double distanceToSurfFast(Location loc,
                                        RuptureSurface rupSurf)
Calculates the distance between the supplied Location and the EventlyGridddedSurface by looping over all the locations in the surface and returning the smallest one determined by horzDistanceFast(Location, Location).

Parameters:
loc - a Location
rupSurf - an EvenlyGriddedSurfaceAPI
Returns:
the minimum distance to a surface from the supplied Location

distanceToLineSegment

public static double distanceToLineSegment(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 distanceToLineSegmentFast(Location, Location, Location). However, this method returns accurate results for values spanning #177;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)

distanceToLineSegmentFast

public static double distanceToLineSegmentFast(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 does NOT support values spanning ±180° and results for such input values are not guaranteed. This method always returns a positive result.

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:
distanceToLineSegment(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 to 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

vector

public static LocationVector vector(Location p1,
                                    Location p2)
Returns the LocationVector describing the move from one Location to another.

Parameters:
p1 - the first Location point
p2 - the second Location point
Returns:
the LocationVector from p1 to p2

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. <eq; 200km) as it degrades at large distances where curvature is not considered. Note that positive angles are down, negative angles are up.

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.

calcMinLat

public static double calcMinLat(Collection<Location> locs)
Calculates the minimum latitude in the supplied Collection of Location objects.

Parameters:
locs - - collection of locations
Returns:
the minimum latitude in the supplied locations, or positive infinity if the Collection is empty.
Throws:
NullPointerException - if locs is null

calcMinLon

public static double calcMinLon(Collection<Location> locs)
Calculates the minimum longitude in the supplied Collection of Location objects.

Parameters:
locs - - collection of locations
Returns:
the minimum longitude in the supplied locations, or positive infinity if the Collection is empty.
Throws:
NullPointerException - if locs is null

calcMaxLat

public static double calcMaxLat(Collection<Location> locs)
Calculates the maximum latitude in the supplied Collection of Location objects.

Parameters:
locs - - collection of locations
Returns:
the maximum latitude in the supplied locations, or negative infinity if the Collection is empty.
Throws:
NullPointerException - if locs is null

calcMaxLon

public static double calcMaxLon(Collection<Location> locs)
Calculates the maximum longitude in the supplied Collection of Location objects.

Parameters:
locs - - collection of locations
Returns:
the maximum longitude in the supplied locations, or negative infinity if the Collection is empty.
Throws:
NullPointerException - if locs is null