# The Hazard Library
# Copyright (C) 2012-2014, GEM Foundation
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
Module :mod:`openquake.hazardlib.geo.geodetic` contains functions for geodetic
transformations, optimized for massive calculations.
"""
import operator
import numpy
#: Earth radius in km.
EARTH_RADIUS = 6371.0
[docs]class GeographicObjects(object):
"""
Store a collection of geographic objects, i.e. objects with longitudes
and latitudes. By default extracts the coordinates from the attributes
.lon and .lat, but you can provide your own getters. It is possible
to extract the closest object to a given location by calling the
method .get_closest(lon, lat).
"""
def __init__(self, objects, getlon=operator.attrgetter('lon'),
getlat=operator.attrgetter('lat')):
self.objects = list(objects)
lons, lats = [], []
for obj in self.objects:
lons.append(getlon(obj))
lats.append(getlat(obj))
self.lons, self.lats = numpy.array(lons), numpy.array(lats)
[docs] def get_closest(self, lon, lat, max_distance=None):
"""
Get the closest object to the given longitude and latitude.
If the `max_distance` is given and all points are farther
then the maximum distance, returns None.
:param lon: longitude in degrees
:param lat: latitude in degrees
:param max_distance: distance in km (or None)
"""
zeros = numpy.zeros_like(self.lons)
index = min_distance(self.lons, self.lats, zeros, lon, lat, 0.,
indices=True)
if max_distance is not None:
min_dist = min_distance(self.lons, self.lats, zeros, lon, lat, 0.)
if min_dist > max_distance:
return
return self.objects[index]
[docs]def geodetic_distance(lons1, lats1, lons2, lats2):
"""
Calculate the geodetic distance between two points or two collections
of points.
Parameters are coordinates in decimal degrees. They could be scalar
float numbers or numpy arrays, in which case they should "broadcast
together".
Implements http://williams.best.vwh.net/avform.htm#Dist
:returns:
Distance in km, floating point scalar or numpy array of such.
"""
lons1, lats1, lons2, lats2 = _prepare_coords(lons1, lats1, lons2, lats2)
distance = numpy.arcsin(numpy.sqrt(
numpy.sin((lats1 - lats2) / 2.0) ** 2.0
+ numpy.cos(lats1) * numpy.cos(lats2)
* numpy.sin((lons1 - lons2) / 2.0) ** 2.0
).clip(-1., 1.))
return (2.0 * EARTH_RADIUS) * distance
[docs]def azimuth(lons1, lats1, lons2, lats2):
"""
Calculate the azimuth between two points or two collections of points.
Parameters are the same as for :func:`geodetic_distance`.
Implements an "alternative formula" from
http://williams.best.vwh.net/avform.htm#Crs
:returns:
Azimuth as an angle between direction to north from first point and
direction to the second point measured clockwise in decimal degrees.
"""
lons1, lats1, lons2, lats2 = _prepare_coords(lons1, lats1, lons2, lats2)
cos_lat2 = numpy.cos(lats2)
true_course = numpy.degrees(numpy.arctan2(
numpy.sin(lons1 - lons2) * cos_lat2,
numpy.cos(lats1) * numpy.sin(lats2)
- numpy.sin(lats1) * cos_lat2 * numpy.cos(lons1 - lons2)
))
return (360 - true_course) % 360
[docs]def distance(lons1, lats1, depths1, lons2, lats2, depths2):
"""
Calculate a distance between two points (or collections of points)
considering points' depth.
Calls :func:`geodetic_distance`, finds the "vertical" distance between
points by subtracting one depth from another and combine both using
Pythagoras theorem.
:returns:
Distance in km, a square root of sum of squares of :func:`geodetic
<geodetic_distance>` distance and vertical distance, which is just
a difference between depths.
"""
hdist = geodetic_distance(lons1, lats1, lons2, lats2)
vdist = depths1 - depths2
return numpy.sqrt(hdist ** 2 + vdist ** 2)
[docs]def min_distance_to_segment(seglons, seglats, lons, lats):
"""
This function computes the shortest distance to a segment in a 2D reference
system.
:parameter seglons:
A list or an array of floats specifying the longitude values of the two
vertexes delimiting the segment.
:parameter seglats:
A list or an array of floats specifying the latitude values of the two
vertexes delimiting the segment.
:parameter lons:
A list or a 1D array of floats specifying the longitude values of the
points for which the calculation of the shortest distance is requested.
:parameter lats:
A list or a 1D array of floats specifying the latitude values of the
points for which the calculation of the shortest distance is requested.
:returns:
An array of the same shape as lons which contains for each point
defined by (lons, lats) the shortest distance to the segment.
Distances are negative for those points that stay on the 'left side'
of the segment direction and whose projection lies within the segment
edges. For all other points, distance is positive.
"""
# Check the size of the seglons, seglats arrays
assert len(seglons) == len(seglats) == 2
# Compute the azimuth of the segment
seg_azim = azimuth(seglons[0], seglats[0], seglons[1], seglats[1])
# Compute the azimuth of the direction obtained
# connecting the first point defining the segment and each site
azimuth1 = azimuth(seglons[0], seglats[0], lons, lats)
# Compute the azimuth of the direction obtained
# connecting the second point defining the segment and each site
azimuth2 = azimuth(seglons[1], seglats[1], lons, lats)
# Find the points inside the band defined by the two lines perpendicular
# to the segment direction passing through the two vertexes of the segment.
# For these points the closest distance is the distance from the great arc.
idx_in = numpy.nonzero(
(numpy.cos(numpy.radians(seg_azim-azimuth1)) >= 0.0) &
(numpy.cos(numpy.radians(seg_azim-azimuth2)) <= 0.0))
# Find the points outside the band defined by the two line perpendicular
# to the segment direction passing through the two vertexes of the segment.
# For these points the closest distance is the minimum of the distance from
# the two point vertexes.
idx_out = numpy.nonzero(
(numpy.cos(numpy.radians(seg_azim-azimuth1)) < 0.0) |
(numpy.cos(numpy.radians(seg_azim-azimuth2)) > 0.0))
# Find the indexes of points 'on the left of the segment'
idx_neg = numpy.nonzero(numpy.sin(numpy.radians(
(azimuth1-seg_azim))) < 0.0)
# Now let's compute the distances for the two cases.
dists = numpy.zeros_like(lons)
if len(idx_in[0]):
dists[idx_in] = distance_to_arc(seglons[0],
seglats[0],
seg_azim,
lons[idx_in],
lats[idx_in])
if len(idx_out[0]):
dists[idx_out] = (min_geodetic_distance(seglons, seglats,
lons[idx_out], lats[idx_out]))
# Finally we correct the sign of the distances in order to make sure that
# the points on the right semispace defined using as a reference the
# direction defined by the segment (i.e. the direction defined by going
# from the first point to the second one) have a positive distance and
# the others a negative one.
dists = abs(dists)
dists[idx_neg] = - dists[idx_neg]
return dists
[docs]def min_geodetic_distance(mlons, mlats, slons, slats):
"""
Same as :func:`min_distance`, but calculates only minimum geodetic distance
(doesn't accept depth values) and doesn't support ``indices=True`` mode.
This is an optimized version of :meth:`min_distance` that is suitable
for calculating the minimum distance between first mesh and each point
of the second mesh when both are defined on the earth surface.
"""
mlons, mlats, slons, slats = _prepare_coords(mlons, mlats, slons, slats)
orig_shape = slons.shape
if slons.ndim == 0:
slons = slons.reshape((1, ))
slats = slats.reshape((1, ))
cos_mlats = numpy.cos(mlats)
cos_slats = numpy.cos(slats)
result = numpy.fromiter(
(
# next five lines are the same as in geodetic_distance()
numpy.arcsin(numpy.sqrt(
numpy.sin((mlats - slats[i]) / 2.0) ** 2.0
+ cos_mlats * cos_slats[i]
* numpy.sin((mlons - slons[i]) / 2.0) ** 2.0
).clip(-1., 1.)).min()
for i in xrange(len(slats))
),
dtype=float, count=len(slats)
) * (2 * EARTH_RADIUS)
if not orig_shape:
# original target point was a scalar, so return scalar as well
[result] = result
return result
else:
return result.reshape(orig_shape)
[docs]def min_distance(mlons, mlats, mdepths, slons, slats, sdepths, indices=False):
"""
Calculate the minimum distance between a collection of points and a point.
This function allows to calculate a closest distance to a collection
of points for each point in another collection. Both collection can be
of any shape, although it doesn't make sense to use scalars for the first
one.
Implements the same formula as in :func:`geodetic_distance` for distance
along great circle arc and the same approach as in :func:`distance`
for combining it with depth distance.
:param array mlons, mlats, mdepths:
Numpy arrays of the same shape representing a first collection
of points, the one distance to which is of interest -- longitudes,
latitudes (both in decimal degrees) and depths (in km).
:param array slons, slats, sdepths:
Scalars, python lists or tuples or numpy arrays of the same shape,
representing a second collection: a list of points to find a minimum
distance from for.
:param indices:
If ``True`` -- return indices of closest points from first triple
of coordinates instead of the actual distances. Indices are always
scalar integers -- they represent indices of a point from flattened
form of ``mlons``, ``mlats`` and ``mdepths`` that is closest to a
point from ``slons``, ``slats`` and ``sdepths``. There is one integer
index per point in second triple of coordinates.
:returns:
Minimum distance in km or indices of closest points, depending on
``indices`` parameter. Result value is a scalar if ``slons``, ``slats``
and ``sdepths`` are scalars and numpy array of the same shape
of those three otherwise.
"""
assert not indices or mlons.ndim > 0
mlons, mlats, slons, slats = _prepare_coords(mlons, mlats, slons, slats)
mdepths = numpy.array(mdepths, float)
sdepths = numpy.array(sdepths, float)
assert mlons.shape == mdepths.shape
assert slons.shape == sdepths.shape
orig_shape = slons.shape
mlons = mlons.reshape(-1)
mlats = mlats.reshape(-1)
mdepths = mdepths.reshape(-1)
slons = slons.reshape(-1)
slats = slats.reshape(-1)
sdepths = sdepths.reshape(-1)
cos_mlats = numpy.cos(mlats)
cos_slats = numpy.cos(slats)
dist_squares = (
# next five lines are the same as in geodetic_distance()
(numpy.arcsin(numpy.sqrt(
numpy.sin((mlats - slats[i]) / 2.0) ** 2.0
+ cos_mlats * cos_slats[i]
* numpy.sin((mlons - slons[i]) / 2.0) ** 2.0
).clip(-1., 1.)) * (2 * EARTH_RADIUS)) ** 2
+ (mdepths - sdepths[i]) ** 2
for i in xrange(len(slats))
)
if not indices:
result = numpy.fromiter((numpy.sqrt(numpy.min(dist_sq))
for dist_sq in dist_squares),
dtype=float, count=len(slats))
else:
result = numpy.fromiter((numpy.argmin(dsq, axis=-1)
for dsq in dist_squares),
dtype=int, count=len(slats))
if not orig_shape:
# original target point was a scalar, so return scalar as well
[result] = result
return result
else:
return result.reshape(orig_shape)
[docs]def intervals_between(lon1, lat1, depth1, lon2, lat2, depth2, length):
"""
Find a list of points between two given ones that lie on the same
great circle arc and are equally spaced by ``length`` km.
:param float lon1, lat1, depth1:
Coordinates of a point to start placing intervals from. The first
point in the resulting list has these coordinates.
:param float lon2, lat2, depth2:
Coordinates of the other end of the great circle arc segment
to put intervals on. The last resulting point might be closer
to the first reference point than the second one or further,
since the number of segments is taken as rounded division of
length between two reference points and ``length``.
:param length:
Required distance between two subsequent resulting points, in km.
:returns:
Tuple of three 1d numpy arrays: longitudes, latitudes and depths
of resulting points respectively.
Rounds the distance between two reference points with respect
to ``length`` and calls :func:`npoints_towards`.
"""
assert length > 0
hdist = geodetic_distance(lon1, lat1, lon2, lat2)
vdist = depth2 - depth1
# if this method is called multiple times with coordinates that are
# separated by the same distance, because of floating point imprecisions
# the total distance may have slightly different values (for instance if
# the distance between two set of points is 65 km, total distance can be
# 64.9999999999989910 and 65.0000000000020322). These two values bring to
# two different values of num_intervals (32 in the first case and 33 in
# the second), and this is a problem because for the same distance we
# should have the same number of intervals. To reduce potential differences
# due to floating point errors, we therefore round total_distance to a
# fixed precision (7)
total_distance = round(numpy.sqrt(hdist ** 2 + vdist ** 2), 7)
num_intervals = int(round(total_distance / length))
if num_intervals == 0:
return numpy.array([lon1]), numpy.array([lat1]), numpy.array([depth1])
dist_factor = (length * num_intervals) / total_distance
return npoints_towards(
lon1, lat1, depth1, azimuth(lon1, lat1, lon2, lat2),
hdist * dist_factor, vdist * dist_factor, num_intervals + 1
)
[docs]def npoints_between(lon1, lat1, depth1, lon2, lat2, depth2, npoints):
"""
Find a list of specified number of points between two given ones that are
equally spaced along the great circle arc connecting given points.
:param float lon1, lat1, depth1:
Coordinates of a point to start from. The first point in a resulting
list has these coordinates.
:param float lon2, lat2, depth2:
Coordinates of a point to finish at. The last point in a resulting
list has these coordinates.
:param npoints:
Integer number of points to return. First and last points count,
so if there have to be two intervals, ``npoints`` should be 3.
:returns:
Tuple of three 1d numpy arrays: longitudes, latitudes and depths
of resulting points respectively.
Finds distance between two reference points and calls
:func:`npoints_towards`.
"""
hdist = geodetic_distance(lon1, lat1, lon2, lat2)
vdist = depth2 - depth1
rlons, rlats, rdepths = npoints_towards(
lon1, lat1, depth1, azimuth(lon1, lat1, lon2, lat2),
hdist, vdist, npoints
)
# the last point should be left intact
rlons[-1] = lon2
rlats[-1] = lat2
rdepths[-1] = depth2
return rlons, rlats, rdepths
[docs]def npoints_towards(lon, lat, depth, azimuth, hdist, vdist, npoints):
"""
Find a list of specified number of points starting from a given one
along a great circle arc with a given azimuth measured in a given point.
:param float lon, lat, depth:
Coordinates of a point to start from. The first point in a resulting
list has these coordinates.
:param azimuth:
A direction representing a great circle arc together with a reference
point.
:param hdist:
Horizontal (geodetic) distance from reference point to the last point
of the resulting list, in km.
:param vdist:
Vertical (depth) distance between reference and the last point, in km.
:param npoints:
Integer number of points to return. First and last points count,
so if there have to be two intervals, ``npoints`` should be 3.
:returns:
Tuple of three 1d numpy arrays: longitudes, latitudes and depths
of resulting points respectively.
Implements "completely general but more complicated algorithm" from
http://williams.best.vwh.net/avform.htm#LL
"""
assert npoints > 1
rlon, rlat = numpy.radians(lon), numpy.radians(lat)
tc = numpy.radians(360 - azimuth)
hdists = numpy.arange(npoints, dtype=float)
hdists *= (hdist / EARTH_RADIUS) / (npoints - 1)
vdists = numpy.arange(npoints, dtype=float)
vdists *= vdist / (npoints - 1)
sin_dists = numpy.sin(hdists)
cos_dists = numpy.cos(hdists)
sin_lat = numpy.sin(rlat)
cos_lat = numpy.cos(rlat)
sin_lats = sin_lat * cos_dists + cos_lat * sin_dists * numpy.cos(tc)
sin_lats = sin_lats.clip(-1., 1.)
lats = numpy.degrees(numpy.arcsin(sin_lats))
dlon = numpy.arctan2(numpy.sin(tc) * sin_dists * cos_lat,
cos_dists - sin_lat * sin_lats)
lons = numpy.mod(rlon - dlon + numpy.pi, 2 * numpy.pi) - numpy.pi
lons = numpy.degrees(lons)
depths = vdists + depth
# the first point should be left intact
lons[0] = lon
lats[0] = lat
depths[0] = depth
return lons, lats, depths
[docs]def point_at(lon, lat, azimuth, distance):
"""
Perform a forward geodetic transformation: find a point lying at a given
distance from a given one on a great circle arc defined by azimuth.
:param float lon, lat:
Coordinates of a reference point, in decimal degrees.
:param azimuth:
An azimuth of a great circle arc of interest measured in a reference
point in decimal degrees.
:param distance:
Distance to target point in km.
:returns:
Tuple of two float numbers: longitude and latitude of a target point
in decimal degrees respectively.
Implements the same approach as :func:`npoints_towards`.
"""
# this is a simplified version of npoints_towards().
# code duplication is justified by performance reasons.
lon, lat = numpy.radians(lon), numpy.radians(lat)
tc = numpy.radians(360 - azimuth)
sin_dists = numpy.sin(distance / EARTH_RADIUS)
cos_dists = numpy.cos(distance / EARTH_RADIUS)
sin_lat = numpy.sin(lat)
cos_lat = numpy.cos(lat)
sin_lats = sin_lat * cos_dists + cos_lat * sin_dists * numpy.cos(tc)
sin_lats = sin_lats.clip(-1., 1.)
lats = numpy.degrees(numpy.arcsin(sin_lats))
dlon = numpy.arctan2(numpy.sin(tc) * sin_dists * cos_lat,
cos_dists - sin_lat * sin_lats)
lons = numpy.mod(lon - dlon + numpy.pi, 2 * numpy.pi) - numpy.pi
lons = numpy.degrees(lons)
return lons, lats
[docs]def distance_to_semi_arc(alon, alat, aazimuth, plons, plats):
"""
In this method we use a reference system centerd on (alon, alat) and with
the y-axis corresponding to aazimuth direction to calculate the minimum
distance from a semiarc with generates in (alon, alat).
Parameters are the same as for :func:`distance_to_arc`.
"""
if type(plons) is float:
plons = numpy.array([plons])
plats = numpy.array([plats])
azimuth_to_target = azimuth(alon, alat, plons, plats)
# Find the indexes of the points in the positive y halfspace
idx = numpy.nonzero(numpy.cos(
numpy.radians((aazimuth-azimuth_to_target))) > 0.0)
# Find the indexes of the points in the negative y halfspace
idx_not = numpy.nonzero(numpy.cos(
numpy.radians((aazimuth-azimuth_to_target))) <= 0.0)
idx_ll_quadr = numpy.nonzero(
(numpy.cos(numpy.radians((aazimuth-azimuth_to_target))) <= 0.0) &
(numpy.sin(numpy.radians((aazimuth-azimuth_to_target))) > 0.0))
# Initialise the array containing the final distances
distance = numpy.zeros_like(plons)
# Compute the distance between the semi-arc with 'aazimuth' direction
# and the set of sites in the positive half-space. The shortest distance to
# the semi-arc in this case can be computed using the function
# :func:`openquake.hazardlib.geo.geodetic.distance_to_arc`.
if len(idx):
distance_to_target = geodetic_distance(alon, alat,
plons[idx], plats[idx])
t_angle = (azimuth_to_target[idx] - aazimuth + 360) % 360
angle = numpy.arccos((numpy.sin(numpy.radians(t_angle)) *
numpy.sin(distance_to_target /
EARTH_RADIUS)).clip(-1, 1))
distance[idx] = (numpy.pi / 2 - angle) * EARTH_RADIUS
# Compute the distance between the reference point and the set of sites
# in the negative half-space. The shortest distance for the semi-arc for
# all the points in the negative semi-space simply corresponds to the
# shortest distance to its origin.
if len(idx_not):
distance[idx_not] = geodetic_distance(alon, alat,
plons[idx_not], plats[idx_not])
distance[idx_ll_quadr] = -1 * distance[idx_ll_quadr]
return distance
[docs]def distance_to_arc(alon, alat, aazimuth, plons, plats):
"""
Calculate a closest distance between a great circle arc and a point
(or a collection of points).
:param float alon, alat:
Arc reference point longitude and latitude, in decimal degrees.
:param azimuth:
Arc azimuth (an angle between direction to a north and arc in clockwise
direction), measured in a reference point, in decimal degrees.
:param float plons, plats:
Longitudes and latitudes of points to measure distance. Either scalar
values or numpy arrays of decimal degrees.
:returns:
Distance in km, a scalar value or numpy array depending on ``plons``
and ``plats``. A distance is negative if the target point lies on the
right hand side of the arc.
Solves a spherical triangle formed by reference point, target point and
a projection of target point to a reference great circle arc.
"""
azimuth_to_target = azimuth(alon, alat, plons, plats)
distance_to_target = geodetic_distance(alon, alat, plons, plats)
# find an angle between an arc and a great circle arc connecting
# arc's reference point and a target point
t_angle = (azimuth_to_target - aazimuth + 360) % 360
# in a spherical right triangle cosine of the angle of a cathetus
# augmented to pi/2 is equal to sine of an opposite angle times
# sine of hypotenuse, see
# http://en.wikipedia.org/wiki/Spherical_trigonometry#Napier.27s_Pentagon
angle = numpy.arccos(
(numpy.sin(numpy.radians(t_angle))
* numpy.sin(distance_to_target / EARTH_RADIUS)).clip(-1, 1)
)
return (numpy.pi / 2 - angle) * EARTH_RADIUS
def _prepare_coords(lons1, lats1, lons2, lats2):
"""
Convert two pairs of spherical coordinates in decimal degrees
to numpy arrays of radians. Makes sure that respective coordinates
in pairs have the same shape.
"""
lons1 = numpy.array(numpy.radians(lons1))
lats1 = numpy.array(numpy.radians(lats1))
assert lons1.shape == lats1.shape
lons2 = numpy.array(numpy.radians(lons2))
lats2 = numpy.array(numpy.radians(lats2))
assert lons2.shape == lats2.shape
return lons1, lats1, lons2, lats2
try:
from openquake.hazardlib.geo import _geodetic_speedups
except ImportError:
# speedups extension is not available
import warnings
warnings.warn("geodetic speedups are not available", RuntimeWarning)
else:
from openquake.hazardlib import speedups
def _c_min_geodetic_distance(mlons, mlats, slons, slats):
mlons, mlats, slons, slats = _prepare_coords(mlons, mlats,
slons, slats)
mdepths = sdepths = numpy.array(0.0)
return _geodetic_speedups.min_distance(mlons, mlats, mdepths,
slons, slats, sdepths,
indices=False)
speedups.register(min_geodetic_distance, _c_min_geodetic_distance)
del _c_min_geodetic_distance
def _c_min_distance(mlons, mlats, mdepths,
slons, slats, sdepths, indices=False):
assert not indices or mlons.ndim > 0
mlons, mlats, slons, slats = _prepare_coords(mlons, mlats,
slons, slats)
mdepths = numpy.array(mdepths, float)
sdepths = numpy.array(sdepths, float)
assert mlons.shape == mdepths.shape
assert slons.shape == sdepths.shape
return _geodetic_speedups.min_distance(mlons, mlats, mdepths,
slons, slats, sdepths, indices)
speedups.register(min_distance, _c_min_distance)
del _c_min_distance