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 differencing

DEM differencing

Configuring verbosity level

Configuring verbosity level

Elevation error map

Elevation error map

Terrain attributes

Terrain attributes

Spatial correlation of errors

Spatial correlation of errors

Nuth and Kääb coregistration

Nuth and Kääb coregistration

Iterative closest point coregistration

Iterative closest point coregistration

Spatial propagation of elevation errors

Spatial propagation of elevation errors

Bias-correction with deramping

Bias-correction with deramping

Working with a collection of DEMs

Working with a collection of DEMs

Blockwise coregistration

Blockwise coregistration

Normalized regional hypsometric interpolation

Normalized regional hypsometric interpolation

Slope and aspect methods

Slope and aspect methods

Estimation and modelling of spatial variograms

Estimation and modelling of spatial variograms

Estimation and modelling of heteroscedasticity

Estimation and modelling of heteroscedasticity

Standardization for stable terrain as error proxy

Standardization for stable terrain as error proxy

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

DEM(filename_or_dataset[, vcrs, load_data, ...])	The digital elevation model.
DEM.save(filename[, driver, dtype, nodata, ...])	Write the raster to file.

Plotting or summarize info

DEM.info([stats, verbose])	Print summary information about the raster.
DEM.plot([bands, cmap, vmin, vmax, alpha, ...])	Plot the raster, with axes in projection of image.

Create from an array

DEM.from_array(data, transform, crs[, ...])

Create a DEM from a numpy array and the georeferencing information.

Unique attributes

Inherited from Raster

DEM.data	Array of the raster.
DEM.crs	Coordinate reference system of the raster.
DEM.transform	Geotransform of the raster.
DEM.nodata	Nodata value of the raster.
DEM.area_or_point	Pixel interpretation of the raster.

Specific to DEM

DEM.vcrs

Vertical coordinate reference system of the DEM.

Other attributes

Inherited from Raster

See the full list in the Raster API of GeoUtils.

DEM.res	Resolution (X, Y) of the raster in georeferenced units.
DEM.bounds	Bounding coordinates of the raster.
DEM.width	Width of the raster in pixels.
DEM.height	Height of the raster in pixels.
DEM.shape	Shape (i.e., height, width) of the raster in pixels.

Georeferencing

Inherited from Raster

DEM.set_nodata(new_nodata[, update_array, ...])	Set a new nodata value for all bands.
DEM.set_area_or_point(new_area_or_point[, ...])	Set new pixel interpretation of the raster.
DEM.info([stats, verbose])	Print summary information about the raster.
DEM.reproject([ref, crs, res, grid_size, ...])	Reproject raster to a different geotransform (resolution, bounds) and/or coordinate reference system (CRS).
DEM.crop(crop_geom[, mode, inplace])	Crop the raster to a given extent.

Vertical referencing for DEM

DEM.set_vcrs(new_vcrs)	Set the vertical coordinate reference system of the DEM.
DEM.to_vcrs(vcrs[, force_source_vcrs, inplace])	Convert the DEM to another vertical coordinate reference system.

Raster-vector interface

Note

See the full list of vector methods in GeoUtils’ documentation.

DEM.polygonize([target_values, data_column_name])	Polygonize the raster into a vector.
DEM.proximity([vector, target_values, ...])	Compute proximity distances to the raster target pixels, or to a vector geometry on the raster grid.
DEM.to_pointcloud([data_column_name, ...])	Convert raster to point cloud.
DEM.interp_points(points[, method, ...])	Interpolate raster values at a set of points.

Terrain attributes

DEM.slope([method, degrees])	Generate a slope map for a DEM, returned in degrees by default.
DEM.aspect([method, degrees])	Calculate the aspect of each cell in a DEM, returned in degrees by default.
DEM.hillshade([method, azimuth, altitude, ...])	Generate a hillshade from the given DEM.
DEM.curvature()	Calculate the terrain curvature (second derivative of elevation) in m-1 multiplied by 100.
DEM.profile_curvature()	Calculate the terrain curvature parallel to the direction of the slope in m-1 multiplied by 100.
DEM.planform_curvature()	Calculate the terrain curvature perpendicular to the direction of the slope in m-1 multiplied by 100.
DEM.maximum_curvature()	Calculate the signed maximum profile or planform curvature parallel to the direction of the slope in m-1 multiplied by 100.
DEM.topographic_position_index([window_size])	Calculates the Topographic Position Index, the difference to the average of neighbouring pixels.
DEM.terrain_ruggedness_index([method, ...])	Calculates the Terrain Ruggedness Index, the cumulated differences to neighbouring pixels.
DEM.roughness([window_size])	Calculates the roughness, the maximum difference between neighbouring pixels, for any window size.
DEM.rugosity()	Calculates the rugosity, the ratio between real area and planimetric area.
DEM.fractal_roughness([window_size])	Calculates the fractal roughness, the local 3D fractal dimension.

Or to get multiple related terrain attributes at once (for performance):

DEM.get_terrain_attribute(attribute, **kwargs)

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.

DEM.coregister_3d(reference_elev[, ...])

Coregister DEM to a reference DEM in three dimensions.

Uncertainty analysis

DEM.estimate_uncertainty(other_elev[, ...])

Estimate uncertainty of DEM.

Coreg

Overview of co-registration class structure:

Coregistration, pipeline and blockwise

coreg.Coreg([meta])	Generic co-registration processing class.
coreg.CoregPipeline(pipeline)	A sequential set of co-registration processing steps.
coreg.BlockwiseCoreg(step, subdivision[, ...])	Block-wise co-registration processing class to run a step in segmented parts of the grid.

Fitting and applying transforms

coreg.Coreg.fit_and_apply(reference_elev, ...)	Estimate and apply the coregistration to a pair of elevation data.
coreg.Coreg.fit(reference_elev, ...[, ...])	Estimate the coregistration transform on the given DEMs.
coreg.Coreg.apply(elev[, bias_vars, ...])	Apply the estimated transform to a DEM.

Extracting metadata

coreg.Coreg.info([as_str])	Summarize information about this coregistration.
coreg.Coreg.meta	Metadata dictionary of the coregistration.

Quick coregistration

coreg.workflows.dem_coregistration(...[, ...])

A one-line function to coregister a selected DEM to a reference DEM.

Affine coregistration

Parent object (to define custom methods)

coreg.AffineCoreg([subsample, matrix, meta])

Generic affine coregistration class.

Coregistration methods

coreg.VerticalShift([vshift_reduc_func, ...])	Vertical translation alignment.
coreg.NuthKaab([max_iterations, ...])	Nuth and Kääb (2011) coregistration, https://doi.org/10.5194/tc-5-271-2011.
coreg.DhMinimize([fit_minimizer, ...])	Elevation difference minimization coregistration.
coreg.ICP([max_iterations, tolerance, ...])	Iterative closest point registration, based on Besl and McKay (1992), https://doi.org/10.1117/12.57955.

Manipulating affine transforms

coreg.AffineCoreg.from_matrix(matrix)	Instantiate a generic Coreg class from a transformation matrix.
coreg.AffineCoreg.to_matrix()	Convert the transform to a 4x4 transformation matrix.
coreg.AffineCoreg.from_translations([x_off, ...])	Instantiate a generic Coreg class from a X/Y/Z translation.
coreg.AffineCoreg.to_translations()	Extract X/Y/Z translations from the affine transformation matrix.
coreg.AffineCoreg.from_rotations([x_rot, ...])	Instantiate a generic Coreg class from a X/Y/Z rotation.
coreg.AffineCoreg.to_rotations()	Extract X/Y/Z euler rotations (extrinsic convention) from the affine transformation matrix.
coreg.apply_matrix(elev, matrix[, invert, ...])	Apply a 3D affine transformation matrix to a 3D elevation point cloud or 2.5D DEM.
coreg.invert_matrix(matrix)	Invert a transformation matrix.

Bias-correction

Parent object (to define custom methods)

coreg.BiasCorr([fit_or_bin, fit_func, ...])

Bias-correction (non-rigid alignment) simultaneously with any number and type of variables.

Bias-correction methods

coreg.Deramp([poly_order, fit_or_bin, ...])	Correct for a 2D polynomial along X/Y coordinates, for example from residual camera model deformations (dome-like errors) or tilts (rotational errors).
coreg.DirectionalBias([angle, fit_or_bin, ...])	Bias correction for directional biases, for example along- or across-track of satellite angle.
coreg.TerrainBias([terrain_attribute, ...])	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

spatialstats.infer_heteroscedasticity_from_stable(...)	Infer heteroscedasticity from differenced values on stable terrain and a list of explanatory variables.
spatialstats.infer_spatial_correlation_from_stable(...)	Infer spatial correlation of errors from differenced values on stable terrain and a list of variogram model to fit as a sum.
spatialstats.spatial_error_propagation(...)	Spatial propagation of elevation errors to an area using the estimated heteroscedasticity and spatial correlations.

Sub-routines for heteroscedasticity

spatialstats.nd_binning(values, list_var, ...)	N-dimensional binning of values according to one or several explanatory variables with computed statistics in each bin.
spatialstats.interp_nd_binning(df, ...[, ...])	Estimate an interpolant function for an N-dimensional binning.
spatialstats.two_step_standardization(...[, ...])	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

spatialstats.sample_empirical_variogram(values)	Sample empirical variograms with binning adaptable to multiple ranges and spatial subsampling adapted for raster data.
spatialstats.fit_sum_model_variogram(...[, ...])	Fit a sum of variogram models to an empirical variogram, with weighted least-squares based on sampling errors.
spatialstats.correlation_from_variogram(...)	Construct the spatial correlation function from a dataframe of variogram parameters.

Sub-routines for error propagation

spatialstats.number_effective_samples(area, ...)

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

spatialstats.patches_method(values, areas[, ...])

Monte Carlo patches method that samples multiple patches of terrain, square or circular, of a certain area and computes a statistic in each patch.

Plotting for uncertainty analysis

spatialstats.plot_variogram(df[, ...])	Plot empirical variogram, and optionally also plot one or several model fits.
spatialstats.plot_1d_binning(df, var_name, ...)	Plot a statistic and its count along a single binning variable.
spatialstats.plot_2d_binning(df, var_name_1, ...)	Plot one statistic and its count along two binning variables.

Stand-alone functions (moved)

spatialstats.nmad(data[, nfact])

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

dDEM(raster, start_time, end_time[, error])

A difference-DEM object.

DEMCollection

DEMCollection(dems[, timestamps, outlines, ...])

A temporal collection of DEMs.