Geodetic calculations

Module openquake.hazardlib.geo.geodetic contains functions for geodetic transformations, optimized for massive calculations.

openquake.hazardlib.geo.geodetic.EARTH_RADIUS = 6371.0

Earth radius in km.

class openquake.hazardlib.geo.geodetic.GeographicObjects(objects, getlon=<operator.attrgetter object>, getlat=<operator.attrgetter 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).

get_closest(lon, lat, max_distance=None)

Get the closest object to the given longitude and latitude and its distance. If the max_distance is given and all objects are farther than the maximum distance, returns (None, None).

Parameters:

• lon – longitude in degrees
• lat – latitude in degrees
• max_distance – distance in km (or None)

openquake.hazardlib.geo.geodetic.azimuth(lons1, lats1, lons2, lats2)

Calculate the azimuth between two points or two collections of points.

Parameters are the same as for 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.

openquake.hazardlib.geo.geodetic.distance(lons1, lats1, depths1, lons2, lats2, depths2)

Calculate a distance between two points (or collections of points) considering points’ depth.

Calls 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 geodetic distance and vertical distance, which is just a difference between depths.

openquake.hazardlib.geo.geodetic.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).

Parameters:

• alon, alat (float) – Arc reference point longitude and latitude, in decimal degrees.
• azimuth – Arc azimuth (an angle between direction to a north and arc in clockwise direction), measured in a reference point, in decimal degrees.
• plons, plats (float) – 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.

openquake.hazardlib.geo.geodetic.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 distance_to_arc().

openquake.hazardlib.geo.geodetic.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.

openquake.hazardlib.geo.geodetic.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.

Parameters:

• lon1, lat1, depth1 (float) – Coordinates of a point to start placing intervals from. The first point in the resulting list has these coordinates.
• lon2, lat2, depth2 (float) – 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.
• 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 npoints_towards().

openquake.hazardlib.geo.geodetic.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 geodetic_distance() for distance along great circle arc and the same approach as in distance() for combining it with depth distance.

Parameters:

• mlons, mlats, mdepths (array) – 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).
• slons, slats, sdepths (array) – 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.
• 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.

openquake.hazardlib.geo.geodetic.min_distance_to_segment(seglons, seglats, lons, lats)

This function computes the shortest distance to a segment in a 2D reference system.

Parameters:

• seglons – A list or an array of floats specifying the longitude values of the two vertexes delimiting the segment.
• seglats – A list or an array of floats specifying the latitude values of the two vertexes delimiting the segment.
• 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.
• 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.

openquake.hazardlib.geo.geodetic.min_geodetic_distance(mlons, mlats, slons, slats)

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

openquake.hazardlib.geo.geodetic.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.

Parameters:

• lon1, lat1, depth1 (float) – Coordinates of a point to start from. The first point in a resulting list has these coordinates.
• lon2, lat2, depth2 (float) – Coordinates of a point to finish at. The last point in a resulting list has these coordinates.
• 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 npoints_towards().

openquake.hazardlib.geo.geodetic.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.

Parameters:

• lon, lat, depth (float) – Coordinates of a point to start from. The first point in a resulting list has these coordinates.
• azimuth – A direction representing a great circle arc together with a reference point.
• hdist – Horizontal (geodetic) distance from reference point to the last point of the resulting list, in km.
• vdist – Vertical (depth) distance between reference and the last point, in km.
• 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

openquake.hazardlib.geo.geodetic.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.

Parameters:

• lon, lat (float) – Coordinates of a reference point, in decimal degrees.
• azimuth – An azimuth of a great circle arc of interest measured in a reference point in decimal degrees.
• 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 npoints_towards().