Various utilities

Module openquake.hazardlib.geo.utils contains functions that are common to several geographical primitives and some other low-level spatial operations.

class openquake.hazardlib.geo.utils.OrthographicProjection(west, east, north, south)

Callable object to compute orthographic projections. See the docstring of get_orthographic_projection.

openquake.hazardlib.geo.utils.cartesian_to_spherical(vectors)

Return the spherical coordinates for coordinates in Cartesian space.

This function does an opposite to spherical_to_cartesian().

Parameters:vectors – Array of 3d vectors in Cartesian space. Returns:Tuple of three arrays of the same shape as vectors representing longitude (decimal degrees), latitude (decimal degrees) and depth (km) in specified order.

openquake.hazardlib.geo.utils.clean_points(points)

Given a list of Point objects, return a new list with adjacent duplicate points removed.

openquake.hazardlib.geo.utils.cross_idl(lon1, lon2)

Return True if two longitude values define line crossing international date line.

>>> cross_idl(-45, 45)
False
>>> cross_idl(-180, -179)
False
>>> cross_idl(180, 179)
False
>>> cross_idl(45, -45)
False
>>> cross_idl(0, 0)
False
>>> cross_idl(-170, 170)
True
>>> cross_idl(170, -170)
True
>>> cross_idl(-180, 180)
True

openquake.hazardlib.geo.utils.get_longitudinal_extent(lon1, lon2)

Return the distance between two longitude values as an angular measure. Parameters represent two longitude values in degrees.

Returns:Float, the angle between lon1 and lon2 in degrees. Value is positive if lon2 is on the east from lon1 and negative otherwise. Absolute value of the result doesn’t exceed 180 for valid parameters values.

openquake.hazardlib.geo.utils.get_middle_point(lon1, lat1, lon2, lat2)

Given two points return the point exactly in the middle lying on the same great circle arc.

Parameters are point coordinates in degrees.

Returns:Tuple of longitude and latitude of the point in the middle.

openquake.hazardlib.geo.utils.get_orthographic_projection(west, east, north, south)

Create and return a projection object for a given bounding box.

Returns:callable OrthographicProjection object that can perform both forward and reverse projection (converting from longitudes and latitudes to x and y values on 2d-space and vice versa). The call takes three arguments: first two are numpy arrays of longitudes and latitudes or abscissae and ordinates of points to project and the third one is a boolean that allows to choose what operation is requested – is it forward or reverse one. True value given to third positional argument (or keyword argument “reverse”) indicates that the projection of points in 2d space back to earth surface is needed. The default value for “reverse” argument is False, which means forward projection (degrees to kilometers).

Raises ValueError in forward projection mode if any of the target points is further than 90 degree (along the great circle arc) from the projection center.

Parameters are given as floats, representing decimal degrees (first two are longitudes and last two are latitudes). They define a bounding box in a spherical coordinates of the collection of points that is about to be projected. The center point of the projection (coordinates (0, 0) in Cartesian space) is set to the middle point of that bounding box. The resulting projection is defined for spherical coordinates that are not further from the bounding box center than 90 degree on the great circle arc.

The result projection is of type Orthographic. This projection is prone to distance, area and angle distortions everywhere outside of the center point, but still can be used for checking shapes: verifying if line intersects itself (like in line_intersects_itself()) or if point is inside of a polygon (like in openquake.hazardlib.geo.polygon.Polygon.discretize()). It can be also used for measuring distance to an extent of around 700 kilometers (error doesn’t exceed 1 km up until then).

openquake.hazardlib.geo.utils.get_spherical_bounding_box(lons, lats)

Given a collection of points find and return the bounding box, as a pair of longitudes and a pair of latitudes.

Parameters define longitudes and latitudes of a point collection respectively in a form of lists or numpy arrays.

Returns:A tuple of four items. These items represent western, eastern, northern and southern borders of the bounding box respectively. Values are floats in decimal degrees. Raises:ValueError – If points collection has the longitudinal extent of more than 180 degrees (it is impossible to define a single hemisphere bound to poles that would contain the whole collection).

openquake.hazardlib.geo.utils.line_intersects_itself(lons, lats, closed_shape=False)

Return True if line of points intersects itself. Line with the last point repeating the first one considered intersecting itself.

The line is defined by lists (or numpy arrays) of points’ longitudes and latitudes (depth is not taken into account).

Parameters:closed_shape – If True the line will be checked twice: first time with its original shape and second time with the points sequence being shifted by one point (the last point becomes first, the first turns second and so on). This is useful for checking that the sequence of points defines a valid Polygon.

openquake.hazardlib.geo.utils.normalized(vector)

Get unit vector for a given one.

Parameters:vector – Numpy vector as coordinates in Cartesian space, or an array of such. Returns:Numpy array of the same shape and structure where all vectors are normalized. That is, each coordinate component is divided by its vector’s length.

openquake.hazardlib.geo.utils.plane_fit(points)

This fits an n-dimensional plane to a set of points. See http://stackoverflow.com/questions/12299540/plane-fitting-to-4-or-more-xyz-points

Parameters:points – An instance of :class:~numpy.ndarray. The number of columns must be equal to three. Returns:A point on the plane and the normal to the plane.

openquake.hazardlib.geo.utils.point_to_polygon_distance(polygon, pxx, pyy)

Calculate the distance to polygon for each point of the collection on the 2d Cartesian plane.

Parameters:

• polygon – Shapely “Polygon” geometry object.
• pxx – List or numpy array of abscissae values of points to calculate the distance from.
• pyy – Same structure as pxx, but with ordinate values.

Returns:

Numpy array of distances in units of coordinate system. Points that lie inside the polygon have zero distance.

openquake.hazardlib.geo.utils.spherical_to_cartesian(lons, lats, depths)

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. The array has the same shape as parameter arrays. In particular it means that if lons and lats are scalars, the result is a single 3d vector. Vector of length 1 represents distance of 1 km.

See also cartesian_to_spherical().

openquake.hazardlib.geo.utils.triangle_area(e1, e2, e3)

Get the area of triangle formed by three vectors.

Parameters are three three-dimensional numpy arrays representing vectors of triangle’s edges in Cartesian space.

Returns:Float number, the area of the triangle in squared units of coordinates, or numpy array of shape of edges with one dimension less.

Uses Heron formula, see http://mathworld.wolfram.com/HeronsFormula.html.