.. _overview:

Block Overview
===============

Block type: ``PROCESSING``

This block uses satellite imagery data and generates RGB georeferenced images using formulas provided as parameters.
The output can be opened in standard images viewer and GIS tools like `QGIS <https://www.qgis.org/>`_ or `ArcGIS <https://esri.com/software/arcgis>`_.

Input parameters
--------------------

* ``red`` - the formula used for calculating values of red channel, see :ref:`formulas <formulas>` for valid values
* ``green`` - the formula used for calculating values of green channel
* ``blue`` - the formula used for calculating values of blue channel
* ``satellite`` - the name of the block providing input data, see :ref:`supported blocks <supported-blocks>` for valid values

The formula should be a mathematical expression containing: band names, operators and functions. More information about formulas can be found in :ref:`formulas <formulas>` section.
To see list of available bands and sample usage please visit :ref:`supported blocks <supported-blocks>` section.

Example parameters using *Sentinel-2 Level 2 (BOA) AOI clipped* block as data source and then generating false color composite:

.. code-block:: javascript

  {
    "sentinelhub-s2-aoiclipped:1": {
      "bbox": [
        19.845642734130864,
        52.30976947421495,
        19.881949734130865,
        52.32649747421495
      ],
      "time": "2018-01-01T00:00:00+00:00/2019-11-20T23:59:59+00:00",
      "limit": 1,
      "zoom_level": 14,
      "time_series": null
    },
    "qzsolutions.mixer:1": {
      "red": "B08/256",
      "blue": "B04/256",
      "green": "B03/256",
      "satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
    }
  }

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

The block produces a feature collection with ``up42.data_path`` property containing a name of the result file.
The result file is RGB GeoTIFF with 8 bit resolution channels.

.. warning::
    Values are expected to be between ``0`` and ``255``. Results of the formula of specific pixel will be clipped to ``0`` for results below ``0``. Values above ``255`` will be clipped to ``255``.


For most of satellites it also returns property ``acquisitionDate`` containing date of image being taken.

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

.. code-block:: javascript

  {
    "type":"FeatureCollection",
    "features":[
      {
        "type":"Feature",
        "bbox":[
          19.84130859375,
          52.308478623663355,
          19.88525390625,
          52.335339071889386
        ],
        "geometry":{
          "type":"Polygon",
          "coordinates":[
            [
              [
                19.86328125,
                52.308478623663355
              ],
              [
                19.84130859375,
                52.308478623663355
              ],
              [
                19.84130859375,
                52.32191088594772
              ],
              [
                19.84130859375,
                52.335339071889386
              ],
              [
                19.86328125,
                52.335339071889386
              ],
              [
                19.88525390625,
                52.335339071889386
              ],
              [
                19.88525390625,
                52.32191088594772
              ],
              [
                19.88525390625,
                52.308478623663355
              ],
              [
                19.86328125,
                52.308478623663355
              ]
            ]
          ]
        },
        "properties":{
          "up42.data_path":"86973862-61e8-4233-82f4-2c60049dee2e.tiff",
          "acquisitionDate":"2019-11-19T09:56:09"
        }
      }
    ]
  }

.. figure:: _static/86973862-61e8-4233-82f4-2c60049dee2e.png
    :alt: Contents of file 86973862-61e8-4233-82f4-2c60049dee2e.tiff

    Contents of file *86973862-61e8-4233-82f4-2c60049dee2e.tiff*

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

Input
~~~~~
This block has such ``input_capabilities``:

.. code-block:: javascript

  "input_capabilities": {
    "raster": {
      "up42_standard": {
        "format": {
          "or": [
            "SAFE",
            "GTiff",
            "DIMAP"
          ]
        }
      }
    }
  }

.. warning::
    Please ensure that input block is listed under :ref:`supported blocks <supported-blocks>` link.

Output
~~~~~~

This block has such ``output_capabilities``:

.. code-block:: javascript

  "output_capabilities": {
    "raster": {
      "up42_standard": {
        "format": "GTiff",
        "dtype": "uint8",
        "resolution": ">"
      }
    }
  }