API reference#
This page provides a summary of xDEM’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.
Examples using xdem.DEM#
DEM#
Important
A DEM inherits all raster methods and attributes from the Raster object of GeoUtils.
Below, we only repeat some core attributes and methods of GeoUtils, see
the Raster API in GeoUtils for the full list.
Opening or saving#
|
The digital elevation model. |
|
Write the raster to file. |
Plotting or summarize info#
Create from an array#
|
Create a DEM from a numpy array and the georeferencing information. |
Unique attributes#
Inherited from Raster#
Array of the raster. |
|
Coordinate reference system of the raster. |
|
Geotransform of the raster. |
|
Nodata value of the raster. |
|
Pixel interpretation of the raster. |
Specific to DEM#
Vertical coordinate reference system of the DEM. |
Other attributes#
Inherited from Raster#
See the full list in the Raster API of GeoUtils.
Resolution (X, Y) of the raster in georeferenced units. |
|
Bounding coordinates of the raster. |
|
Width of the raster in pixels. |
|
Height of the raster in pixels. |
|
Shape (i.e., height, width) of the raster in pixels. |
Georeferencing#
Inherited from Raster#
|
Set a new nodata value for all bands. |
|
Set new pixel interpretation of the raster. |
|
|
|
|
|
Vertical referencing for DEM#
|
Set the vertical coordinate reference system of the DEM. |
|
Raster-vector interface#
Note
See the full list of vector methods in GeoUtils’ documentation.
|
Polygonize the raster into a vector. |
|
Compute proximity distances to the raster target pixels, or to a vector geometry on the raster grid. |
|
Convert raster to point cloud. |
|
Statistics#
|
Terrain attributes#
|
Generate a slope map for a DEM, returned in degrees by default. |
|
Calculate the aspect of each cell in a DEM, returned in degrees by default. |
|
Generate a hillshade from the given DEM. |
|
Calculates profile curvature in units of m-1 multiplied by 100. |
|
Calculates tangential curvature in units of m-1 multiplied by 100. |
|
Calculates planform (or plan) curvature in units of m-1 multiplied by 100., defined as the curvature of a projection of the contour line onto a horizontal plane. |
|
Calculates flow line curvature in units of m-1 multiplied by 100. |
|
Calculate the maximal (geometric) or maximum (directional derivative) curvature in units of m-1 multiplied by 100. |
|
Calculate the minimal (geometric) or minimum (directional derivative) curvature in units of m-1 multiplied by 100. |
Calculates the Topographic Position Index, the difference to the average of neighbouring pixels. |
|
|
Calculates the Terrain Ruggedness Index, the cumulated differences to neighbouring pixels. |
|
Calculates the roughness, the maximum difference between neighbouring pixels, for any window size. |
|
Calculates the rugosity, the ratio between real area and planimetric area. |
|
Calculates the fractal roughness, the local 3D fractal dimension. |
|
Generate a texture shaded relief map using fractional Laplacian operator. |
Or to get multiple related terrain attributes at once (for performance):
|
Derive one or multiple terrain attributes from a DEM. |
Coregistration and bias corrections#
Tip
To build and pass your coregistration pipeline to coregister_3d(), see the API of Coreg.
|
Coregister DEM to a reference DEM in three dimensions. |
Uncertainty analysis#
|
Estimate the uncertainty of DEM. |
EPC#
Important
An EPC inherits all point cloud methods and attributes from the PointCloud object of GeoUtils.
Below, we only repeat some core attributes and methods of GeoUtils, see
the PointCloud API in GeoUtils for the full list.
Opening or saving#
|
The georeferenced elevation point cloud. |
|
Write the |
Plotting or summarize info#
Create from arrays or tuples#
|
Create point cloud from three 1D array-like coordinates for X/Y/Z. |
|
Create point cloud from an iterable of 3-tuples (X coordinate, Y coordinate, Z value). |
|
Create point cloud from a 3 x N or N x 3 array of X coordinates, Y coordinates and Z values. |
Unique attributes#
Inherited from PointCloud#
Geodataframe of the point cloud. |
|
Name of data column of the point cloud. |
Specific to EPC#
Vertical coordinate reference system of the elevation point cloud. |
Other attributes#
Inherited from PointCloud#
See the full list in the PointCloud API of GeoUtils.
Number of points in the point cloud. |
|
Total bounding box of the vector. |
|
Coordinate reference system of the vector. |
Georeferencing#
Inherited from PointCloud#
|
|
|
|
|
|
|
Vertical referencing for DEM#
|
Set the vertical coordinate reference system of the elevation point cloud. |
|
Interface with rasters and vectors#
Note
See the full list of vector methods in GeoUtils’ documentation.
|
Grid point cloud into a raster. |
|
Rasterize vector to a raster or mask, with input geometries burned in. |
Statistics#
|
Coregistration and bias corrections#
Tip
To build and pass your coregistration pipeline to coregister_3d(), see the API of Coreg.
|
Coregister elevation point cloud to a reference elevation data in three dimensions. |
Coreg#
Overview of co-registration class structure:
Coregistration, pipeline and blockwise#
|
Generic co-registration processing class. |
|
A sequential set of co-registration processing steps. |
|
A processing class of choice is run on a subdivision of the raster. |
Fitting and applying transforms#
|
|
|
Estimate the coregistration transform on the given DEMs. |
|
Extracting metadata#
|
|
Metadata dictionary of the coregistration. |
Affine coregistration#
Parent object (to define custom methods)#
|
Generic affine coregistration class. |
Coregistration methods#
|
Vertical translation alignment. |
|
Nuth and Kääb (2011) coregistration, https://doi.org/10.5194/tc-5-271-2011. |
|
Elevation difference minimization coregistration. |
|
Least Z-difference coregistration. |
|
Iterative closest point registration. |
|
Coherent Point Drift coregistration, based on Myronenko and Song (2010), https://doi.org/10.1109/TPAMI.2010.46. |
Manipulating affine transforms#
|
|
|
Invert a transformation matrix. |
Build rigid affine matrix based on 3 translations (unit of coordinates) and 3 rotations (degrees or radians). |
|
Extract 3 translations (unit of coordinates) and 3 rotations (degrees or radians) from rigid affine matrix. |
Bias-correction#
Parent object (to define custom methods)#
|
Bias-correction (non-rigid alignment) simultaneously with any number and type of variables. |
Bias-correction methods#
|
Correct for a 2D polynomial along X/Y coordinates, for example from residual camera model deformations (dome-like errors) or tilts (rotational errors). |
|
Bias correction for directional biases, for example along- or across-track of satellite angle. |
|
Correct a bias according to terrain, such as elevation or curvature. |
Uncertainty analysis#
Important
Several uncertainty functionalities of xDEM are being implemented directly in SciKit-GStat for spatial statistics
(e.g., fitting a sum of variogram models, pairwise subsampling for grid data). This will allow to simplify several
function inputs and outputs, by relying on a single Variogram() object.
This will trigger API changes in future package versions.
Core routines for heteroscedasticity, spatial correlations, error propagation#
Infer spatial correlation of errors from differenced values on stable terrain and a list of variogram model to fit as a sum. |
|
Spatial propagation of elevation errors to an area using the estimated heteroscedasticity and spatial correlations. |
Sub-routines for heteroscedasticity#
|
N-dimensional binning of values according to one or several explanatory variables with computed statistics in each bin. |
|
Estimate an interpolant function for an N-dimensional binning. |
|
Standardize the proxy differenced values using the modelled heteroscedasticity, re-scaled to the spread statistic, and generate the final standardization function. |
Sub-routines for spatial correlations#
Sample empirical variograms with binning adaptable to multiple ranges and spatial subsampling adapted for raster data. |
|
|
Fit a sum of variogram models to an empirical variogram, with weighted least-squares based on sampling errors. |
Construct the spatial correlation function from a dataframe of variogram parameters. |
Sub-routines for error propagation#
|
Compute the number of effective samples, i.e. the number of uncorrelated samples, in an area accounting for spatial correlations described by a sum of variogram models. |
Empirical validation#
|
Plotting for uncertainty analysis#
|
Plot empirical variogram, and optionally also plot one or several model fits. |
|
Plot a statistic and its count along a single binning variable. |
|
Plot one statistic and its count along two binning variables. |
Stand-alone functions (moved)#
|
Calculate the normalized median absolute deviation (NMAD) of an array. |
Development classes (removal or re-factoring)#
Caution
The xdem.dDEM and xdem.DEMCollection classes will be removed or re-factored in the near future.
dDEM#
|
A difference-DEM object. |
DEMCollection#
|
A temporal collection of DEMs. |