

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object org.opensha.commons.geo.LocationUtils
public final class LocationUtils
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.
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 decimaldegrees, radians, and km is comparable to micronscale precision. 
Method Summary  

static double 
angle(Location p1,
Location p2)
Calculates the angle between two Location s using the
Haversine formula. 
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 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 (greatcircle). 
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 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 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 Location s. 
Methods inherited from class java.lang.Object 

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

public static final double TOLERANCE
Method Detail 

public static double angle(Location p1, Location p2)
Location
s using the
Haversine formula. This method properly handles values spanning
±180°. See Aviation
Formulary for source. Result is returned in radians.
p1
 the first Location
pointp2
 the second Location
point
public static double horzDistance(Location p1, Location p2)
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)
.
p1
 the first Location
pointp2
 the second Location
point
angle(Location, Location)
,
horzDistanceFast(Location, Location)
public static double horzDistanceFast(Location p1, Location p2)
Location
s. 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 0360° interval or use
horzDistance(Location, Location)
in such instances.
p1
 the first Location
pointp2
 the second Location
point
horzDistance(Location, Location)
public static double vertDistance(Location p1, Location p2)
Location
s. The
returned value is not absolute and preserves the sign of the difference
between the points.
p1
 the first Location
pointp2
 the first Location
point
public static double linearDistance(Location p1, Location p2)
Location
s 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)
.
p1
 the first Location
pointp2
 the second Location
point
linearDistanceFast(Location, Location)
public static double linearDistanceFast(Location p1, Location p2)
Location
s. This simple and speedy implementation uses
the Pythagorean theorem, treating horizontal and vertical separations as
orthogonal.linearDistance(Location, Location)
for more reliable results.
Note: This method fails for values spanning ±180°;
see horzDistanceFast(Location, Location)
.
p1
 the first Location
pointp2
 the second Location
point
linearDistance(Location, Location)
public static double distanceToLine(Location p1, Location p2, Location p3)
Location
is ignored. This method uses the true spherical
geometric function for 'offtrack distance'; See Aviation
Formulary for source. The sign of the result indicates which side of
the supplied line p3
is on (right:[+] left:[]).distanceToLineFast(Location, Location, Location)
. However, this
method returns accurate results for values spanning #177;180°. p3
does not project
onto the segment, use
distanceToLineSegment(Location, Location, Location)
instead.
p1
 the first Location
point on the linep2
 the second Location
point on the linep3
 the Location
point for which distance will be
calculated
distanceToLineFast(Location, Location, Location)
,
distanceToLineSegment(Location, Location, Location)
public static double distanceToLineFast(Location p1, Location p2, Location p3)
Location
is ignored. This is a fast, geometric,
cartesion (flatearth 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 0360° 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
distanceToLineSegmentFast(Location, Location, Location)
instead.
p1
 the first Location
point on the linep2
 the second Location
point on the linep3
 the Location
point for which distance will be
calculated
distanceToLine(Location, Location, Location)
,
distanceToLineSegmentFast(Location, Location, Location)
public static double distanceToSurf(Location loc, AbstractEvenlyGriddedSurface rupSurf)
Location
and
the EventlyGridddedSurface
by looping over all the locations
in the surface and returning the smallest one determined by
horzDistance(Location, Location)
.
loc
 a Location
rupSurf
 an EvenlyGriddedSurfaceAPI
Location
public static double distanceToSurfFast(Location loc, RuptureSurface rupSurf)
Location
and
the EventlyGridddedSurface
by looping over all the locations
in the surface and returning the smallest one determined by
horzDistanceFast(Location, Location)
.
Note: This method fails for values spanning ±180°;
see horzDistanceFast(Location, Location)
.
loc
 a Location
rupSurf
 an EvenlyGriddedSurfaceAPI
Location
public static double distanceToLineSegment(Location p1, Location p2, Location p3)
Location
is
ignored. This method uses the true spherical geometric function for
'offtrack distance'; See Aviation
Formulary for source. This method always returns a positive result.distanceToLineSegmentFast(Location, Location, Location)
. However,
this method returns accurate results for values spanning #177;180°. distanceToLine(Location, Location, Location)
instead.
p1
 the first Location
point on the linep2
 the second Location
point on the linep3
 the Location
point for which distance will be
calculated
distanceToLineFast(Location, Location, Location)
,
distanceToLine(Location, Location, Location)
public static double distanceToLineSegmentFast(Location p1, Location p2, Location p3)
Location
is ignored. This is a fast,
geometric, cartesion (flatearth 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). This
method always returns a positive result.
Note: This method fails for values spanning ±180°;
see distanceToLineFast(Location, Location, Location)
.
If the line should instead be treated as infinite, use
distanceToLineFast(Location, Location, Location)
instead.
p1
 the first Location
point on the linep2
 the second Location
point on the linep3
 the Location
point for which distance will be
calculated
distanceToLineSegment(Location, Location, Location)
,
distanceToLineFast(Location, Location, Location)
public static double azimuthRad(Location p1, Location p2)
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π.Location
s store lat and lon in radians internally.
Use azimuth(Location, Location)
for presentation.
p1
 the first Location
pointp2
 the second Location
point
azimuth(Location, Location)
public static double azimuth(Location p1, Location p2)
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°.
p1
 the first Location
pointp2
 the second Location
point
azimuthRad(Location, Location)
public static Location location(Location p, double azimuth, double distance)
Location
given an origin point, bearing, and
distance. See
Aviation Formulary for source. Note that azimuth
is
expected in radians.
p
 starting location pointazimuth
 (bearing) in radians away from origindistance
 (horizontal) along bearing in km
public static Location location(Location p, LocationVector d)
Location
given an origin point and a
LocationVector
. See Aviation Formulary
for source.
p
 starting location pointd
 distance along bearing
public static LocationVector vector(Location p1, Location p2)
LocationVector
describing the move from one
Location
to another.
p1
 the first Location
pointp2
 the second Location
point
LocationVector
from p1
to
p2
public static double plunge(Location p1, Location p2)
public static LocationVector bisect(Location p1, Location p2, Location p3)
LocationVector
that bisects the angle
defined by the line segments
p2p1
and
p2p3
.
p1
 the first Location
pointp2
 the second Location
pointp3
 the third Location
point
LocationVector
public static boolean isPole(Location p)
Location
coincides with one of
the poles. Any supplied Location
s that are very close (less
than a mm) will return true
.
p
 Location
to check
true
if loc
coincides with one of the
earth's poles, false
otherwise.public static boolean areSimilar(Location p1, Location p2)
true
if the supplied Location
s are
very, very close to one another. Internally, lat, lon, and depth values
must be within <1mm of each other.
p1
 the first Location
to comparep2
 the second Location
to compare
true
if the supplied Location
s are very
close, false
otherwise.public static double calcMinLat(Collection<Location> locs)
Collection
of Location
objects.
locs
  collection of locations
Collection
is empty.
NullPointerException
 if locs
is nullpublic static double calcMinLon(Collection<Location> locs)
Collection
of Location
objects.
locs
  collection of locations
Collection
is empty.
NullPointerException
 if locs
is nullpublic static double calcMaxLat(Collection<Location> locs)
Collection
of Location
objects.
locs
  collection of locations
Collection
is empty.
NullPointerException
 if locs
is nullpublic static double calcMaxLon(Collection<Location> locs)
Collection
of Location
objects.
locs
  collection of locations
Collection
is empty.
NullPointerException
 if locs
is null


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 