Ctrl+K

clouddrift.sphere

clouddrift.sphere#

This module provides functions for spherical geometry calculations.

Functions

bearing(lon1, lat1, lon2, lat2)

Return elementwise initial (forward) bearing in radians from arrays of latitude and longitude in degrees, based on the spherical law of cosines.

cartesian_to_spherical(x, y, z)

Converts Cartesian three-dimensional coordinates to latitude and longitude on a spherical body.

cartesian_to_tangentplane(u, v, w, ...)

Project a three-dimensional Cartesian vector on a plane tangent to a spherical Earth.

coriolis_frequency(latitude)

Return the Coriolis frequency or commonly known f parameter in geophysical fluid dynamics.

cumulative_distance(longitude, latitude)

Return the cumulative great circle distance in meters along a sequence of geographical locations.

distance(lon1, lat1, lon2, lat2)

Return elementwise great circle distance in meters between one or more points from arrays of their latitudes and longitudes, using the Haversine formula.

plane_to_sphere(x, y[, lon_origin, lat_origin])

Convert Cartesian coordinates on a plane to spherical coordinates.

position_from_distance_and_bearing(lon, lat, ...)

Return elementwise new position in degrees from arrays of latitude and longitude in degrees, distance in meters, and bearing in radians, based on the spherical law of cosines.

recast_lon(lon[, lon0])

Recast (convert) longitude values to a selected range of 360 degrees starting from lon0.

recast_lon180(lon)

Recast (convert) longitude values to the range [-180, 180[.

recast_lon360(lon)

Recast (convert) longitude values to the range [0, 360[.

sphere_to_plane(lon, lat[, lon_origin, ...])

Convert spherical coordinates to a tangent (Cartesian) plane.

spherical_to_cartesian(lon, lat[, radius])

Converts latitude and longitude on a spherical body to

tangentplane_to_cartesian(up, vp, longitude, ...)

Return the three-dimensional Cartesian components of a vector contained in a plane tangent to a spherical Earth.
clouddrift.sphere.bearing(lon1: float | list | ndarray | DataArray, lat1: float | list | ndarray | DataArray, lon2: float | list | ndarray | DataArray, lat2: float | list | ndarray | DataArray) → float | ndarray[source]#

Return elementwise initial (forward) bearing in radians from arrays of latitude and longitude in degrees, based on the spherical law of cosines.

The formula is:

θ = atan2(cos φ1 ⋅ sin φ2 - sin φ1 ⋅ cos φ2 ⋅ cos Δλ, sin Δλ ⋅ cos φ2)

where (φ, λ) is (lat, lon) and θ is bearing, all in radians. Bearing is defined as zero toward East and positive counterclockwise.

Parameters#

lon1float or array-like

Longitudes of the first set of points, in degrees

lat1float or array-like

Latitudes of the first set of points, in degrees

lon2float or array-like

Longitudes of the second set of points, in degrees

lat2float or array-like

Latitudes of the second set of points, in degrees

Returns#

thetafloat or np.ndarray

Bearing angles in radians

Examples#

Calculate the bearing of one degree longitude on the equator:

>>> bearing(0, 0, 1, 0)
0.0

Calculate the bearing of 10 degrees longitude at 45-degrees North latitude:

>>> bearing(0, 45, 10, 45)
0.06178508761798218
clouddrift.sphere.cartesian_to_spherical(x: float | ndarray | DataArray, y: float | ndarray | DataArray, z: float | ndarray | DataArray) → tuple[ndarray, ndarray][source]#

Converts Cartesian three-dimensional coordinates to latitude and longitude on a spherical body.

The Cartesian coordinate system is a right-handed system whose origin lies at the center of the sphere. It is oriented with the Z-axis passing through the poles and the X-axis passing through the point lon = 0, lat = 0. This function is inverted by spherical_to_cartesian.

Parameters#

xfloat or array-like

x-coordinates in 3D.

yfloat or array-like

y-coordinates in 3D.

zfloat or array-like

z-coordinates in 3D.

Returns#

lonfloat or array-like

An N-d array of longitudes in degrees in range [-180, 180].

latfloat or array-like

An N-d array of latitudes in degrees.

Examples#

>>> x = EARTH_RADIUS_METERS * np.cos(np.deg2rad(45))
>>> y = EARTH_RADIUS_METERS * np.cos(np.deg2rad(45))
>>> z = 0 * x
>>> cartesian_to_spherical(x, y, z)
(44.99999999999985, 0.0)

cartesian_to_spherical is inverted by spherical_to_cartesian:

>>> x, y, z = spherical_to_cartesian(np.array([45]),np.array(0))
>>> cartesian_to_spherical(x, y, z)
(array([45.]), array([0.]))

Raises#

AttributeError

If x, y, and z are not NumPy arrays.

See Also#

spherical_to_cartesian()

clouddrift.sphere.cartesian_to_tangentplane(u: float | ndarray, v: float | ndarray, w: float | ndarray, longitude: float | ndarray, latitude: float | ndarray) → tuple[float] | tuple[ndarray][source]#

Project a three-dimensional Cartesian vector on a plane tangent to a spherical Earth.

The Cartesian coordinate system is a right-handed system whose origin lies at the center of a sphere. It is oriented with the Z-axis passing through the north pole at lat = 90, the X-axis passing through the point lon = 0, lat = 0, and the Y-axis passing through the point lon = 90, lat = 0.

Parameters#

ufloat or np.ndarray

First component of Cartesian vector.

vfloat or np.ndarray

Second component of Cartesian vector.

wfloat or np.ndarray

Third component of Cartesian vector.

longitudefloat or np.ndarray

Longitude in degrees of tangent point of plane.

latitudefloat or np.ndarray

Latitude in degrees of tangent point of plane.

Returns#

up: float or np.ndarray

First component of projected vector on tangent plane (positive eastward).

vp: float or np.ndarray

Second component of projected vector on tangent plane (positive northward).

Raises#

Warning

Raised if the input latitude is not in the expected range [-90, 90].

Examples#

>>> u, v = cartesian_to_tangentplane(1, 1, 1, 45, 90)

See Also#

tangentplane_to_cartesian()

clouddrift.sphere.coriolis_frequency(latitude: float | ndarray) → float | ndarray[source]#

Return the Coriolis frequency or commonly known f parameter in geophysical fluid dynamics.

Parameters#

latitudefloat or np.ndarray

Latitude in degrees.

Returns#

ffloat or np.ndarray

Signed Coriolis frequency in radian per seconds.

Examples#

>>> f = coriolis_frequency(np.array([0, 45, 90]))
clouddrift.sphere.cumulative_distance(longitude: list | ndarray | DataArray, latitude: list | ndarray | DataArray) → ndarray[source]#

Return the cumulative great circle distance in meters along a sequence of geographical locations.

Parameters#

latitudearray-like

Latitude sequence, in degrees.

longitudearray-like

Longitude sequence, in degrees.

Returns#

outnp.ndarray

Cumulative distance.

See Also#

distance()

Examples#

Calculate the cumulative distance in meters along a path of three points:

>>> cumulative_distance(np.array([0, 1, 2]), np.array([0, 1, 2]))
array([     0.        , 157424.62387233, 314825.27182116])
clouddrift.sphere.distance(lon1: float | list | ndarray | DataArray, lat1: float | list | ndarray | DataArray, lon2: float | list | ndarray | DataArray, lat2: float | list | ndarray | DataArray) → float | ndarray[source]#

Return elementwise great circle distance in meters between one or more points from arrays of their latitudes and longitudes, using the Haversine formula.

d = 2⋅r⋅asin √[sin²(Δφ/2) + cos φ1 ⋅ cos φ2 ⋅ sin²(Δλ/2)]

where (φ, λ) is (lat, lon) in radians and r is the radius of the sphere in meters.

Parameters#

lon1np.ndarray

Longitudes of the first set of points, in degrees

lat1np.ndarray

Latitudes of the first set of points, in degrees

lon2np.ndarray

Longitudes of the second set of points, in degrees

lat2np.ndarray

Latitudes of the second set of points, in degrees

Returns#

outnp.ndarray

Great circle distance

Examples#

Calculate the distance of one degree longitude on the equator:

>>> distance(0, 0, 0, 1)
111318.84502145034

Calculate the distance of one degree longitude at 45-degrees North latitude:

>>> distance(0, 45, 1, 45)
78713.81064540472

You can also pass array-like inputs to calculate an array of distances:

>>> distance([0, 0], [0, 45], [0, 1], [1, 45])
array([111318.84502145,  78713.8106454 ])
clouddrift.sphere.plane_to_sphere(x: ndarray, y: ndarray, lon_origin: float = 0, lat_origin: float = 0) → tuple[ndarray, ndarray][source]#

Convert Cartesian coordinates on a plane to spherical coordinates.

The arrays of input zonal and meridional displacements x and y are assumed to follow a contiguous trajectory. The spherical coordinate of each successive point is determined by following a great circle path from the previous point. The spherical coordinate of the first point is determined by following a great circle path from the origin, by default (0, 0).

The output arrays have the same floating-point output type as the input.

If projecting multiple trajectories onto the same plane, use apply_ragged() for highest accuracy.

Parameters#

xnp.ndarray

An N-d array of zonal displacements in meters

ynp.ndarray

An N-d array of meridional displacements in meters

lon_originfloat, optional

Origin longitude of the tangent plane in degrees, default 0

lat_originfloat, optional

Origin latitude of the tangent plane in degrees, default 0

Returns#

lonnp.ndarray

Longitude in degrees

latnp.ndarray

Latitude in degrees

Examples#

>>> plane_to_sphere(np.array([0., 0.]), np.array([0., 1000.]))
(array([0.00000000e+00, 5.50062664e-19]), array([0.       , 0.0089832]))

You can also specify an origin longitude and latitude:

>>> plane_to_sphere(np.array([0., 0.]), np.array([0., 1000.]), lon_origin=1, lat_origin=0)
(array([1., 1.]), array([0.       , 0.0089832]))

Raises#

AttributeError

If x and y are not NumPy arrays

See Also#

sphere_to_plane()

clouddrift.sphere.position_from_distance_and_bearing(lon: float, lat: float, distance: float, bearing: float) → tuple[float, float][source]#

Return elementwise new position in degrees from arrays of latitude and longitude in degrees, distance in meters, and bearing in radians, based on the spherical law of cosines.

The formula is:

φ2 = asin( sin φ1 ⋅ cos δ + cos φ1 ⋅ sin δ ⋅ cos θ ) λ2 = λ1 + atan2( sin θ ⋅ sin δ ⋅ cos φ1, cos δ − sin φ1 ⋅ sin φ2 )

where (φ, λ) is (lat, lon) and θ is bearing, all in radians. Bearing is defined as zero toward East and positive counterclockwise.

Parameters#

lonfloat

Longitude of the first set of points, in degrees

latfloat

Latitude of the first set of points, in degrees

distancearray_like

Distance in meters

bearingarray_like

Bearing angles in radians

Returns#

lon2array_like

Latitudes of the second set of points, in degrees, in the range [-90, 90]

lat2array_like

Longitudes of the second set of points, in degrees, in the range [-180, 180]

Examples#

Calculate the position of one degree longitude distance on the equator:

>>> position_from_distance_and_bearing(0, 0, 111318.84502145034, 0)
(1.0, 0.0)

Calculate the position of one degree latitude distance from 45 degrees North latitude:

>>> position_from_distance_and_bearing(0, 45, 111318.84502145034, np.pi / 2)
(8.81429402840006e-17, 45.99999999999999)
clouddrift.sphere.recast_lon(lon: ndarray, lon0: float | None = -180) → ndarray[source]#

Recast (convert) longitude values to a selected range of 360 degrees starting from lon0.

Parameters#

lonnp.ndarray or float

An N-d array of longitudes in degrees

lon0float, optional

Starting longitude of the recasted range (default -180).

Returns#

np.ndarray or float

Converted longitudes in the range [lon0, lon0+360[

Examples#

By default, recast_lon converts longitude values to the range [-180, 180[:

>>> recast_lon(200)
-160

>>> recast_lon(180)
-180

The range of the output longitude is controlled by lon0. For example, with lon0 = 0, the longitude values are converted to the range [0, 360[.

>>> recast_lon(200, -180)
-160

With lon0 = 20, longitude values are converted to range [20, 380], which can be useful to avoid cutting the major ocean basins.

>>> recast_lon(10, 20)
370

See Also#

recast_lon360(), recast_lon180()

clouddrift.sphere.recast_lon180(lon: ndarray) → ndarray[source]#

Recast (convert) longitude values to the range [-180, 180[. This is a convenience wrapper around recast_lon() with lon0 = -180.

Parameters#

lonnp.ndarray

An N-d array of longitudes in degrees

Returns#

np.ndarray

Converted longitudes in the range [-180, 180[

Examples#

>>> recast_lon180(200)
-160

>>> recast_lon180(-200)
160

See Also#

recast_lon(), recast_lon360()

clouddrift.sphere.recast_lon360(lon: ndarray) → ndarray[source]#

Recast (convert) longitude values to the range [0, 360[. This is a convenience wrapper around recast_lon() with lon0 = 0.

Parameters#

lonnp.ndarray

An N-d array of longitudes in degrees

Returns#

np.ndarray

Converted longitudes in the range [0, 360[

Examples#

>>> recast_lon360(200)
200

>>> recast_lon360(-200)
160

See Also#

recast_lon(), recast_lon180()

clouddrift.sphere.sphere_to_plane(lon: ndarray, lat: ndarray, lon_origin: float = 0, lat_origin: float = 0) → tuple[ndarray, ndarray][source]#

Convert spherical coordinates to a tangent (Cartesian) plane.

The arrays of input longitudes and latitudes are assumed to be following a contiguous trajectory. The Cartesian coordinate of each successive point is determined by following a great circle path from the previous point. The Cartesian coordinate of the first point is determined by following a great circle path from the origin, by default (0, 0).

The output arrays have the same floating-point output type as the input.

If projecting multiple trajectories onto the same plane, use apply_ragged() for highest accuracy.

Parameters#

lonnp.ndarray

An N-d array of longitudes in degrees

latnp.ndarray

An N-d array of latitudes in degrees

lon_originfloat, optional

Origin longitude of the tangent plane in degrees, default 0

lat_originfloat, optional

Origin latitude of the tangent plane in degrees, default 0

Returns#

xnp.ndarray

x-coordinates on the tangent plane

ynp.ndarray

y-coordinates on the tangent plane

Examples#

>>> sphere_to_plane(np.array([0., 1.]), np.array([0., 0.]))
(array([     0.        , 111318.84502145]), array([0., 0.]))

You can also specify an origin longitude and latitude:

>>> sphere_to_plane(np.array([0., 1.]), np.array([0., 0.]), lon_origin=1, lat_origin=0)
(array([-111318.84502145,       0.        ]),
 array([1.36326267e-11, 1.36326267e-11]))

Raises#

AttributeError

If lon and lat are not NumPy arrays

See Also#

plane_to_sphere()

clouddrift.sphere.spherical_to_cartesian(lon: float | list | ndarray | DataArray, lat: float | list | ndarray | DataArray, radius: float | None = 6378100.0) → tuple[ndarray, ndarray, ndarray][source]#
Converts latitude and longitude on a spherical body to

three-dimensional Cartesian coordinates.

The Cartesian coordinate system is a right-handed system whose origin lies at the center of a sphere. It is oriented with the Z-axis passing through the poles and the X-axis passing through the point lon = 0, lat = 0. This function is inverted by cartesian_to_spherical().

Parameters#

lonarray-like

An N-d array of longitudes in degrees.

latarray-like

An N-d array of latitudes in degrees.

radius: float, optional

The radius of the spherical body in meters. The default assumes the Earth with EARTH_RADIUS_METERS = 6.3781e6.

Returns#

xfloat or array-like

x-coordinates in 3D in meters.

yfloat or array-like

y-coordinates in 3D in meters.

zfloat or array-like

z-coordinates in 3D in meters.

Examples#

>>> spherical_to_cartesian(np.array([0, 45]), np.array([0, 45]))
(array([6378100., 3189050.]),
array([      0., 3189050.]),
array([      0.        , 4509997.76108592]))

>>> spherical_to_cartesian(np.array([0, 45, 90]), np.array([0, 90, 180]), radius=1)
(array([ 1.00000000e+00,  4.32978028e-17, -6.12323400e-17]),
array([ 0.00000000e+00,  4.32978028e-17, -1.00000000e+00]),
array([0.0000000e+00, 1.0000000e+00, 1.2246468e-16]))

>>> x, y, z = spherical_to_cartesian(np.array([0, 5]), np.array([0, 5]))

Raises#

AttributeError

If lon and lat are not NumPy arrays.

See Also#

cartesian_to_spherical()

clouddrift.sphere.tangentplane_to_cartesian(up: float | ndarray, vp: float | ndarray, longitude: float | ndarray, latitude: float | ndarray) → tuple[float] | tuple[ndarray][source]#

Return the three-dimensional Cartesian components of a vector contained in a plane tangent to a spherical Earth.

The Cartesian coordinate system is a right-handed system whose origin lies at the center of a sphere. It is oriented with the Z-axis passing through the north pole at lat = 90, the X-axis passing through the point lon = 0, lat = 0, and the Y-axis passing through the point lon = 90, lat = 0.

Parameters#

up: float or np.ndarray

First component of vector on tangent plane (positive eastward).

vp: float or np.ndarray

Second component of vector on tangent plane (positive northward).

longitudefloat or np.ndarray

Longitude in degrees of tangent point of plane.

latitudefloat or np.ndarray

Latitude in degrees of tangent point of plane.

Returns#

ufloat or np.ndarray

First component of Cartesian vector.

vfloat or np.ndarray

Second component of Cartesian vector.

wfloat or np.ndarray

Third component of Cartesian vector.

Examples#

>>> u, v, w = tangentplane_to_cartesian(1, 1, 45, 90)

Notes#

This function is inverted by cartesian_to_tangetplane().

See Also#

cartesian_to_tangentplane()

Contents