xdem.spatial_tools¶

Basic operations to be run on 2D arrays and DEMs

Contents

Functions

Functions ¶

get_array_and_mask ¶

xdem.spatial_tools.get_array_and_mask(array, check_shape=True, copy=True)[source]¶

Return array with masked values set to NaN and the associated mask. Works whether array is a ndarray with NaNs or a np.ma.masked_array.

Parameters

array – Input array.
check_shape – Validate that the array is either a 1D array, a 2D array or a 3D array of shape (1, rows, cols).
copy – Return a copy of ‘array’. If False, a view will be attempted (and warn if not possible)

Returns array_data, invalid_mask

a tuple of ndarrays. First is array with invalid pixels converted to NaN, second is mask of invalid pixels (True if invalid).

get_mask ¶

xdem.spatial_tools.get_mask(array)[source]¶

Return the mask of invalid values, whether array is a ndarray with NaNs or a np.ma.masked_array.

Parameters: array (Union[ndarray, MaskedArray]) – Input array.
Returns invalid_mask: boolean array, True where array is masked or Nan.
Return type: ndarray

get_valid_extent ¶

xdem.spatial_tools.get_valid_extent(array)[source]¶

Return (rowmin, rowmax, colmin, colmax), the first/last row/column of array with valid pixels

Return type: tuple

hillshade ¶

xdem.spatial_tools.hillshade(dem, resolution, azimuth=315.0, altitude=45.0, z_factor=1.0)[source]¶

Generate a hillshade from the given DEM.

Parameters

dem – The input DEM to calculate the hillshade from.
resolution – One or two values specifying the resolution of the DEM.
azimuth – The azimuth in degrees (0-360°) going clockwise, starting from north.
altitude – The altitude in degrees (0-90°). 90° is straight from above.
z_factor – Vertical exaggeration factor.

Raises

AssertionError – If the given DEM is not a 2D array.
ValueError – If invalid argument types or ranges were given.

Returns

A hillshade with the dtype “float32” with value ranges of 0-255.

Examples using `xdem.spatial_tools.hillshade`¶

Iterative Closest Point (ICP) coregistration.¶

merge_bounding_boxes ¶

xdem.spatial_tools.merge_bounding_boxes(bounds, resolution)[source]¶

merge_rasters ¶

xdem.spatial_tools.merge_rasters(rasters, reference=0, merge_algorithm=<function nanmean>, resampling_method='bilinear', use_ref_bounds=False)[source]¶

Merge a list of rasters into one larger raster.

Reprojects the rasters to the reference raster CRS and resolution. Note that currently all rasters will be loaded once in memory. However, if rasters data is not loaded prior to merge_rasters it will be loaded for reprojection and deleted, therefore avoiding duplication and optimizing memory usage.

Parameters

rasters – A list of geoutils Raster objects to be merged.
reference – The reference index, in case the reference is to be merged, or a separate Raster object in case the reference should not be merged. Defaults to the first raster in the list.
merge_algorithm – The algorithm, or list of algorithms, to merge the rasters with. Defaults to the mean.If several algorithms are provided, each result is returned as a separate band.
resampling_method – The resampling method for the raster reprojections.
use_ref_bounds – If True, will use reference bounds, otherwise will use maximum bounds of all rasters.

Returns

The merged raster with the same parameters (excl. bounds) as the reference.

nmad ¶

xdem.spatial_tools.nmad(data, nfact=1.4826)[source]¶

Calculate the normalized median absolute deviation (NMAD) of an array.

Parameters

data (ndarray) – input data
nfact (float) – normalization factor for the data; default is 1.4826

Returns nmad

(normalized) median absolute deviation of data.

Return type

float

Examples using `xdem.spatial_tools.nmad`¶

Nuth & Kääb (2011) coregistration¶

Blockwise coregistration¶

Normalized regional hypsometric interpolation¶

resampling_method_from_str ¶

xdem.spatial_tools.resampling_method_from_str(method_str)[source]¶

Get a rasterio resampling method from a string representation, e.g. “cubic_spline”.

Return type: Resampling

stack_rasters ¶

xdem.spatial_tools.stack_rasters(rasters, reference=0, resampling_method='bilinear', use_ref_bounds=False, diff=False, progress=True)[source]¶

Stack a list of rasters into a common grid as a 3D np array with nodata set to Nan.

If use_ref_bounds is True, output will have the shape (N, height, width) where N is len(rasters) and height and width is equal to reference’s shape. If use_ref_bounds is False, output will have the shape (N, height2, width2) where N is len(rasters) and height2 and width2 are set based on reference’s resolution and the maximum extent of all rasters.

Use diff=True to return directly the difference to the reference raster.

Note that currently all rasters will be loaded once in memory. However, if rasters data is not loaded prior to merge_rasters it will be loaded for reprojection and deleted, therefore avoiding duplication and optimizing memory usage.

Parameters

rasters – A list of geoutils Raster objects to be stacked.
reference – The reference index, in case the reference is to be stacked, or a separate Raster object in case the reference should not be stacked. Defaults to the first raster in the list.
resampling_method – The resampling method for the raster reprojections.
use_ref_bounds – If True, will use reference bounds, otherwise will use maximum bounds of all rasters.
diff – If True, will return the difference to the reference, rather than the DEMs.
progress – If True, will display a progress bar. Default is True.

Returns

The stacked raster with the same parameters (optionally bounds) as the reference.

subdivide_array ¶

xdem.spatial_tools.subdivide_array(shape, count)[source]¶

Create indices for subdivison of an array in a number of blocks.

If ‘count’ is divisible by the product of ‘shape’, the amount of cells in each block will be equal. If ‘count’ is not divisible, the amount of cells in each block will be very close to equal.

Parameters

shape – The shape of a array to be subdivided.
count – The amount of subdivisions to make.

Examples

>>> subdivide_array((4, 4), 4)
array([[0, 0, 1, 1],
       [0, 0, 1, 1],
       [2, 2, 3, 3],
       [2, 2, 3, 3]])

>>> subdivide_array((6, 4), 4)
array([[0, 0, 1, 1],
       [0, 0, 1, 1],
       [0, 0, 1, 1],
       [2, 2, 3, 3],
       [2, 2, 3, 3],
       [2, 2, 3, 3]])

>>> subdivide_array((5, 4), 3)
array([[0, 0, 0, 0],
       [0, 0, 0, 0],
       [1, 1, 2, 2],
       [1, 1, 2, 2],
       [1, 1, 2, 2]])

Raises

ValueError – If the ‘shape’ size (np.prod(shape)) is smallern than ‘count’ If the shape is not a 2D shape.

Returns

An array of shape ‘shape’ with ‘count’ unique indices.

subsample_raster ¶

xdem.spatial_tools.subsample_raster(array, subsample, return_indices=False)[source]¶

Randomly subsample a 1D or 2D array by a subsampling factor, taking only non NaN/masked values.

Parameters: subsample (Union[float, int]) – If <= 1, will be considered a fraction of valid pixels to extract.

If > 1 will be considered the number of pixels to extract. :type return_indices: bool :param return_indices: If set to True, will return the extracted indices only.

Return type: ndarray
Returns: The subsampled array (1D) or the indices to extract (same shape as input array)

subtract_rasters ¶

xdem.spatial_tools.subtract_rasters(first_raster, second_raster, reference='first', resampling_method='cubic_spline')[source]¶

Subtract one raster with another.

difference = first_raster - reprojected_second_raster, OR difference = reprojected_first_raster - second_raster,

depending on which raster is acting “reference”.

Parameters

first_raster (Union[str, Raster]) – The first raster in the equation.
second_raster (Union[str, Raster]) – The second raster in the equation.
reference (str) – Which raster to provide the reference bounds, CRS and resolution (can be “first” or “second”).

Raises

ValueError: If any of the given arguments are invalid.

Return type

Raster

Returns

A raster of the difference between first_raster and second_raster.