demcompare.img_tools
====================

.. py:module:: demcompare.img_tools

.. autoapi-nested-parse::

   This module contains generic functions associated to raster images.
   It consists mainly on wrappers to rasterio functions.



Functions
---------

.. autoapisummary::

   demcompare.img_tools.convert_pix_to_coord
   demcompare.img_tools.crop_rasterio_source_with_roi
   demcompare.img_tools.compute_gdal_translate_bounds
   demcompare.img_tools.remove_nan_and_flatten
   demcompare.img_tools.compute_surface_normal
   demcompare.img_tools.neighbour_interpol
   demcompare.img_tools.calc_spatial_freq_2d
   demcompare.img_tools.calc_spatial_freq_1d


Module Contents
---------------

.. py:function:: convert_pix_to_coord(transform_array: Union[List, numpy.ndarray], row: Union[float, int, numpy.ndarray], col: Union[float, int, numpy.ndarray]) -> Tuple[numpy.ndarray, numpy.ndarray]

   Convert input (row, col) pixels to dataset geographic coordinates
   from affine rasterio transform in upper left convention.
   See: https://gdal.org/tutorials/geotransforms_tut.html

   :param transform_array: Array containing 6 Affine Geo Transform coefficients
   :type transform_array: List or np.ndarray
   :param row: row to convert
   :type row: float, int or np.ndarray
   :param col: column to convert
   :type col: float, int or np.ndarray
   :return: converted x,y in geographic coordinates from affine transform
   :rtype: Tuple[np.ndarray, np.ndarray]


.. py:function:: crop_rasterio_source_with_roi(src: rasterio.DatasetReader, roi: List[float]) -> Tuple[numpy.ndarray, rasterio.Affine]

   Transforms the input Region of Interest to polygon and
   crops the input rasterio source DEM and its transform.
   If the ROI is outside of the input DEM, an exception is raised.

   :param src: input source dataset in rasterio format
   :type src: rasterio.DatasetReader
   :param roi: region of interest to crop
   :type roi: List[float]
   :return: cropped dem and its affine transform
   :rtype: Tuple[np.ndarray, Affine]


.. py:function:: compute_gdal_translate_bounds(y_offset: Union[float, int, numpy.ndarray], x_offset: Union[float, int, numpy.ndarray], shape: Tuple[int, int], georef_transform: numpy.ndarray) -> Tuple[float, float, float, float]

   Obtain the gdal coordinate bounds to apply the translation offsets to
   the DEM to coregister/translate with gdal.

   The offsets can be applied with the command line:
   gdal_translate -a_ullr <ulx> <uly> <lrx> <lry>
   /path_to_original_dem.tif /path_to_coregistered_dem.tif

   :param y_offset: y pixel offset
   :type y_offset: Union[float, int, ndarray]
   :param x_offset: x pixel offset
   :type x_offset: Union[float, int, ndarray]
   :param shape: rasterio tuple containing x size and y size
   :type shape: Tuple[int, int]
   :param georef_transform: Array with 6 Affine Geo Transform coefficients
   :type georef_transform: np.ndarray
   :return: coordinate bounds to apply the offsets
   :rtype: Tuple[float,float,float,float]


.. py:function:: remove_nan_and_flatten(data: numpy.ndarray) -> numpy.ndarray

   Function for removing NaNs from a numpy array (data)
   If data has a dimension >1,
   the function returns a row vector (1D) without NaNs

   :param data: array of values
   :type data: np.ndarray
   :return: array of values without Nans
   :rtype: np.ndarray


.. py:function:: compute_surface_normal(data: numpy.ndarray, dx: numpy.float64, dy: numpy.float64) -> numpy.ndarray

   Return the surface normal vector at each pixel.
   First: compute the gradient in every direction at each pixel.
   Finally: compute the cross product of the 2 gradient vectors.

   :param data: 2D (row, col) np.ndarray containing the image
   :type data: np.ndarray
   :param dx: DEM's resolution in the X direction
   :type dx: np.float64
   :param dy: DEM's resolution in the Y direction
   :type dy: np.float64
   :return: vector (3D, row, col) normal to the surface for each pixel
   :rtype: np.ndarray


.. py:function:: neighbour_interpol(data2d: numpy.ndarray, no_values_location: numpy.ndarray) -> numpy.ndarray

   Nearest neighbor interpolation function.
   Applied to DEM containing no data values for calculating curvature.

   :param data2d: 2D (row, col) np.ndarray containing the image
   :type data2d: np.ndarray
   :param no_values_location: 2D (row, col) np.ndarray
                              containing the no data values
   :type no_values_location: np.ndarray
   :return: 2D interpolated np.ndarray
   :rtype: np.ndarray


.. py:function:: calc_spatial_freq_2d(s_y: int, s_x: int, edge: float = np.pi)

   Calculation of normalized spatial frequencies
   for a 2D image/matrix of size s_y * s_x.

   :param s_y: number of rows of the image
   :type s_y: int
   :param s_x: number of columns of the image
   :type s_x: int
   :return: normalized spatial frequencies
   :rtype: (np.ndarray, np.ndarray)


.. py:function:: calc_spatial_freq_1d(n: int, edge: float = np.pi) -> numpy.ndarray

   Calculation of normalized frequencies
   between [-edge, +edge] of a vector of n samples.
   n is even or odd.
   In both cases, the vector contains the zero frequency at the center.

   :param n: frequency vector size
   :type n: int
   :param edge: maximum frequency
   :type edge: float
   :return: frequencies between -edge and +edge
   :rtype: np.ndarray