BandMath - Band Math
^^^^^^^^^^^^^^^^^^^^

Outputs a monoband image which is the result of a mathematical operation on several multi-band images.

Detailed description
--------------------

This application performs a mathematical operation on several multi-band images and outputs the result into a monoband image. The given expression is computed at each pixel position. Evaluation of the mathematical formula is done by the muParser libraries.

The formula can be written using:

  * numerical values ( 2.3, -5, 3.1e4, ...)
  * variables containing pixel values (e.g. : 'im2b3' is the pixel value in 2nd image, 3rd band)
  * binary operators:

    * '+' addition, '-' subtraction, '*' multiplication, '/' division
    * '^' raise x to the power of y
    * '<' less than, '>' greater than, '<=' less or equal, '>=' greater or equal
    * '==' equal, '!=' not equal
    * '||' logical or, '&&' logical and
  * if-then-else operator: '(condition ? value_true : value_false)'
  * functions : exp(), log(), sin(), cos(), min(), max(), ...

The full list of features and operators is available on the muParser website [1].

Parameters
----------

This section describes in details the parameters available for this application. Table [#]_ presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is *BandMath* .

.. [#] Table: Parameters table for Band Math.

+-------------+----------------------------------+--------------------------+
|Parameter Key|Parameter Name                    |Parameter Type            |
+=============+==================================+==========================+
|il           |Input image-list                  |Input image list          |
+-------------+----------------------------------+--------------------------+
|out          |Output Image                      |Output image              |
+-------------+----------------------------------+--------------------------+
|ram          |Available RAM (Mb)                |Int                       |
+-------------+----------------------------------+--------------------------+
|exp          |Expression                        |String                    |
+-------------+----------------------------------+--------------------------+
|inxml        |Load otb application from xml file|XML input parameters file |
+-------------+----------------------------------+--------------------------+
|outxml       |Save otb application to xml file  |XML output parameters file|
+-------------+----------------------------------+--------------------------+

- **Input image-list**: Image-list of operands to the mathematical expression.
- **Output Image**: Output image which is the result of the mathematical expressions on input image-list operands.
- **Available RAM (Mb)**: Available memory for processing (in MB).
- **Expression**: The muParser mathematical expression to apply on input images.
- **Load otb application from xml file**: Load otb application from xml file.
- **Save otb application to xml file**: Save otb application to xml file.


Example
-------

To run this example in command-line, use the following: 
::

	otbcli_BandMath -il verySmallFSATSW_r.tif verySmallFSATSW_nir.tif verySmallFSATSW.tif -out apTvUtBandMathOutput.tif -exp 'cos( im1b1 ) > cos( im2b1 ) ? im3b1 : im3b2'

To run this example from Python, use the following code snippet: 

::

	#!/usr/bin/python

	# Import the otb applications package
	import otbApplication

	# The following line creates an instance of the BandMath application 
	BandMath = otbApplication.Registry.CreateApplication("BandMath")

	# The following lines set all the application parameters:
	BandMath.SetParameterStringList("il", ['verySmallFSATSW_r.tif', 'verySmallFSATSW_nir.tif', 'verySmallFSATSW.tif'])

	BandMath.SetParameterString("out", "apTvUtBandMathOutput.tif")

	BandMath.SetParameterString("exp", "'cos( im1b1 ) > cos( im2b1 ) ? im3b1 : im3b2'")

	# The following line execute the application
	BandMath.ExecuteAndWriteOutput()

Limitations
~~~~~~~~~~~

None

Authors
~~~~~~~

This application has been written by OTB-Team.

See Also
~~~~~~~~

These additional resources can be useful for further information: 
  | [1] http://beltoforion.de/article.php?a=muparser