.. _formulas:

Formulas
================

The formula should be a mathematical expression containing: band names, operators and functions.
Available bands for supported data blocks are listed in :ref:`supported blocks <supported-blocks>` section.

Basic arithmetics
------------------------------------
Available bands can be referenced by their name. You can add, subtract, multiply and divide. Example:

.. code-block:: javascript

    "((BAND1 + BAND2 - BAND3) / 2) * 5"

Functions
------------------------------------
The following functions are available in formulas:

Rounding
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``round(x)``
* ``ceil(x)``
* ``floor(x)``

Trigonometric
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``sin(x)``
* ``cos(x)``
* ``tan(x)``
* ``sinh(x)``
* ``cosh(x)``
* ``tanh(x)``
* ``arcsin(x)``
* ``arccos(x)``
* ``arctan(x)``

Logarithm and exponentiation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``sqrt(x)``
* ``log(x)``
* ``log2(x)``
* ``log10(x)``
* ``exp(x)``
* ``relu(x)`` - rectified linear unit
* ``sigmoid(x)``
* ``expit(x)`` - alias for ``sigmoid``

Summary statistics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``min(x)`` - the minimum value of the entire band in the current image
* ``max(x)``- the maximum value of the entire band in the current image
* ``std(x)`` - the standard deviation of values in the band in the current image
* ``var(x)`` - the variance of values in the band in the current image
* ``mean(x)`` - the mean value of the entire band in the current image
* ``median(x)`` - the median value of the entire band in the current image

Miscellaneous
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``abs(x)``
* ``threshold(x, t)`` - returns ``1`` for ``x >= t`` and ``0`` otherwise

Example:

.. code-block:: javascript

    "threshold(abs(BAND1 - BAND2), 12.5) * 255"

Convolution
------------------------------------
Use ``@`` operator or ``convolve`` function with an array of constant values to apply a convolutional filter to a band.

There are also several predefined filters:

* ``box_blur(x)`` - uses ``[[1, 1, 1], [1, 1, 1], [1, 1, 1]] / 9`` kernel
* ``gauss_blur(x)`` - uses ``[[1, 2, 1], [2, 4, 2], [1, 2, 1]] / 16`` kernel
* ``edges(x)`` - uses ``[[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]]`` kernel
* ``sobel_x(x)`` - uses ``[[1, 0, -1], [2, 0, -2], [1, 0, -1]]`` kernel
* ``sobel_y(x)`` - uses ``[[1, 2, 1], [0, 0, 0], [-1, -2, -1]]`` kernel

Examples:

.. code-block:: javascript

    "(BAND1 @ [[1, 2, 1], [2, 4, 2], [1, 2, 1]]) / 16"
    "(convolve(BAND1, [[1, 2, 1], [2, 4, 2], [1, 2, 1]]) / 16)"
    "gauss_blur(BAND1)"

Operator Precedence
------------------------------------

+----------+---------------+---------------+
| Priority | Operator      | Associativity |
+==========+===============+===============+
| 0        | ``-`` (unary) | right to left |
+----------+---------------+---------------+
| 1        | ``*`` ``/``   | left to right |
+----------+---------------+---------------+
| 2        | ``+`` ``-``   | left to right |
+----------+---------------+---------------+
| 3        | ``@``         | left to right |
+----------+---------------+---------------+