.. _qzsolutions-nbr:
NBR Calculator
===============
Block type: ``PROCESSING``
This block takes photos from an optical satellite and calculates Normalized Burn Ratio (*NBR*).
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 `_ or `ArcGIS `_.
.. _qzsolutions-nbr.parameters:
Supported parameters
--------------------
* ``colormap`` - the colormap, which will be used in rendering. See section :ref:`qzsolutions-nbr.colormap` for valid values.
* ``satellite`` - the name of the block providing input data. See section :ref:`qzsolutions-nbr.supported_data_blocks` for valid values.
Example parameters using ``Sentinel-2 Level 2 (BOA) AOI clipped`` block as data source and then rendering NBR with ``binary`` colormap:
.. 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.nbr:1": {
"colormap": "binary",
"satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
}
}
.. _qzsolutions-nbr.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 `_.
Sample block parameters when using *Landsat-8 Level 1 (TOA) AOI clipped* data block:
.. code-block:: javascript
{
"colormap": "binary",
"satellite": "Landsat-8 Level 1 (TOA) AOI clipped"
}
Formula used for NBR calculation: :math:`(B05-B07) / (B05+B07)`
Sentinel-2 L1C MSI Full Scenes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To see this block on up42 please `click here `_.
Sample block parameters when using *Sentinel-2 L1C MSI Full Scenes* data block:
.. code-block:: javascript
{
"colormap": "binary",
"satellite": "Sentinel-2 L1C MSI Full Scenes"
}
Formula used for NBR calculation: :math:`(B08-B12) / (B08+B12)`
Sentinel-2 Level 2 (BOA) AOI clipped
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To see this block on up42 please `click here `_.
Sample block parameters when using *Sentinel-2 Level 2 (BOA) AOI clipped* data block:
.. code-block:: javascript
{
"colormap": "binary",
"satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
}
Formula used for NBR calculation :math:`(B08-B12) / (B08+B12)`
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": "f3ef52c5-2b50-4114-9551-e453758feae0.tiff",
"acquisitionDate": "2018-05-08T09:50:28"
}
}
]
}
.. figure:: _static/example.png
:alt: Contents of file f3ef52c5-2b50-4114-9551-e453758feae0.tiff
Contents of file *f3ef52c5-2b50-4114-9551-e453758feae0.tiff*
Legend is in section :ref:`qzsolutions-nbr.rgb-output`.
Capabilities
------------
Input
~~~~~
This block has such ``input_capabilities``:
.. code-block:: javascript
"input_capabilities": {
"raster": {
"up42_standard": {
"format": {
"or": [
"SAFE",
"GTiff"
]
},
"sensor": {"or": ["Landsat8", "Sentinel2"]},
"bands": ["swir", "nir"]
}
}
}
.. warning::
Please ensure that input block is listed under :ref:`qzsolutions-nbr.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": [
"nbr"
]
}
}
}
If ``colormap`` is set to ``id`` then output type is ``float``. Otherwise it's ``uint8``.
.. _qzsolutions-nbr.colormap:
Colormap
--------
NBR 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-nbr.colormap`).
.. _qzsolutions-nbr.rgb-output:
RGB Output
~~~~~~~~~~
We can visualize NBR 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 `_.
Set ``colormap`` parameter to requested colormap name (see :ref:`qzsolutions-nbr.colormap`).
Raw Output
~~~~~~~~~~
It is possible to get raw output, i.e. single band GeoTIFF file with ``float32`` matrix containing NBR values.
Set ``colormap`` parameter to ``id`` (see :ref:`qzsolutions-nbr.colormap`).
.. code-block:: javascript
{
"colormap": "id",
"satellite": "Sentinel-2 Level 2 (BOA) AOI clipped"
}
Such files can be manually colorized in `QGIS with singleband pseudocolor `_.
It is possible to read NBR value for particular pixel with `Identify Features tool `_.
Other usage of such files is further processing in Python or as an input for other up42 processing blocks.