.. _qzsolutions-arvi:

ARVI Calculator
===============

Block type: ``PROCESSING``

This block takes photos from an optical satellite and calculates Atmospherically Resistant Vegetation Index (*ARVI*).
It produces georeferenced raster output, which can be inspected visually or used for further processing.
The output can be opened in GIS tools like `QGIS <https://www.qgis.org/>`_ or `ArcGIS <https://esri.com/software/arcgis>`_.

.. _qzsolutions-arvi.parameters:

Supported parameters
--------------------

* ``colormap`` - the colormap, which will be used in rendering. See section :ref:`qzsolutions-arvi.colormap` for valid values.
* ``y`` - the quotient derived from the components of atmospheric reflectance in the blue and red channel.
* ``satellite`` - the name of the block providing input data. See section :ref:`qzsolutions-arvi.supported_data_blocks` for valid values.

Example parameters using ``Sentinel-2 Level 2 (BOA) AOI clipped`` block as data source and then rendering ARVI with ``RdYlGn`` colormap and variable :math:`y` set to ``0.1``:

.. code-block:: javascript

  {
    "sentinelhub-s2-aoiclipped:1": {
      "time": "2018-05-07T16:47:48+00:00/2018-05-09T16:47:49+00:00",
      "limit": 1,
      "intersects": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              18.726196,
              53.473489
            ],
            [
              18.720531,
              53.479312
            ],
            [
              18.708215,
              53.476043
            ],
            [
              18.719931,
              53.468431
            ],
            [
              18.73332,
              53.466183
            ],
            [
              18.739586,
              53.471854
            ],
            [
              18.726196,
              53.473489
            ]
          ]
        ]
      },
      "zoom_level": 14
    },
    "qzsolutions.arvi:1": {
      "colormap": "RdYlGn",
      "y": 0.1,
      "satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
    }
  }

.. _qzsolutions-arvi.supported_data_blocks:

Supported data blocks
---------------------
Currently this block supports input from data blocks:

Landsat-8 Level 1 (TOA) AOI clipped
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see this block on up42 please `click here <https://marketplace.up42.com/block/95519b2d-09d7-4cd0-a321-4d6a46bef6c1>`_.

Sample block parameters when using *Landsat-8 Level 1 (TOA) AOI clipped* data block:

.. code-block:: javascript

  {
    "colormap": "RdYlGn",
    "y": 0.1,
    "satellite": "Landsat-8 Level 1 (TOA) AOI clipped"
  }

Formula used for ARVI calculation: :math:`(B05 - B04 - y * (B04 - B02)) / (B05 + B04 - y * (B04 - B02))`

Pléiades Download
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see this block on up42 please `click here <https://marketplace.up42.com/block/defb134b-ca00-4e16-afa0-639c6dc0c5fe>`_.

Sample block parameters when using *Pléiades Download* data block:

.. code-block:: javascript

  {
    "colormap": "RdYlGn",
    "y": 0.1,
    "satellite": "Pleiades Download"
  }

.. warning::
    Please notice that ``satellite`` parameter does not contain 'é' character but 'e'.

Formula used for ARVI calculation: :math:`(NIR - R - y * (R - B)) / (NIR + R - y * (R - B))`

Sentinel-2 L1C MSI Full Scenes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see this block on up42 please `click here <https://marketplace.up42.com/block/98c1acfa-c141-4095-b2e6-acf52d110178>`_.

Sample block parameters when using *Sentinel-2 L1C MSI Full Scenes* data block:

.. code-block:: javascript

  {
    "colormap": "RdYlGn",
    "y": 0.1,
    "satellite": "Sentinel-2 L1C MSI Full Scenes"
  }

Formula used for ARVI calculation: :math:`(B09 - B04 - y * (B04 - B02)) / (B09 + B04 - y * (B04 - B02))`

Sentinel-2 Level 2 (BOA) AOI clipped
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see this block on up42 please `click here <https://marketplace.up42.com/block/018dfb34-fc19-4334-8125-14fd7535f979>`_.

Sample block parameters when using *Sentinel-2 Level 2 (BOA) AOI clipped* data block:

.. code-block:: javascript

  {
    "colormap": "RdYlGn",
    "y": 0.1,
    "satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
  }

Formula used for ARVI calculation: :math:`(B09 - B04 - y * (B04 - B02)) / (B09 + B04 - y * (B04 - B02))`

SPOT 6/7 Download
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see this block on up42 please `click here <https://marketplace.up42.com/block/63a69b97-1765-474e-b465-0b319b8d3b2d>`_.

Sample block parameters when using *SPOT 6/7 Download* data block:

.. code-block:: javascript

  {
    "colormap": "RdYlGn",
    "y": 0.1,
    "satellite": "SPOT 6/7 Download"
  }

Formula used for ARVI calculation: :math:`(NIR - R - y * (R - B)) / (NIR + R - y * (R - B))`

Output format
-------------

The block produces a feature collection with ``up42.data_path`` property containing a name of the result file.

Contents of *data.json* file returned by a block configured in the previous example:

.. code-block:: javascript

  {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "bbox": [
          18.69873046875,
          53.46189043285912,
          18.74267578125,
          53.48804553605621
        ],
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                18.720703125,
                53.46189043285912
              ],
              [
                18.69873046875,
                53.46189043285912
              ],
              [
                18.69873046875,
                53.47496999954854
              ],
              [
                18.69873046875,
                53.48804553605621
              ],
              [
                18.720703125,
                53.48804553605621
              ],
              [
                18.74267578125,
                53.48804553605621
              ],
              [
                18.74267578125,
                53.47496999954854
              ],
              [
                18.74267578125,
                53.46189043285912
              ],
              [
                18.720703125,
                53.46189043285912
              ]
            ]
          ]
        },
        "properties": {
          "up42.data_path": "fa91ec13-5f7e-41f4-ad24-db8a267e9d50.tiff",
          "acquisitionDate": "2018-05-08T09:50:28"
        }
      }
    ]
  }


.. figure:: _static/fa91ec13-5f7e-41f4-ad24-db8a267e9d50.png
    :alt: Contents of file fa91ec13-5f7e-41f4-ad24-db8a267e9d50.tiff

    Contents of file *fa91ec13-5f7e-41f4-ad24-db8a267e9d50.tiff*

Legend is in section :ref:`qzsolutions-arvi.rgb-output`.

Capabilities
------------

Input
~~~~~

This block has such ``input_capabilities``:

.. code-block:: javascript

  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": {
          "or": [
            "SAFE",
            "GTiff",
            "DIMAP"
          ]
        },
        "sensor": {"or": ["Landsat8", "Sentinel2", "SPOT", "Pleiades"]},
        "bands": ["red", "blue", "nir"]
      }
    }
  }

.. warning::
    Please ensure that input block is listed under :ref:`qzsolutions-arvi.supported_data_blocks` section.

Output
~~~~~~

This block has such ``output_capabilities``:

.. code-block:: javascript

  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "dtype": {"or": ["uint8", "float"]},
        "resolution": ">"
      },
      "custom": {
        "bands": [
          "arvi"
        ]
      }
    }
  }

If ``colormap`` is set to ``id`` then output type is ``float``. Otherwise it's ``uint8``.

.. _qzsolutions-arvi.colormap:

Colormap
--------

ARVI is always in :math:`[-1, 1]` range. There are two possible output types: RGB output and raw output.
The output type is controlled with ``colormap`` parameter (see :ref:`qzsolutions-arvi.colormap`).

.. _qzsolutions-ARVI.rgb-output:

RGB Output
~~~~~~~~~~

We can visualize ARVI as RGB GeoTIFF file. Colormap assigns color to each possible index value.

A legend for commonly used color maps is in the figure below.

.. figure:: _static/colorbars.png
    :alt: Commonly used colormaps

    Commonly used colormaps


This block supports `any predefined Matplotlib colormaps <https://matplotlib.org/tutorials/colors/colormaps.html>`_.

Set ``colormap`` parameter to requested colormap name (see :ref:`qzsolutions-arvi.colormap`).

Raw Output
~~~~~~~~~~

It is possible to get raw output, i.e. single band GeoTIFF file with ``float32`` matrix containing ARVI values.
Set ``colormap`` parameter to ``id`` (see :ref:`qzsolutions-arvi.colormap`).

.. code-block:: javascript

  {
    "colormap": "id",
    "y": 0.1,
    "satellite": "SPOT 6/7 Download"
  }

Such files can be manually colorized in `QGIS with singleband pseudocolor <https://docs.qgis.org/3.4/en/docs/training_manual/rasters/changing_symbology.html#basic-fa-singleband-pseudocolor>`_.
It is possible to read ARVI value for particular pixel with `Identify Features tool <https://docs.qgis.org/testing/en/docs/user_manual/introduction/general_tools.html#identify>`_.

Other usage of such files is further processing in Python or as an input for other up42 processing blocks.