xdem.coreg.apply_matrix

Contents

xdem.coreg.apply_matrix#

xdem.coreg.apply_matrix(elev, matrix, invert=False, centroid=None, resample=True, resampling='linear', transform=None, z_name='z', **kwargs)[source]#

Apply a 3D affine transformation matrix to a 3D elevation point cloud or 2.5D DEM.

For an elevation point cloud, the transformation is exact.

For a DEM, it requires re-gridding because the affine-transformed point cloud of the DEM does not fall onto a regular grid anymore (except if the affine transformation only has translations). For this, this function uses the three following methods:

  1. For transformations with only translations, the transform is updated and vertical shift added to the array,

2. For transformations with a small rotation (20 degrees or less for all axes), this function maps which 2D point coordinates will fall back exactly onto the original DEM grid coordinates after affine transformation by searching iteratively using the invert affine transformation and 2D point regular-grid interpolation on the original DEM (see geoutils.Raster.interp_points, or scipy.interpolate.interpn),

3. For transformations with large rotations (20 degrees or more), scipy.interpolate.griddata is used to re-grid the irregular affine-transformed 3D point cloud using Delauney triangulation interpolation (slower).

Parameters:
  • elev (Raster | ndarray[Any, dtype[floating[Any]]] | GeoDataFrame) – Elevation point cloud or DEM to transform, either a 2D array (requires transform) or geodataframe (requires z_name).

  • matrix (ndarray[Any, dtype[floating[Any]]]) – Affine (4x4) transformation matrix to apply to the DEM.

  • invert (bool) – Whether to invert the transformation matrix.

  • centroid (tuple[float, float, float] | None) – The X/Y/Z transformation centroid. Irrelevant for pure translations. Defaults to the midpoint (Z=0).

  • resample (bool) – (For translations) If set to True, will resample output on the translated grid to match the input transform. Otherwise, only the transform will be updated and no resampling is done.

  • resampling (Literal['nearest', 'linear', 'cubic', 'quintic']) – Point interpolation method, one of ‘nearest’, ‘linear’, ‘cubic’, or ‘quintic’. For more information, see scipy.ndimage.map_coordinates and scipy.interpolate.interpn. Default is linear.

  • transform (Affine) – Geotransform of the DEM, only for DEM passed as 2D array.

  • z_name (str) – Column name to use as elevation, only for point elevation data passed as geodataframe.

  • kwargs (Any) – Keywords passed to _apply_matrix_rst for testing.

Return type:

tuple[ndarray[Any, dtype[floating[Any]]], Affine] | Raster | GeoDataFrame

Returns:

Affine transformed elevation point cloud or DEM.