# BandMathX¶

This application performs mathematical operations on several multiband images.

## Description¶

This application performs a mathematical operation on several multi-band images and outputs the result into an image (multi- or mono-band, as opposed to the BandMath OTB-application). The mathematical formula is done by the muParserX library.

The list of features and the syntax of muParserX is available at [1].

As opposed to muParser (and thus the BandMath OTB-application [2]), muParserX supports vector expressions which allows outputting multi-band images.

Hereafter is a brief reference of the muParserX syntax

## Fundamentals¶

The formula can be written using:

- numerical values ( 2.3, -5, 3.1e4, ...)
- variables containing pixel values (please, note the indexing of inputs from 1 to N). Examples for the first input image:
`im1`

a pixel from 1st input, made of n components (n bands)`im1b2`

the 2nd component of a pixel from 1st input (band index is 1-based)`im1b2N3x4`

a 3x4 pixels Neighbourhood of a pixel the 2nd component of a pixel from the 1st input`im1PhyX`

horizontal (X-axis) spacing of the 1st input.`im1PhyY`

vertical spacing of the 1st input input.`im1b2Mean`

mean of the 2nd component of the 1st input (global statistics)`im1b2Mini`

minimum of the 2nd component of the 1st input (global statistics)`im1b2Maxi`

maximum of the 2nd component of the 1st input (global statistics)`im1b2Sum`

sum of the 2nd component of the 1st input (global statistics)`im1b2Var`

variance of the 2nd component of the 1st input (global statistics)`idxX`

and`idxY`

are the indices of the current pixel (generic variables)

- 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 operators:
`or`

,`and`

,`xor`

- if-then-else operator:
`(condition ? value_true : value_false)`

- functions: abs(), exp(), log(), sin(), cos(), min(), max(), ...

Always keep in mind that this application only addresses mathematically well-defined formulas. For instance, it is not possible to add vectors of different dimensions (e.g. addition of a row vector with a column vector), or a scalar to a vector or matrix, or divide two vectors, etc.

Thus, it is important to remember that a pixel of n components is always represented as a row vector.

- Example:
`im1 + im2`

represents the addition of pixels from the 1st and 2nd inputs. This expression is consistent only if both inputs have the same number of bands.

Please note that it is also possible to use the following expressions to obtain the same result:

`im1b1 + im2b1`

`im1b2 + im2b2`

- ...

Nevertheless, the first expression is by far much pleaseant. We call this new functionality the ‘batch mode’ (performing the same operation in a band-to-band fashion).

## Operations involving neighborhoods of pixels¶

Another new feature is the possibility to perform operations that involve neighborhoods of pixels. Variables related to such neighborhoods are always defined following the `imIbJNKxP`

pattern, where:

`I`

is an number identifying the image input (remember, input #0 = im1, and so on)`J`

is an number identifying the band (remember, first band is indexed by 1)`KxP`

are two numbers that represent the size of the neighborhood (first one is related to the horizontal direction)

NB: All neighborhood are centered, thus `K`

and `P`

must be odd numbers.

Many operators come with this new functionality:

- dotpr
- mean
- var
- median
- vmin
- vmax
- etc.

For instance, if `im1`

represents the pixel of a 3 bands image:

```
im1 - mean( im1b1N5x5, im1b2N5x5, im1b3N5x5 )
```

could represent a high pass filter (note that by implying three neighborhoods, the operator mean returns a row vector of three components. It is a typical behaviour for many operators of this application).

In addition to the previous operators, other operators are available:

- existing operators/functions from muParserX, that were not originally defined for vectors and matrices (e.g. cos, sin). These new operators/functions keep the original names to which we added the prefix
`v`

for vector (`vcos`

,`vsin`

, etc.)`mult`

,`div`

and`pow`

operators, that perform element-wise multiplication, division or exponentiation of vector/matrices (e.g.`im1 div im2`

).`mlt`

,`dv`

and`pw`

operators, that perform multiplication, division or exponentiation of vector/matrices by a scalar (e.g.`im1 dv 2.0`

).`bands`

, which is a very useful operator. It allows selecting specific bands from an image, or to rearrange them in a new vector (e.g.``bands( im1, { 1, 2, 1, 1 } )`` produces a vector of 4 components made of band 1, band 2, band 1 and band 1 values from the first input.

Note that curly brackets must be used in order to select the desired bandindices.

## The application itself¶

The application can use an expression supplied with the `-exp`

parameter. It can also use an input context file, that defines variables and expressions. An example of context file is given below:

```
#F expo 1.1
#M kernel1 { 0.1 , 0.2 , 0.3; 0.4 , 0.5 , 0.6; 0.7 , 0.8 , 0.9; 1 , 1.1, 1.2; 1.3 , 1.4 , 1.5 }
#E $dotpr( kernel1, im1b1N3x5 ); im2b1^expo$
```

As we can see, #I/#F allows the definition of an integer/float constant, whereas #M allows the definition of a vector/matrix. In the latter case, elements of a row must be separated by commas, and rows must be separated by semicolons. It is also possible to define expressions within the same txt file, with #E <expr> (see limitations, below).

## Parameters¶

**Input image list** `-il image1 image2...`

*Mandatory*

Image list to perform computation on.

**Output Image** `-out image [dtype]`

*Mandatory*

Output image.

**Expressions** `-exp string`

*Mandatory*

Mathematical expression to apply.

**Import context** `-incontext filename [dtype]`

A txt file containing user’s constants and expressions.

**Export context** `-outcontext filename [dtype]`

A txt file where to save user’s constants and expressions.

**Available RAM (MB)** `-ram int`

*Default value: 256*

Available memory for processing (in MB).

## Examples¶

From the command-line:

```
otbcli_BandMathX -il verySmallFSATSW_r.tif verySmallFSATSW_nir.tif verySmallFSATSW.tif -out apTvUtBandMathOutput.tif -exp "cos( im1b1 ) + im2b1 * im3b1 - im3b2 + ndvi( im3b3, im3b4 )"
```

From Python:

```
import otbApplication
app = otbApplication.Registry.CreateApplication("BandMathX")
app.SetParameterStringList("il", ['verySmallFSATSW_r.tif', 'verySmallFSATSW_nir.tif', 'verySmallFSATSW.tif'])
app.SetParameterString("out", "apTvUtBandMathOutput.tif")
app.SetParameterString("exp", "cos( im1b1 ) + im2b1 * im3b1 - im3b2 + ndvi( im3b3, im3b4 )")
app.ExecuteAndWriteOutput()
```

## Limitations¶

The application is currently unable to produce one output image per expression, contrary to otbBandMathXImageFilter. Separating expressions by semicolons `;`

will concatenate their results into a unique multiband output image.