pandora2d.refinement.optical_flow
=================================

.. py:module:: pandora2d.refinement.optical_flow

.. autoapi-nested-parse::

   This module contains functions associated to the optical flow method used in the refinement step.



Classes
-------

.. autoapisummary::

   pandora2d.refinement.optical_flow.OpticalFlow


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

.. py:class:: OpticalFlow(cfg: dict = None, step: list = None, window_size: int = 5)

   Bases: :py:obj:`pandora2d.refinement.refinement.AbstractRefinement`


   OpticalFLow class allows to perform the subpixel cost refinement step


   .. py:attribute:: _invalid_disp
      :value: None



   .. py:attribute:: _ITERATIONS
      :value: 4



   .. py:attribute:: schema


   .. py:attribute:: _iterations


   .. py:attribute:: _refinement_method


   .. py:attribute:: _window_size


   .. py:attribute:: _step


   .. py:method:: check_conf(cfg: dict) -> dict
      :classmethod:


      Check the refinement configuration

      :param cfg: user_config for refinement
      :return: cfg: global configuration



   .. py:property:: margins


   .. py:method:: reshape_to_matching_cost_window(img: xarray.Dataset, cost_volumes: xarray.Dataset, coordinates: tuple[list, list], disp_row: numpy.typing.NDArray = None, disp_col: numpy.typing.NDArray = None) -> numpy.typing.NDArray

      Transform image from (nb_col, nb_row) to (window_size, window_size, nbcol*nbrow)

      :param img: image to reshape
      :param cost_volumes: cost_volumes 4D row, col, disp_col, disp_row
      :param coordinates: min and max index coordinate for row and col [(first_row,last_row),(first_col,last_col)]
      :param disp_row: array dim [] containing all the row shift
      :param disp_col: array dim [] containing all the columns shift
      :return: array containing reshaped image [window_size, window_size, nbcol*nbrow]



   .. py:method:: warped_img(right_reshape: numpy.typing.NDArray, delta_row: numpy.typing.NDArray, delta_col: numpy.typing.NDArray, index_to_compute: list) -> numpy.typing.NDArray

      Shifted matching_cost window with computed disparity

      :param right_reshape: image right reshaped with dims (window_size, window_size, nbcol*nb_row)
      :param delta_row: rows disparity map
      :param delta_col: columns disparity map
      :param index_to_compute: list containing all valid pixel for computing optical flow
      :return: new array containing shifted matching_cost windows



   .. py:method:: lucas_kanade_core_algorithm(left_data: numpy.typing.NDArray, right_data: numpy.typing.NDArray) -> tuple[float, float]

      Implement lucas & kanade algorithm core

      :param left_data: matching_cost window for one pixel from left image
      :param right_data: matching_cost window for one pixel from left image
      :return: sub-pixel disparity computed by Lucas & Kanade optical flow



   .. py:method:: optical_flow(left_img: numpy.typing.NDArray, right_img: numpy.typing.NDArray, list_idx_to_compute: list) -> tuple[numpy.typing.NDArray, numpy.typing.NDArray, list]

      Computing optical flow between left and right image

      :param left_img: reshaped left image array
      :param right_img: reshaped right image array
      :param list_idx_to_compute: list of valid pixel
      :return: computed sub-pixel disparity map



   .. py:method:: find_nearest_column(value: int, data: numpy.typing.NDArray, direction: Literal['+', '-']) -> numpy.typing.NDArray
      :staticmethod:


      Return the nearest column from initial column index coordinate in a given direction

      :param value: initial column index
      :param data: cost volume coordinates
      :param direction: direction sign (must be + or -)



   .. py:method:: refinement_method(cost_volumes: xarray.Dataset, disp_map: xarray.Dataset, img_left: xarray.Dataset, img_right: xarray.Dataset) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

      Return the subpixel disparity maps

      :param cost_volumes: cost_volumes 4D row, col, disp_col, disp_row
      :param disp_map: pixels disparity maps
      :param img_left: left image dataset
      :param img_right: right image dataset
      :return: the refined disparity maps and disparity correlation score



   .. py:method:: _invalid_out_of_grid_disparities(step: list, delta: numpy.typing.NDArray[numpy.floating], disparity: xarray.DataArray) -> None

      Replace delta values by invalid_disp value when it is outside the corresponding disparity range defined by
      the disparity grid.

      :param step: [row_step, col_step]
      :param delta: refined disparity map
      :param disparity: pixelic disparity grids with min and max `band_disp` coordinates.