bordado.great_circle_coordinates

bordado.great_circle_coordinates(beginning, end, *, size=None, spacing=None, radius=6370994, non_dimensional_coords=None)

Generate evenly spaced coordinates along a great circle between points.

The beginning and end points must be (longitude, latitude) coordinates on a sphere. The generated coordinates will be evenly spaced (in physical distances, not degrees) and fall along a great circle path between the two points. The points can be specified by size (number of points) or their spacing (in physical units, like meters).

Use this function to generates coordinates for sampling along a profile when data are in geographic coordinates.

Parameters:

beginningtuple = (longitude, latitude)

The coordinates of the starting point of the profile. Coordinates must be single values and not array-like. Units should be decimal degrees.

endtuple = (longitude, latitude)

The coordinates of the ending point of the profile. Coordinates must be single values and not array-like. Units should be decimal degrees.

sizeint or None

The number of points in the profile. If None, spacing must be provided.

spacingfloat or None

The step size (interval) between points in the profile. If None, size must be provided. Units should be compatible with radius (usually meters).

radiusfloat

The radius of the sphere, usually the mean radius of the Earth or other body used to scale the distances along the great circle. Units should be compatible with spacing (usually meters). Defaults to the mean radius of the WGS84 Earth ellipsoid (6,370,994 meters).

non_dimensional_coordsNone, scalar, or tuple of scalars

If not None, then value(s) of extra non-dimensional coordinates (coordinates that aren’t part of the profile dimensions, like height for a lat/lon profile). Will generate extra coordinate arrays from these values with the same shape of the final profile coordinates and the constant value given here. Use this to generate arrays of constant heights or times, for example, which might be needed to accompany a profile.

Returns:

coordinatestuple = (longitude, latitude, …)

Arrays with the coordinates of each point in the profile. The first two are longitude and latitude. Subsequent arrays are any extra values given in non_dimensional_coords. All arrays will be 1-dimensional and have the same shape.

distancesarray

The great circle distances between each point in the profile and the beginning point.

Examples

Generate coordinates between points at the equator for a sphere with a unit radius:

>>> import numpy as np
>>> spacing = 2 * np.pi / 180
>>> (longitude, latitude), distance = great_circle_coordinates(
...     (0, 0), (10, 0), spacing=spacing, radius=1,
... )
>>> print('longitude:', ', '.join(f'{i:.1f}' for i in longitude))
longitude: 0.0, 2.0, 4.0, 6.0, 8.0, 10.0
>>> print('latitude:', ', '.join(f'{i:.1f}' for i in latitude))
latitude: 0.0, 0.0, 0.0, 0.0, 0.0, 0.0
>>> print('distance:', ', '.join(f'{i:.4f}' for i in distance))
distance: 0.0000, 0.0349, 0.0698, 0.1047, 0.1396, 0.1745
>>> print(np.allclose(distance[1:] - distance[0:-1], spacing))
True

It can sometimes be useful to generate an additional array of the same size as the coordinates but filled with a single value, for example if we also need a constant height value returned:

>>> (lon, lat, height), dist = great_circle_coordinates(
...     (1, 10), (1, 20), size=11, non_dimensional_coords=35)
>>> print(height)
[35. 35. 35. 35. 35. 35. 35. 35. 35. 35. 35.]