pandora2d.refinement.dichotomy
==============================

.. py:module:: pandora2d.refinement.dichotomy

.. autoapi-nested-parse::

   Module for Dichotomy refinement method (python version).



Attributes
----------

.. autoapisummary::

   pandora2d.refinement.dichotomy.COST_SELECTION_METHOD_MAPPING


Classes
-------

.. autoapisummary::

   pandora2d.refinement.dichotomy.DichotomyPython
   pandora2d.refinement.dichotomy.CostSurfaces
   pandora2d.refinement.dichotomy.Point


Functions
---------

.. autoapisummary::

   pandora2d.refinement.dichotomy.search_new_best_point


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

.. py:data:: COST_SELECTION_METHOD_MAPPING

.. py:class:: DichotomyPython(cfg: dict = None, _: list = None, __: int = 5)

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


   Subpixel refinement method by dichotomy (python version).


   .. py:attribute:: NB_MAX_ITER
      :value: 9



   .. py:attribute:: schema


   .. py:attribute:: filter


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


      Check the refinement method configuration.

      Will change `number_of_iterations` value by `Dichotomy.NB_MAX_ITER` if above `Dichotomy.NB_MAX_ITER`.

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



   .. py:property:: margins

      Create margins for dichotomy object.

      It will be used for ROI and for dichotomy window extraction from cost volumes.



   .. 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: pixel disparity maps
      :param img_left: left image dataset
      :param img_right: right image dataset
      :return: the refined disparity maps



.. py:class:: CostSurfaces(cost_volumes: xarray.Dataset)

   Container to extract subsampling cost surfaces around a given disparity from cost volumes.

   Cost Surface of point with coordinates `row==0` and `col==1` can be accessed with   `cost_surface[0, 1]`.

   The container is iterable row first then columns.


   .. py:attribute:: cost_volumes


   .. py:method:: __getitem__(item)

      Get cost surface (cost_volume & criteria) of coordinates item where item is (row, col).



   .. py:method:: __iter__()

      Iter over cost surfaces, row first then columns.



.. py:class:: Point

   Bases: :py:obj:`NamedTuple`


   Coordinates of a subpixellic point of cost surface.


   .. py:attribute:: row
      :type:  int | float | numpy.float32


   .. py:attribute:: col
      :type:  int | float | numpy.float32


.. py:function:: search_new_best_point(cost_surface: xarray.DataArray, precision: float, initial_disparity: tuple[numpy.floating, numpy.floating] | tuple[int, int], initial_position: tuple[numpy.floating, numpy.floating] | tuple[int, int], initial_value: numpy.float32, filter_dicho: pandora2d.interpolation_filter.AbstractFilter, cost_selection_method: collections.abc.Callable) -> tuple[Point, numpy.floating, numpy.floating, numpy.floating]

   Find best position and cost after interpolation of cost surface for given precision.

   :param cost_surface: Disparities in rows and cols of a point
   :param precision: subpixellic disparity precision to use
   :param initial_disparity: initial disparities (disp_row, disp_col)
   :param initial_position: coordinates (row, col) to interpolate around
   :param initial_value: initial value
   :param filter_dicho: filter used to do interpolation in dichotomy loop
   :param cost_selection_method: function used to select best cost
   :return: coordinates of best interpolated cost, its value and its corresponding disparities.