spatial
Utilities for reading and operating on spatial data
Can read netCDF4, HDF5 or geotiff files
Calling Sequence
Reading a netCDF4 file
import icesat2_toolkit.spatial
dinput = icesat2_toolkit.spatial.from_netCDF4(path_to_netCDF4_file)
Reading a HDF5 file
import icesat2_toolkit.spatial
dinput = icesat2_toolkit.spatial.from_HDF5(path_to_HDF5_file)
General Methods
- icesat2_toolkit.spatial.case_insensitive_filename(filename: str | pathlib.Path)[source]
Searches a directory for a filename without case dependence
- Parameters
- filename: str
input filename
- icesat2_toolkit.spatial.from_file(filename: str, format: str, **kwargs)[source]
Wrapper function for reading data from an input format
- Parameters
- filename: str
full path of input file
- format: str
format of input file
- **kwargs: dict
Keyword arguments for file reader
- icesat2_toolkit.spatial.from_netCDF4(filename: str, **kwargs)[source]
Read data from a netCDF4 file
- Parameters
- filename: str
full path of input netCDF4 file
- compression: str or NoneType, default None
file compression type
- timename: str, default ‘time’
name for time-dimension variable
- xname: str, default ‘lon’
name for x-dimension variable
- yname: str, default ‘lat’
name for y-dimension variable
- varname: str, default ‘data’
name for data variable
- field_mapping: dict, default {}
mapping between output variables and input netCDF4
- icesat2_toolkit.spatial.from_HDF5(filename: str | pathlib.Path, **kwargs)[source]
Read data from a HDF5 file
- Parameters
- filename: str
full path of input HDF5 file
- compression: str or NoneType, default None
file compression type
- timename: str, default ‘time’
name for time-dimension variable
- xname: str, default ‘lon’
name for x-dimension variable
- yname: str, default ‘lat’
name for y-dimension variable
- varname: str, default ‘data’
name for data variable
- field_mapping: dict, default {}
mapping between output variables and input HDF5
- icesat2_toolkit.spatial.from_geotiff(filename: str, **kwargs)[source]
Read data from a geotiff file
- Parameters
- filename: str
full path of input geotiff file
- compression: str or NoneType, default None
file compression type
- bounds: list or NoneType, default bounds
extent of the file to read:
[xmin, xmax, ymin, ymax]
- icesat2_toolkit.spatial.convert_ellipsoid(phi1: ndarray, h1: ndarray, a1: float, f1: float, a2: float, f2: float, eps: float = 1e-12, itmax: int = 10)[source]
Convert latitudes and heights to a different ellipsoid using Newton-Raphson
- Parameters
- phi1: np.ndarray
latitude of input ellipsoid in degrees
- h1: np.ndarray
height above input ellipsoid in meters
- a1: float
semi-major axis of input ellipsoid
- f1: float
flattening of input ellipsoid
- a2: float
semi-major axis of output ellipsoid
- f2: float
flattening of output ellipsoid
- eps: float, default 1e-12
tolerance to prevent division by small numbers and to determine convergence
- itmax: int, default 10
maximum number of iterations to use in Newton-Raphson
- Returns
- phi2: np.ndarray
latitude of output ellipsoid in degrees
- h2: np.ndarray
height above output ellipsoid in meters
References
- 1
Meeus, Astronomical Algorithms, 2nd edition, 477 pp., (1998).
- icesat2_toolkit.spatial.compute_delta_h(a1: float, f1: float, a2: float, f2: float, lat: ndarray)[source]
- Compute difference in elevation for two ellipsoids at a given
latitude using a simplified empirical equation
- Parameters
- a1: float
semi-major axis of input ellipsoid
- f1: float
flattening of input ellipsoid
- a2: float
semi-major axis of output ellipsoid
- f2: float
flattening of output ellipsoid
- lat: np.ndarray
latitudes (degrees north)
- Returns
- delta_h: np.ndarray
difference in elevation for two ellipsoids
References
- 1
J Meeus, Astronomical Algorithms, pp. 77–82, (1991).
- icesat2_toolkit.spatial.wrap_longitudes(lon: float | numpy.ndarray)[source]
Wraps longitudes to range from -180 to +180
- Parameters
- lon: float or np.ndarray
longitude (degrees east)
- icesat2_toolkit.spatial.to_cartesian(lon: ndarray, lat: ndarray, h: float | numpy.ndarray = 0.0, a_axis: float = 6378137.0, flat: float = 0.0033528106647474805)[source]
Converts geodetic coordinates to Cartesian coordinates
- Parameters
- lon: np.ndarray
longitude (degrees east)
- lat: np.ndarray
latitude (degrees north)
- h: float or np.ndarray, default 0.0
height above ellipsoid (or sphere)
- a_axis: float, default 6378137.0
semimajor axis of the ellipsoid
for spherical coordinates set to radius of the Earth
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
for spherical coordinates set to 0
- icesat2_toolkit.spatial.to_sphere(x: ndarray, y: ndarray, z: ndarray)[source]
Convert from cartesian coordinates to spherical coordinates
- Parameters
- x, np.ndarray
cartesian x-coordinates
- y, np.ndarray
cartesian y-coordinates
- z, np.ndarray
cartesian z-coordinates
- icesat2_toolkit.spatial.to_geodetic(x: ndarray, y: ndarray, z: ndarray, a_axis: float = 6378137.0, flat: float = 0.0033528106647474805, method: str = 'bowring', eps: float = 2.220446049250313e-16, iterations: int = 10)[source]
Convert from cartesian coordinates to geodetic coordinates using either iterative or closed-form methods
- Parameters
- x, float
cartesian x-coordinates
- y, float
cartesian y-coordinates
- z, float
cartesian z-coordinates
- a_axis: float, default 6378137.0
semimajor axis of the ellipsoid
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
- method: str, default ‘bowring’
method to use for conversion
'moritz'
: iterative solution'bowring'
: iterative solution'zhu'
: closed-form solution
- eps: float, default np.finfo(np.float64).eps
tolerance for iterative methods
- iterations: int, default 10
maximum number of iterations
- icesat2_toolkit.spatial._moritz_iterative(x: ndarray, y: ndarray, z: ndarray, a_axis: float = 6378137.0, flat: float = 0.0033528106647474805, eps: float = 2.220446049250313e-16, iterations: int = 10)[source]
Convert from cartesian coordinates to geodetic coordinates using the iterative solution of [1]
- Parameters
- x, float
cartesian x-coordinates
- y, float
cartesian y-coordinates
- z, float
cartesian z-coordinates
- a_axis: float, default 6378137.0
semimajor axis of the ellipsoid
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
- eps: float, default np.finfo(np.float64).eps
tolerance for iterative method
- iterations: int, default 10
maximum number of iterations
References
- 1
B. Hofmann-Wellenhof and H. Moritz, Physical Geodesy, 2nd Edition, 403 pp., (2006). doi: 10.1007/978-3-211-33545-1
- icesat2_toolkit.spatial._bowring_iterative(x: ndarray, y: ndarray, z: ndarray, a_axis: float = 6378137.0, flat: float = 0.0033528106647474805, eps: float = 2.220446049250313e-16, iterations: int = 10)[source]
Convert from cartesian coordinates to geodetic coordinates using the iterative solution of [1] [2]
- Parameters
- x, float
cartesian x-coordinates
- y, float
cartesian y-coordinates
- z, float
cartesian z-coordinates
- a_axis: float, default 6378137.0
semimajor axis of the ellipsoid
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
- eps: float, default np.finfo(np.float64).eps
tolerance for iterative method
- iterations: int, default 10
maximum number of iterations
References
- 1
B. R. Bowring, “Transformation from spatial to geodetic coordinates,” Survey Review, 23(181), 323–327, (1976). doi: 10.1179/sre.1976.23.181.323
- 2
B. R. Bowring, “The Accuracy Of Geodetic Latitude and Height Equations,” Survey Review, 28(218), 202–206, (1985). doi: 10.1179/sre.1985.28.218.202
- icesat2_toolkit.spatial._zhu_closed_form(x: ndarray, y: ndarray, z: ndarray, a_axis: float = 6378137.0, flat: float = 0.0033528106647474805)[source]
Convert from cartesian coordinates to geodetic coordinates using the closed-form solution of [1]
- Parameters
- x, float
cartesian x-coordinates
- y, float
cartesian y-coordinates
- z, float
cartesian z-coordinates
- a_axis: float, default 6378137.0
semimajor axis of the ellipsoid
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
References
- 1
J. Zhu, “Exact conversion of Earth-centered, Earth-fixed coordinates to geodetic coordinates,” Journal of Guidance, Control, and Dynamics, 16(2), 389–391, (1993). doi: 10.2514/3.21016
- icesat2_toolkit.spatial.scale_factors(lat: ndarray, flat: float = 0.0033528106647474805, reference_latitude: float = 70.0, metric: str = 'area')[source]
Calculates scaling factors to account for polar stereographic distortion including special case of at the exact pole [1] [2]
- Parameters
- lat: np.ndarray
latitude (degrees north)
- flat: float, default 1.0/298.257223563
ellipsoidal flattening
- reference_latitude: float, default 70.0
reference latitude (true scale latitude)
- metric: str, default ‘area’
metric to calculate scaling factors
'distance'
: scale factors for distance'area'
: scale factors for area
- Returns
- scale: np.ndarray
scaling factors at input latitudes
References
- icesat2_toolkit.spatial.inside_polygon(x: ndarray, y: ndarray, xpts: ndarray, ypts: ndarray, threshold: float = 0.01)[source]
Indicates whether a specified 2D point is inside a specified 2D polygon
- Parameters
- x: np.ndarray
x-coordinates of the 2D point(s) to check
- y: np.ndarray
y-coordinates of the 2D point(s) to check
- xpts: np.ndarray
x-coordinates of the 2D polygon.
- ypts: np.ndarray
y-coordinates of the 2D polygon
- threshold: float, default 0.01
minimum angle for checking if inside polygon
- Returns
- flag: np.ndarray
flag denoting if points are within polygon
True
: within polygonFalse
: outside polygon