# orthodrome¶

exception Slow[source]
class Loc(lat, lon)[source]

Simple location representation.

Attrib lat

Latitude in [deg].

Attrib lon

Longitude in [deg].

clip(x, mi, ma)[source]

Clip values of an array.

Parameters
Returns

Clipped data.

Return type

numpy.ndarray

wrap(x, mi, ma)[source]

Wrapping continuous data to fundamental phase values. Parameters
Returns

Wrapped data.

Return type

numpy.ndarray

cosdelta(*args)[source]

Cosine of the angular distance between two points a and b on a sphere.

This function (find implementation below) returns the cosine of the distance angle ‘delta’ between two points a and b, 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
Returns

Cosdelta.

Return type

float

cosdelta_numpy(a_lats, a_lons, b_lats, b_lons)[source]

Cosine of the angular distance between two points a and b on a sphere.

This function returns the cosines of the distance angles delta between two points a and b given as numpy.ndarray. The coordinates are expected to be given in geographical coordinates and in degrees. For numerical stability a maximum of 1.0 is enforced.

Please find the details of the implementation in the documentation of the function pyrocko.orthodrome.cosdelta() above.

Parameters
Returns

Cosdelta.

azimuth(*args)[source]

Azimuth calculation.

This function (find implementation below) returns azimuth … between points a and b, coordinates of which are expected to be given in geographical coordinates and in degrees. Parameters
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
Returns

Azimuths in [deg].

Return type

numpy.ndarray, (N)

azibazi(*args, **kwargs)[source]

Azimuth and backazimuth from location A towards B and back.

Returns

Azimuth in [deg] from A to B, back azimuth in [deg] from B to A.

Return type
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
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() and pyrocko.orthodrome.azimuth()

Parameters
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 file pyrocko.config.

From wikipedia (http://de.wikipedia.org/wiki/Orthodrome), based on:

Meeus, J.: Astronomical Algorithms, S 85, Willmann-Bell, Richmond 2000 (2nd ed., 2nd printing), ISBN 0-943396-61-1  The spherical-earth 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
Returns

Distance in [m].

Return type

float

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 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 file pyrocko.config.

From wikipedia (http://de.wikipedia.org/wiki/Orthodrome), based on:

Meeus, J.: Astronomical Algorithms, S 85, Willmann-Bell, Richmond 2000 (2nd ed., 2nd printing), ISBN 0-943396-61-1  The spherical-earth 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
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 and y coordinate numpy.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)

Absolute latitudes and longitudes are calculated from relative changes.

For numerical stability a range between of -1.0 and 1.0 is enforced for c and alpha.   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() and pyrocko.orthodrome.distance_accurate50m(). Parameters
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 are azimuth() and distance_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: positive_region(region)[source]

Normalize parameterization of a rectangular geographical region.

Parameters

region (tuple of float) – (west, east, south, north) in [deg].

Returns

(west, east, south, north), where west <= east and where west and east are in the range [-180., 180.+360.].

Return type

tuple of float

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 of float) – (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.

Parameters
• p (tuple of float) – (lat, lon) in [deg].

• region (tuple of float) – (west, east, south, north) region boundaries in [deg].

Returns

True, if point is in region, else False.

Return type

bool

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

Parameters
• lat (float) – Latitude of the center point of circular region in [deg].

• lon (float) – Longitude of the center point of circular region in [deg].

Returns

Rectangular region as (east, west, south, north) in [deg] or None.

Return type
geographic_midpoint(lats, lons, weights=None)[source]

Calculate geographic midpoints by finding the center of gravity.

This method suffers from instabilities if points are centered around the poles.

Parameters
Returns

Latitudes and longitudes of the midpoints in [deg].

Return type

numpy.ndarray, (2xN)

geodetic_to_ecef(lat, lon, alt)[source]

Convert geodetic coordinates to Earth-Centered, Earth-Fixed (ECEF) Cartesian coordinates. 3 4

Parameters
• lat (float) – Geodetic latitude in [deg].

• lon (float) – Geodetic longitude in [deg].

• alt (float) – Geodetic altitude (height) in [m] (positive for points outside the geoid).

Returns

ECEF Cartesian coordinates (X, Y, Z) in [m].

Return type
3

https://en.wikipedia.org/wiki/ECEF

4

https://en.wikipedia.org/wiki/Geographic_coordinate_conversion #From_geodetic_to_ECEF_coordinates

ecef_to_geodetic(X, Y, Z)[source]

Convert Earth-Centered, Earth-Fixed (ECEF) Cartesian coordinates to geodetic coordinates (Ferrari’s solution).

Parameters

Z (X, Y,) – Cartesian coordinates in ECEF system in [m].

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

https://en.wikipedia.org/wiki/Geographic_coordinate_conversion #The_application_of_Ferrari.27s_solution

exception Farside[source]
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 point-in-polygon 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

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 of float) – Coordinates (lat, lon) of point to test [deg].

Returns

True, if point is located within polygon, else False.

Return type

bool