org.opensha.commons.geo
Class LocationUtils

java.lang.Object
  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 9762 2012-12-06 21:48:27Z field $

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	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	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 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.

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)

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

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 #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)

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 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:

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 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