Source code for openquake.hazardlib.geo.geodetic

# -*- coding: utf-8 -*-
# vim: tabstop=4 shiftwidth=4 softtabstop=4
#
# Copyright (C) 2012-2020 GEM Foundation
#
# OpenQuake 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.
#
# OpenQuake 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 OpenQuake. If not, see <http://www.gnu.org/licenses/>.

"""
Module :mod:`openquake.hazardlib.geo.geodetic` contains functions for geodetic
transformations, optimized for massive calculations.
"""
import numpy
from scipy.spatial.distance import cdist
from openquake.baselib.python3compat import round

#: Earth radius in km.
EARTH_RADIUS = 6371.0

#: Maximum elevation on Earth in km.
EARTH_ELEVATION = -8.848


[docs]def geodetic_distance(lons1, lats1, lons2, lats2, diameter=2*EARTH_RADIUS): """ 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 )) return diameter * 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
def _reshape(array, orig_shape): if orig_shape: return array.reshape(orig_shape) return array[0] # scalar array
[docs]def spherical_to_cartesian(lons, lats, depths=None): """ Return the position vectors (in Cartesian coordinates) of list of spherical coordinates. For equations see: http://mathworld.wolfram.com/SphericalCoordinates.html. Parameters are components of spherical coordinates in a form of scalars, lists or numpy arrays. ``depths`` can be ``None`` in which case it's considered zero for all points. :returns: ``numpy.array`` of 3d vectors representing points' coordinates in Cartesian space in km. The array has shape `lons.shape + (3,)`. In particular, if ``lons`` and ``lats`` are scalars the result is a 3D vector and if they are vectors the result is a matrix of shape (N, 3). See also :func:`cartesian_to_spherical`. """ phi = numpy.radians(lons) theta = numpy.radians(lats) if depths is None: rr = EARTH_RADIUS else: rr = EARTH_RADIUS - numpy.array(depths) cos_theta_r = rr * numpy.cos(theta) try: shape = lons.shape except AttributeError: # a list/tuple was passed try: shape = (len(lons),) except TypeError: # a scalar was passed shape = () arr = numpy.zeros(shape + (3,)) arr[..., 0] = cos_theta_r * numpy.cos(phi) arr[..., 1] = cos_theta_r * numpy.sin(phi) arr[..., 2] = rr * numpy.sin(theta) return arr
[docs]def min_geodetic_distance(a, b): """ Compute the minimum distance between first mesh and each point of the second mesh when both are defined on the earth surface. :param a: a pair of (lons, lats) or an array of cartesian coordinates :param b: a pair of (lons, lats) or an array of cartesian coordinates """ if isinstance(a, tuple): a = spherical_to_cartesian(a[0].flatten(), a[1].flatten()) if isinstance(b, tuple): b = spherical_to_cartesian(b[0].flatten(), b[1].flatten()) return cdist(a, b).min(axis=0)
[docs]def distance_matrix(lons, lats, diameter=2*EARTH_RADIUS): """ :param lons: array of m longitudes :param lats: array of m latitudes :returns: matrix of (m, m) distances """ m = len(lons) assert m == len(lats), (m, len(lats)) lons = numpy.radians(lons) lats = numpy.radians(lats) cos_lats = numpy.cos(lats) result = numpy.zeros((m, m)) for i in range(len(lons)): a = numpy.sin((lats[i] - lats) / 2.0) b = numpy.sin((lons[i] - lons) / 2.0) result[i, :] = numpy.arcsin( numpy.sqrt(a * a + cos_lats[i] * cos_lats * b * b)) * diameter return result
[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) 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) 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))) 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)) ) 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.radians(lons1) lats1 = numpy.radians(lats1) assert lons1.shape == lats1.shape lons2 = numpy.radians(lons2) lats2 = numpy.radians(lats2) assert lons2.shape == lats2.shape return lons1, lats1, lons2, lats2