l3py.grid

Point distributions on the ellipsoid.

grid.ellipsoidal_distance(lat1, lon2, lat2, a=6378137.0, f=0.003352810681182319)

Compute the distance between points (lon1, lat1) and (lon2, lat2) on an ellipsoid with semi-major axis a and flattening f.

Parameters:

• lon1 (float, array_like(m,), array_like(m,n)) – longitude of source points in radians
• lat1 (float, array_like(m,), array_like(m,n)) – latitude of source points in radians
• lon2 (float, array_like(m,), array_like(m,n)) – longitude of target points in radians
• lat2 (float, array_like(m,), array_like(m,n)) – latitude of target points in radians
• a (float) – semi-major axis of ellipsoid
• f (float) – flattening of ellipsoid

Returns:

d – ellipsoidal distance between points (lon1, lat1) and (lon2, lat2) in meters

Return type:

ndarray(m,), ndarray(m,n)

Notes

This function uses the approximation formula by Lambert [1] and gives meter level accuracy.

References

[1]	Lambert, W. D (1942). “The distance between two widely separated points on the surface of the earth”. J. Washington Academy of Sciences. 32 (5): 125–130.

grid.spherical_distance(lat1, lon2, lat2, r=6378136.3)

Compute the spherical distance between points (lon1, lat1) and (lon2, lat2) on a sphere with radius r.

Parameters:

• lon1 (float, array_like(m,), array_like(m,n)) – longitude of source points in radians
• lat1 (float, array_like(m,), array_like(m,n)) – latitude of source points in radians
• lon2 (float, array_like(m,), array_like(m,n)) – longitude of target points in radians
• lat2 (float, array_like(m,), array_like(m,n)) – latitude of target points in radians
• r (float) – radius of the sphere in meters

Returns:

d – spherical distance between points (lon1, lat1) and (lon2, lat2) in meters

Return type:

ndarray(m,), ndarray(m,n)

grid.winding_number(x, y)

Winding number algorithm for point in polygon tests.

Parameters:

• polygon (ndarray(k, 2)) – two-column ndarray with longitude/latitude pairs defining the polygon
• x (ndarray(m,), ndarray(m,n)) – x-coordinates of points to be tested
• y (ndarray(m,), ndarray(m,n)) – y-coordinates of points to be tested

Returns:

contains – boolean array indicating which point is contained in the polygon

Return type:

ndarray(m,), ndarray(m,n)

class l3py.grid.Basin(polygons)

Simple class representation of an area enclosed by a polygon boundary, potentially with holes. No sanity checking for potential geometry errors is performed.

Parameters:polygons (ndarray(k, 2) or list of ndarray(k, 2)) – Coordinates defining the basin. Can be either a single two-column ndarray with longitude/latitude pairs for rows, or a list of ndarrays in the same format. Longitude/latitude should be given in radians.

Methods

contains_points(lon, lat)

Method to check whether points are within the basin bounds.

contains_points(lon, lat)

Method to check whether points are within the basin bounds.

Parameters:

• lon (float, ndarray(m,), ndarray(m,n)) – longitude of points to be tested (should be given in radians)
• lat (float, ndarray(m,), ndarray(m,n)) – latitude of points to be tested (should be given in radians)

class l3py.grid.GeographicGrid(dlon=0.5, dlat=0.5, a=6378137.0, f=0.003352810681182319)

Class representation of a (possibly time stampled) global geographic grid defined by step size in longitude and latitude.

The resulting point coordinates are center points of area elements (pixels). This means that for dlon=dlat=1 the lower left coordinate will be (-179.5, -89.5) and the upper right (179.5, 89.5) degrees.

Parameters:

• dlon (float) – longitudinal step size in degrees
• dlat (float) – latitudinal step size in degrees
• a (float) – semi-major axis of ellipsoid
• f (float) – flattening of ellipsoid

Methods

colatitude()	Colatitude of the points along a meridian.
copy()	Deep copy of GeographicGrid instance.
create_mask(basin)	Create a mask (boolean array) for the Geographic grid instance based on a polygon.
mean([mask])	Compute the weighted average of grid points, potentially with a mask.
radius()	Geocentric radius of the points along a meridian.

is_regular

colatitude()

Colatitude of the points along a meridian.

copy()

Deep copy of GeographicGrid instance.

create_mask(basin)

Create a mask (boolean array) for the Geographic grid instance based on a polygon.

Parameters:basin (Basin) – Basin instance. Returns:mask – boolean array of size(nlons, nlats), True for points inside the polygon, False for points outside. Return type:array_like(m,n)

mean(mask=None)

Compute the weighted average of grid points, potentially with a mask. The individual points are weighted by their area elements.

Parameters:mask (array_like(nlons, nlats), None) – boolean array with the same shape as the value array. If None, all points are averaged. Returns:mean – weighted mean over all grid points in mask Return type:float

See also

l3py.grid.GeographicGrid.create_mask()

member function which creates masks from polygons

radius()

Geocentric radius of the points along a meridian.

class l3py.grid.Grid

Base interface for point collections.

Subclasses must implement a deep copy, getter for radius and colatitude as well as a method which returns whether the grid is regular (e.g. equiangular geographic coordinates) or an arbitrary point distribution.

Methods

colatitude
copy
is_regular
radius