pyrocko.orthodrome¶
Some basic geodetic functions.
Functions

Azimuth and backazimuth from location A towards B and back. 

Azimuth and backazimuth from location A towards B and back. 

Calculation of the azimuth (track angle) and the distance from locations A towards B on a sphere. 

Absolute latitudes and longitudes are calculated from relative changes. 

Absolute latitudes and longitudes are calculated from relative changes. 

Azimuth calculation. 

Calculation of the azimuth (track angle) from a location A towards B. 

Clip values of an array. 

Test if point is inside polygon on a sphere. 

Test which points are inside polygon on a sphere. 

Cosine of the angular distance between two points 

Cosine of the angular distance between two points 

Accurate distance calculation based on a spheroid of rotation. 

Accurate distance calculation based on a spheroid of rotation. 

Convert EarthCentered, EarthFixed (ECEF) Cartesian coordinates to geodetic coordinates (Ferrari's solution). 

Convert geodetic coordinates to EarthCentered, EarthFixed (ECEF) Cartesian coordinates. 

Calculate geographic midpoints by finding the center of gravity. 

Relative cartesian coordinates with respect to a reference location. 

Relative cartesian coordinates with respect to a reference location. 

Transform local cartesian coordinates to latitude and longitude. 

Transform local cartesian coordinates to latitude and longitude. 

Check if a point is contained in a rectangular geographical region. 

Check what points are contained in a rectangular geographical region. 

Normalize parameterization of a rectangular geographical region. 

Get a rectangular region which fully contains a given circular region. 

Wrapping continuous data to fundamental phase values. 
Classes

Simple location representation. 
 class Loc(lat, lon)[source]¶
Bases:
object
Simple location representation.
 Attrib lat:
Latitude in [deg].
 Attrib lon:
Longitude in [deg].
 clip(x, mi, ma)[source]¶
Clip values of an array.
 Parameters:
x (
numpy.ndarray
) – Continunous data to be clipped.mi (float) – Clip minimum.
ma (float) – Clip maximum.
 Returns:
Clipped data.
 Return type:
 wrap(x, mi, ma)[source]¶
Wrapping continuous data to fundamental phase values.
 Parameters:
x (
numpy.ndarray
) – Continunous data to be wrapped.mi (float) – Minimum value of wrapped data.
ma (float) – Maximum value of wrapped data.
 Returns:
Wrapped data.
 Return type:
 cosdelta(*args)[source]¶
Cosine of the angular distance between two points
a
andb
on a sphere.This function (find implementation below) returns the cosine of the distance angle ‘delta’ between two points
a
andb
, coordinates of which are expected to be given in geographical coordinates and in degrees. For numerical stability a maximum of 1.0 is enforced. Parameters:
a (
pyrocko.orthodrome.Loc
) – Location point A.b (
pyrocko.orthodrome.Loc
) – Location point B.
 Returns:
Cosdelta.
 Return type:
 cosdelta_numpy(a_lats, a_lons, b_lats, b_lons)[source]¶
Cosine of the angular distance between two points
a
andb
on a sphere.This function returns the cosines of the distance angles delta between two points
a
andb
given asnumpy.ndarray
. The coordinates are expected to be given in geographical coordinates and in degrees. For numerical stability a maximum of1.0
is enforced.Please find the details of the implementation in the documentation of the function
pyrocko.orthodrome.cosdelta()
above. Parameters:
a_lats (
numpy.ndarray
) – Latitudes in [deg] point A.a_lons (
numpy.ndarray
) – Longitudes in [deg] point A.b_lats (
numpy.ndarray
) – Latitudes in [deg] point B.b_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point B.
 Returns:
Cosdelta.
 azimuth(*args)[source]¶
Azimuth calculation.
This function (find implementation below) returns azimuth … between points
a
andb
, coordinates of which are expected to be given in geographical coordinates and in degrees. Parameters:
a (
pyrocko.orthodrome.Loc
) – Location point A.b (
pyrocko.orthodrome.Loc
) – Location point B.
 Returns:
Azimuth in degree
 azimuth_numpy(a_lats, a_lons, b_lats, b_lons, _cosdelta=None)[source]¶
Calculation of the azimuth (track angle) from a location A towards B.
This function returns azimuths (track angles) from locations A towards B given in
numpy.ndarray
. Coordinates are expected to be given in geographical coordinates and in degrees.Please find the details of the implementation in the documentation of the function
pyrocko.orthodrome.azimuth()
. Parameters:
a_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point A.a_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point A.b_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point B.b_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point B.
 Returns:
Azimuths in [deg].
 Return type:
numpy.ndarray
,(N)
 azibazi_numpy(a_lats, a_lons, b_lats, b_lons, implementation='c')[source]¶
Azimuth and backazimuth from location A towards B and back.
Arguments are given as
numpy.ndarray
. Parameters:
a_lats (
numpy.ndarray
) – Latitude(s) in [deg] of point A.a_lons (
numpy.ndarray
) – Longitude(s) in [deg] of point A.b_lats (
numpy.ndarray
) – Latitude(s) in [deg] of point B.b_lons (
numpy.ndarray
) – Longitude(s) in [deg] of point B.
 Returns:
Azimuth(s) in [deg] from A to B, back azimuth(s) in [deg] from B to A.
 Return type:
 azidist_numpy(*args)[source]¶
Calculation of the azimuth (track angle) and the distance from locations A towards B on a sphere.
The assisting functions used are
pyrocko.orthodrome.cosdelta()
andpyrocko.orthodrome.azimuth()
 Parameters:
a_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point A.a_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point A.b_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point B.b_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point B.
 Returns:
Azimuths in [deg], distances in [deg].
 Return type:
numpy.ndarray
,(2xN)
 distance_accurate50m(*args, **kwargs)[source]¶
Accurate distance calculation based on a spheroid of rotation.
Function returns distance in meter between points A and B, coordinates of which must be given in geographical coordinates and in degrees. The returned distance should be accurate to 50 m using WGS84. Values for the Earth’s equator radius and the Earth’s oblateness (
f_oblate
) are defined in the pyrocko configuration filepyrocko.config
.From wikipedia (http://de.wikipedia.org/wiki/Orthodrome), based on:
Meeus, J.: Astronomical Algorithms, S 85, WillmannBell, Richmond 2000 (2nd ed., 2nd printing), ISBN 0943396611
The sphericalearth distance D between A and B, can be given with:
The oblateness of the Earth requires some correction with correction factors h1 and h2:
 Parameters:
a (
pyrocko.orthodrome.Loc
) – Location point A.b (
pyrocko.orthodrome.Loc
) – Location point B.
 Returns:
Distance in [m].
 Return type:
 distance_accurate50m_numpy(a_lats, a_lons, b_lats, b_lons, implementation='c')[source]¶
Accurate distance calculation based on a spheroid of rotation.
Function returns distance in meter between points
a
andb
, coordinates of which must be given in geographical coordinates and in degrees. The returned distance should be accurate to 50 m using WGS84. Values for the Earth’s equator radius and the Earth’s oblateness (f_oblate
) are defined in the pyrocko configuration filepyrocko.config
.From wikipedia (http://de.wikipedia.org/wiki/Orthodrome), based on:
Meeus, J.: Astronomical Algorithms, S 85, WillmannBell, Richmond 2000 (2nd ed., 2nd printing), ISBN 0943396611
The sphericalearth distance
D
betweena
andb
, can be given with:The oblateness of the Earth requires some correction with correction factors
h1
andh2
: Parameters:
a_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point A.a_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point A.b_lats (
numpy.ndarray
,(N)
) – Latitudes in [deg] point B.b_lons (
numpy.ndarray
,(N)
) – Longitudes in [deg] point B.
 Returns:
Distances in [m].
 Return type:
numpy.ndarray
,(N)
 ne_to_latlon(lat0, lon0, north_m, east_m)[source]¶
Transform local cartesian coordinates to latitude and longitude.
From east and north coordinates (
x
andy
coordinatenumpy.ndarray
) relative to a reference differences in longitude and latitude are calculated, which are effectively changes in azimuth and distance, respectively:The projection used preserves the azimuths of the input points.
 Parameters:
lat0 (float) – Latitude origin of the cartesian coordinate system in [deg].
lon0 (float) – Longitude origin of the cartesian coordinate system in [deg].
north_m (
numpy.ndarray
,(N)
) – Northing distances from origin in [m].east_m (
numpy.ndarray
,(N)
) – Easting distances from origin in [m].
 Returns:
Array with latitudes and longitudes in [deg].
 Return type:
numpy.ndarray
,(2xN)
 azidist_to_latlon(lat0, lon0, azimuth_deg, distance_deg)[source]¶
Absolute latitudes and longitudes are calculated from relative changes.
Convenience wrapper to
azidist_to_latlon_rad()
with azimuth and distance given in degrees. Parameters:
lat0 (float) – Latitude origin of the cartesian coordinate system in [deg].
lon0 (float) – Longitude origin of the cartesian coordinate system in [deg].
azimuth_deg (
numpy.ndarray
,(N)
) – Azimuth from origin in [deg].distance_deg (
numpy.ndarray
,(N)
) – Distances from origin in [deg].
 Returns:
Array with latitudes and longitudes in [deg].
 Return type:
numpy.ndarray
,(2xN)
 azidist_to_latlon_rad(lat0, lon0, azimuth_rad, distance_rad)[source]¶
Absolute latitudes and longitudes are calculated from relative changes.
For numerical stability a range between of
1.0
and1.0
is enforced forc
andalpha
. Parameters:
lat0 (float) – Latitude origin of the cartesian coordinate system in [deg].
lon0 (float) – Longitude origin of the cartesian coordinate system in [deg].
distance_rad (
numpy.ndarray
,(N)
) – Distances from origin in [rad].azimuth_rad (
numpy.ndarray
,(N)
) – Azimuth from origin in [rad].
 Returns:
Array with latitudes and longitudes in [deg].
 Return type:
numpy.ndarray
,(2xN)
 ne_to_latlon_alternative_method(lat0, lon0, north_m, east_m)[source]¶
Transform local cartesian coordinates to latitude and longitude.
Like
pyrocko.orthodrome.ne_to_latlon()
, but this method (implementation below), although it should be numerically more stable, suffers problems at points which are across the pole as seen from the cartesian origin. Parameters:
lat0 (float) – Latitude origin of the cartesian coordinate system in [deg].
lon0 (float) – Longitude origin of the cartesian coordinate system in [deg].
north_m (
numpy.ndarray
,(N)
) – Northing distances from origin in [m].east_m (
numpy.ndarray
,(N)
) – Easting distances from origin in [m].
 Returns:
Array with latitudes and longitudes in [deg].
 Return type:
numpy.ndarray
,(2xN)
 latlon_to_ne(*args)[source]¶
Relative cartesian coordinates with respect to a reference location.
For two locations, a reference location A and another location B, given in geographical coordinates in degrees, the corresponding cartesian coordinates are calculated. Assisting functions are
pyrocko.orthodrome.azimuth()
andpyrocko.orthodrome.distance_accurate50m()
. Parameters:
refloc (
pyrocko.orthodrome.Loc
) – Location reference point.loc (
pyrocko.orthodrome.Loc
) – Location of interest.
 Returns:
Northing and easting from refloc to location in [m].
 Return type:
 latlon_to_ne_numpy(lat0, lon0, lat, lon)[source]¶
Relative cartesian coordinates with respect to a reference location.
For two locations, a reference location (
lat0
,lon0
) and another location B, given in geographical coordinates in degrees, the corresponding cartesian coordinates are calculated. Assisting functions areazimuth()
anddistance_accurate50m()
. Parameters:
lat0 – Latitude of the reference location in [deg].
lon0 – Longitude of the reference location in [deg].
lat – Latitude of the absolute location in [deg].
lon – Longitude of the absolute location in [deg].
 Returns:
(n, e)
: relative north and east positions in [m]. Return type:
numpy.ndarray
,(2xN)
Implemented formulations:
 points_in_region(p, region)[source]¶
Check what points are contained in a rectangular geographical region.
 Parameters:
p (
numpy.ndarray
(N, 2)
) –(lat, lon)
pairs in [deg].region (
tuple
offloat
) –(west, east, south, north)
region boundaries in [deg].
 Returns:
Mask, returning
True
for each point within the region. Return type:
numpy.ndarray
of bool, shape(N)
 point_in_region(p, region)[source]¶
Check if a point is contained in a rectangular geographical region.
 radius_to_region(lat, lon, radius)[source]¶
Get a rectangular region which fully contains a given circular region.
 Parameters:
 Returns:
Rectangular region as
(east, west, south, north)
in [deg] orNone
. Return type:
 geographic_midpoint(lats, lons, weights=None, depths=None, earthradius=6371000.0)[source]¶
Calculate geographic midpoints by finding the center of gravity.
This method suffers from instabilities if points are centered around the poles.
 Parameters:
lats (
numpy.ndarray
,(N)
) – Latitudes in [deg].lons (
numpy.ndarray
,(N)
) – Longitudes in [deg].weights (optional,
numpy.ndarray
,(N)
) – Weighting factors.depths (optional,
numpy.ndarray
,(N)
) – Depths in [m].
 Returns:
Latitudes and longitudes of the midpoint in [deg] (and depth [m] if depths are given).
 Return type:
(lat, lon)
or(lat, lon, depth)
 geodetic_to_ecef(lat, lon, alt)[source]¶
Convert geodetic coordinates to EarthCentered, EarthFixed (ECEF) Cartesian coordinates. [3] [4]
 ecef_to_geodetic(X, Y, Z)[source]¶
Convert EarthCentered, EarthFixed (ECEF) Cartesian coordinates to geodetic coordinates (Ferrari’s solution).
 Parameters:
 Returns:
Geodetic coordinates (lat, lon, alt). Latitude and longitude are in [deg] and altitude is in [m] (positive for points outside the geoid).
 Return type:
See also
https://en.wikipedia.org/wiki/Geographic_coordinate_conversion #The_application_of_Ferrari.27s_solution
 contains_points(polygon, points)[source]¶
Test which points are inside polygon on a sphere.
The inside of the polygon is defined as the area which is to the left hand side of an observer walking the polygon line, points in order, on the sphere. Lines between the polygon points are treated as great circle paths. The polygon may be arbitrarily complex, as long as it does not have any crossings or thin parts with zero width. The polygon may contain the poles and is allowed to wrap around the sphere multiple times.
The algorithm works by consecutive cutting of the polygon into (almost) hemispheres and subsequent Gnomonic projections to perform the pointinpolygon tests on a 2D plane.
 Parameters:
polygon (
numpy.ndarray
of shape(N, 2)
, second index 0=lat, 1=lon) – Point coordinates defining the polygon [deg].points (
numpy.ndarray
of shape(N, 2)
, second index 0=lat, 1=lon) – Coordinates of points to test [deg].
 Returns:
Boolean mask array.
 Return type:
numpy.ndarray
of shape(N,)
.
 contains_point(polygon, point)[source]¶
Test if point is inside polygon on a sphere.
Convenience wrapper to
contains_points()
to test a single point. Parameters:
polygon (
numpy.ndarray
of shape(N, 2)
, second index 0=lat, 1=lon) – Point coordinates defining the polygon [deg].point (
tuple
offloat
) – Coordinates(lat, lon)
of point to test [deg].
 Returns:
True
, if point is located within polygon, elseFalse
. Return type: