cars.devibrate
==============

.. py:module:: cars.devibrate

.. autoapi-nested-parse::

   cars-devibrate: devibrate a high resolution DSM using a low resolution DSM



Attributes
----------

.. autoapisummary::

   cars.devibrate.package_path
   cars.devibrate.GEOID_DEFAULT


Functions
---------

.. autoapisummary::

   cars.devibrate.acquisition_direction
   cars.devibrate.get_time_ground_direction
   cars.devibrate.project_coordinates_on_line
   cars.devibrate.lowres_initial_dem_splines_fit
   cars.devibrate.read_lowres_dsm
   cars.devibrate.compute_splines
   cars.devibrate.cars_devibrate
   cars.devibrate.cli


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

.. py:data:: package_path

.. py:data:: GEOID_DEFAULT

.. py:function:: acquisition_direction(sensor1, geomodel1, sensor2, geomodel2, geometry_plugin)

   Computes the mean acquisition of the input images pair

   :param sensor1: sensor image name of the first product
   :param geomodel1: geomodel name of the first product
   :param sensor2: sensor image name of the second product
   :param geomodel2: geomodel name of the second product
   :return: a tuple composed of :
       - the mean acquisition direction as a numpy array
       - the acquisition direction of the first product as a numpy array
       - the acquisition direction of the second product as a numpy array


.. py:function:: get_time_ground_direction(sensor, geomodel, geometry_plugin, x_loc: float = None, y_loc: float = None, y_offset: float = None) -> numpy.ndarray

   For a given image, compute the direction of increasing acquisition
   time on ground.
   Done by two localizations at "y" and "y+y_offset" values.

   :param sensor: sensor image name
   :param geomodel: geomodel name
   :param x_loc: x location in image for estimation (default=center)
   :param y_loc: y location in image for estimation (default=1/4)
   :param y_offset: y location in image for estimation (default=1/2)
   :param dem: DEM for direct localisation function
   :param geoid: path to geoid file
   :return: normalized direction vector as a numpy array


.. py:function:: project_coordinates_on_line(x_coord: Union[float, numpy.ndarray], y_coord: Union[float, numpy.ndarray], origin: Union[List[float], numpy.ndarray], vec: Union[List[float], numpy.ndarray]) -> Union[float, numpy.ndarray]

   Project coordinates (x, y) on a line starting from origin with a
   direction vector vec, and return the euclidean distances between
   projected points and origin.

   :param x_coord: scalar or vector of coordinates x
   :param y_coord: scalar or vector of coordinates y
   :param origin: coordinates of origin point for line
   :param vec: direction vector of line
   :return: vector of distances of projected points to origin


.. py:function:: lowres_initial_dem_splines_fit(lowres_dsm_from_matches: xarray.Dataset, lowres_initial_dem: xarray.Dataset, origin: numpy.ndarray, time_direction_vector: numpy.ndarray, ext: int = 3, order: int = 3, min_pts_per_time: int = 100, min_pts_along_time_direction: int = 100, butterworth_filter_order: int = 3, butterworth_critical_frequency: float = 0.05)

   This function takes 2 datasets containing DSM and models the
   difference between the two as an UnivariateSpline along the
   direction given by origin and time_direction_vector. Internally,
   it looks for the highest smoothing factor that satisfies the rmse threshold.

   :param lowres_dsm_from_matches: Dataset containing the low resolution DSM
       obtained from matches, as returned by the
       rasterization.simple_rasterization_dataset function.
   :param lowres_initial_dem: Dataset containing the low resolution DEM,
       on the same grid as lowres_dsm_from_matches
   :param origin: coordinates of origin point for line
   :type origin: list(float) or np.array(float) of size 2
   :param time_direction_vector: direction vector of line
   :type time_direction_vector: list(float) or np.array(float) of size 2
   :param ext: behavior outside of interpolation domain
   :param order: spline order
   :param min_pts_per_time: minimum number of points for
       each measurement
   :param min_pts_along_time_direction:  minimum number of points for
       time direction
   :param butterworth_filter_order: Order of the filter.
       See scipy.signal.butter
   :param butterworth_critical_frequency: The filter critical frequency
       or frequencies. See scipy.signal.butter


.. py:function:: read_lowres_dsm(srtm_path, startx, starty, endx, endy)

   Read an extract of the low resolution input DSM and return it as an Array


.. py:function:: compute_splines(sensor1, geomodel1, sensor2, geomodel2, matches, srtm_path, geoid_path, out_dir, min_pts_per_time: int = 100, min_pts_along_time_direction: int = 100, butterworth_filter_order: int = 3, butterworth_critical_frequency: float = 0.05)

   Compute a spline dict containing estimated splines, origin
   and time_direction_vector


.. py:function:: cars_devibrate(used_conf, srtm_path, geoid_path, min_pts_per_time: int = 100, min_pts_along_time_direction: int = 100, butterworth_filter_order: int = 3, butterworth_critical_frequency: float = 0.05)

   Main fonction. Expects a dictionary from the CLI
   or directly the input parameters.


.. py:function:: cli()

   Main cars-devibrate entrypoint (Command Line Interface)