Getting started
===============

Overview
########

Pandora2d  is a coregistration tool that provides disparity maps for image pairs with a combination in both directions.
It uses `Pandora <https://github.com/CNES/Pandora>`__ which works with stereo pair of images only.


Install
#######
Pandora2D is available on Github and can be installed by:

.. code-block:: bash

    #install pandora2d latest release
    pip install pandora2d

If you want to use ``matching_cost_method=mc_cnn``, install the MCCNN plugin:

.. code-block:: bash

    pip install pandora-plugin-mccnn

See `Pandora plugin documentation <https://pandora.readthedocs.io/en/stable/userguide/plugins/plugin_mccnn.html>`_.

First step
##########

Pandora2d requires a `config.json` input file to declare the pipeline and the pair of images to process.
Download our data sample to start right away !

.. code-block:: bash

    # Images pairs with a combination of vertical and horizontal stereo
    wget -P data_samples/images https://raw.githubusercontent.com/CNES/Pandora2D/master/data_samples/images/maricopa.zip
    # Config file
    wget -P data_samples/json_conf_files https://raw.githubusercontent.com/CNES/Pandora2D/master/data_samples/json_conf_files/a_basic_pipeline.json
    #uncompress data
    unzip data_samples/images/maricopa.zip -d data_samples/images
    #run Pandora2D
    pandora2d data_samples/json_conf_files/a_basic_pipeline.json

.. note::
    With these commands, output files will be stored in data_samples/json_conf_files/a_basic_pipeline_output repository. 

Customize
#########

To create your own coregistration pipeline and choose among the variety of
algorithms we provide, please consult :ref:`userguide`.

You will learn:

    * which steps you can use and combine
    * how to quickly set up a Pandora2D pipeline

Credits
#######

Pandora2D uses `transitions <https://github.com/pytransitions/transitions>`_ to manage the pipelines one can create.
Images I/O are provided by `rasterio <https://github.com/mapbox/rasterio>`_ and we use `xarray <https://github.com/pydata/xarray>`_
to handle 4D Cost Volumes.

Our data test sample is based on the Peps Sentinel2 website (by CNES).

Related
#######

* Pandora2D calls Pandora N times for N row disparities.
    `Pandora <https://github.com/cnes/pandora>`_ - stereo matching framework