.. _inputs:

Inputs
======

Pandora2D needs a pair of images that `rasterio <https://github.com/mapbox/rasterio>`_ can open and information about
the no_data of the images and range disparities.

Configuration and parameters
****************************

Input section is composed of the following keys:

.. list-table:: Input section
    :header-rows: 1

    * - Name
      - Description
      - Type
      - Default value
      - Required
    * - *left*
      - Left image properties (see description below)
      - dict
      - None
      - Yes
    * - *right*
      - Right image properties (see description below)
      - dict
      - None
      - Yes
    * - *col_disparity*
      - The disparities for columns (see description below)
      - dict
      - None
      - If the estimation step is not present
    * - *row_disparity*
      - The disparities for rows (see description below)
      - dict
      - None
      - If the estimation step is not present


Image (left and right) and disparity (col_disparity and row_disparity) properties are composed of the following keys:

.. tabs::

    .. tab:: Image properties

        Parameters : 

        .. list-table::
            :header-rows: 1

            * - Name
              - Description
              - Type
              - Default value
              - Required
            * - *img*
              - Path to the image
              - string
              - None
              - Yes
            * - *nodata*
              - Nodata value of the image
              - int, "NaN" or "inf"
              - -9999
              - No
            * - *mask*
              - Path to the mask
              - string
              - None
              - No

    .. tab:: Disparity properties

        Parameters : 


        .. list-table::
            :header-rows: 1

            * - Name
              - Description
              - Type
              - Default value
              - Required
            * - *init*
              - Initial point or path to initial grid
              - int or string
              - None
              - Yes
            * - *range*
              - The search radius (see :ref:`initial_disparity`)
              - int >= 0
              - None
              - Yes

.. note::

    The initial disparity can be defined in two ways:

    **1. Constant value for all points**

    If the initial disparity is the same for every point in the image, the *init* dictionary key must be an integer.

    **2. Variable value for each point**

    If the initial disparity varies across the image, the *init* key must be a string pointing to one of the following:

    - A file path to a grid that contains an integer initial value for each point in the image.
    - Alternatively, a path to an output directory that holds the disparity grids generated by a previous Pandora2D run.

    When using an output directory instead of a grid file, the following conditions must be met:

    - Both *init* values for the disparities must reference the same directory. Mixing grids from different runs is not allowed.
    - The step value defined in the pipeline configuration must match the one declared in the `attributes.json` file.

.. note::
    When using a string initial disparity (i.e., a path to a grid or an output directory),
    it is possible to enter a no data value in the metadata of the initial disparity grid so that points with this value are ignored in Pandora2d calculations.
    
    If a disparity map calculated by Pandora2D is used as the initial variable disparity grid, the *invalid_disp* value used in the Pandora2D disparity step configuration 
    that calculated these disparity maps is automatically saved as no data in the metadata of the the row_map.tif and col_map.tif files.

.. warning::
  If an output directory path is specified as input disparities and 
  it contains disparity maps smaller than the image, these maps will serve as the ROI (see :ref:`roi`). 

.. warning::
    If you provide a path to a disparity grid or an output directory as the initial disparity, 
    and one of the initial disparity grids contains sub-pixel values, then these sub-pixel values are rounded to the nearest integer.

    Values with a decimal of .5 are rounded to the nearest even integer (as is done in NumPy's `round` function)

.. warning::
    With sad/ssd matching_cost_method in the pipeline (see :ref:`Sequencing`), `nodata` only accepts `int` type.
    
    In addition, when the `nodata` value entered is `NaN` or `inf`, it is replaced by -9999  in the image datasets to avoid disrupting processing.

.. note::
    Only one-band masks are accepted by pandora2d. Mask must comply with the following convention:
     - Value equal to 0 for valid pixel
     - Value not equal to 0 for invalid pixel

Examples
********

**Input with constant initial disparity** 

.. code:: json
    :name: Input example

    {
        "input":
        {
            "left": {
                "img": "./data/left.tif",
                "nodata": -9999,
                "mask": "./data/mask_left.tif"
            },
            "right": {
                "img": "/data/right.tif",
                "nodata": -9999
            },
            "col_disparity": {"init": 0, "range": 3},
            "row_disparity": {"init": 0, "range": 3}
        }
        ,
        "pipeline":
        {
            // pipeline content
        },
        "output":
        {
            // output content
        }
    }

**Input with variable initial disparity** 

.. code:: json
    :name: Input example with disparity grid

    {
        "input":
        {
            "left": {
                "img": "./data/left.tif",
                "nodata": -9999,
                "mask": "./data/mask_left.tif"
            },
            "right": {
                "img": "/data/right.tif",
                "nodata": -9999
            },
            "col_disparity": {"init": "./data/col_disparity_grid.tif", "range": 3},
            "row_disparity": {"init": "./data/row_disparity_grid.tif", "range": 3}
        }
        ,
        "pipeline" :
        {
            // pipeline content
        },
        "output":
        {
            // output content
        }
    }