Introduction

Image formula are string representation of classical equations composed of elementary items :

operators
functions
operands (constant or variable values)

Usage of such a formula is classically associated to two stages :

a preprocessing stage which ensure formula syntax validity and extraction of elementary items constituting formula.
some evaluation stages were variable values are set with respect to concrete situations.

Result type

For convenience, formula result types are restricted to two values types :

ipsdk::ipReal64 for arithmetical cases (ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic case)
Example :
$3 * 2 + 5$
or
$3 * I1 + I2$
ipsdk::ipBool for logical cases (ipsdk::image::tools::eImageFormulaResultType::eMFRT_Logic case)
Example :
$log(3.2) > 2.7$
or
$log(I1) > 2.7$

Note: Order of operations respect standard operator precedence rules.

See also: https://en.wikipedia.org/wiki/Order_of_operations

Note: Parenthesis can be freely used

Image type

Image formula framework can be used with 2d or 3d images (see ipsdk::image::tools::eImageFormulaImageType). Some formula features will be customized depending on image type (image coordinates, structuring elements type, ...).

Formula operators

This section regroups information about used formula operators. Formula operators are described by ipsdk::image::tools::eImageFormulaOperatorType enumerate.

These operators allow all classical equation combinations such as :

$(((3 * 2) + 5) / 7) ^ 2$

$(((3 * pi) + 5) / 7) ^ 2$

Note: Associated result type will depends on operators combination.

Formula functions

This section describes formula functions available with IPSDK image formula framework.

Formula arithmetic functions

Formula unary arithmetical functions

Formula unary arithmetical functions are described by ipsdk::image::tools::eImageFormulaUnaryArithmeticFunctionType enumerate.

These functions allow introduction of unary arithmetic functions into equations such as :

$sqrt(2*2 + 3*3)$

$sqrt(2*I1 + 3*I2)$

Note: These functions are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.
Function operand must be associated to a ipsdk::ipReal64 type.

Formula binary arithmetical functions

Formula binary arithmetical functions are described by ipsdk::image::tools::eImageFormulaBinaryArithmeticFunctionType enumerate.

These functions allow introduction of binary arithmetic functions into equations such as :

$atan2(2, 3)$

$atan2(I1, I2)$

Note: These functions are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.
Function operands must be associated to a ipsdk::ipReal64 type.

Formula generic arithmetical functions

Formula generic arithmetical functions are described by ipsdk::image::tools::eImageFormulaGenericArithmeticFunctionType enumerate.

These functions allow introduction of arithmetic functions using variable arguments list into equations such as :

$min(2, 1.7, 3, 4.2, 5.4)$

$min(100, I1, I2)$

These functions can be used with one or more operands.

Note: These functions are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.
Function operand must be associated to a ipsdk::ipReal64 type.

Formula couple arithmetical functions

Formula couple arithmetical functions are described by ipsdk::image::tools::eImageFormulaCoupledArithmeticFunctionType enumerate.

These functions allow introduction of arithmetic functions using coupled variable arguments list into equations such as :

$distance(x0, x1, y0, y1)$

$distance(x0, x1, y0, y1, z0, z1)$

Note: These functions are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.
Function operand must be associated to a ipsdk::ipReal64 type.

Formula ternary logical functions

Formula ternary logical functions are described by ipsdk::image::tools::eImageFormulaTernaryLogicFunctionType enumerate.

At this time a single function is available in this group $if(predicateValue, successValue, failureValue)$ :

$if(2>3, 5, 4)$

$if(2>3, true, false)$

$if(I1>100, I1, 100)$

Function evaluation returns :

if is evaluated to boolean value
if is evaluated to boolean value

Note

Associated operands types must respect following rules :

must be associated to a ipsdk::ipBool value.
and must be associated to same value type.
This function can then alternativelly be associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic or a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Logic result type in function of (and so ) value type.

Mapping functions

Mapping functions are described by ipsdk::image::tools::eImageFormulaMapFunctionType enumerate.

At this time a single function is available in this group $lut(predicateValue_1:targetValue_1, ..., predicateValue_n:targetValue_n; optionalDefaultValue)$ :

$lut(I1<100=100, I1>200=200, I1)$

where $predicateValue_i:targetValue_i$ is a logical predicate associated to a target value.

Function evaluation returns :

Target value associated to first valid predicate.
If none of provided predicates are valid :
- if this optional value has been set
- zero if has not been set and global result type is arithmetic
- false if has not been set and global result type is logic

Note

Associated operands types must respect following rules :

must be associated to a ipsdk::ipBool value.
all must be associated to same value type.
if is provided it must be associated to same value type as This function can then alternativelly be associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic or a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Logic result type in function of value type.

Formula operands

This section regroups information about used formula operands. Formula operands can be represented in following forms :

classical numerical values such as .
classical logical values : or (see ipsdk::image::tools::eImageFormulaStaticBoolean)
predefined constant values
variables which refers to image values

Note: Note that string used in equations are not case sensitive.

Formula constant operands

Formula static constant operands

Formula static constant operands are described by ipsdk::image::tools::eImageFormulaStaticConstant enumerate. These constants will be replaced in equation by their numeric value :

$pi$

will be replaced by its numerical value.

Formula dynamic constant operands

Formula dynamic constant operands are described by ipsdk::image::tools::eImageFormulaDynamicConstant enumerate. These constants will be replaced in equation by value extracted from used image informations.

These constants can be introduced into equations as follows :

$(x-cx) * (x-cx) + (y-cy) * (y-cy) <= 15$

Note: These constants are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.

Formula image constant operands

Formula image constant operands are described by ipsdk::image::tools::eImageFormulaImageConstant enumerate. Each constant depends on an image id, see Formula variable operands. These constants will be replaced in equation by value extracted from used image informations.

These constants can be introduced into equations as follows :

$If(I1>GLMean(I1)+1.5*GLStdDev(I1), I1, GLMean(I1)+1.5*GLStdDev(I1))$

Note: These constants are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.

Formula variable operands

Basic usage of formula variable operands

Formula variable operands are associated image identifier (see ipsdk::image::tools::eFormulaImageId). These variable names can refer to :

an input generic image (associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type) :
- $I1\Leftrightarrow InOptImg1$
- $I2\Leftrightarrow InOptImg2$
- $I3\Leftrightarrow InOptImg3$
  If several input generic images are provided, all these images must be associated to same image buffer type (see ipsdk::image::eImageBufferType).
an input binary image (associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Logic result type) :
- $B1\Leftrightarrow InOptBinImg1$
- $B2\Leftrightarrow InOptBinImg2$
- $B3\Leftrightarrow InOptBinImg3$
  These images must be associated to a binary image buffer type (see ipsdk::image::eImageBufferType).
an input label image (associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type) :
- $L1\Leftrightarrow InOptLabImg1$
- $L2\Leftrightarrow InOptLabImg2$
- $L3\Leftrightarrow InOptLabImg3$
  If several input label images are provided, all these images must be associated to same image buffer type (label 16 or label 32, see ipsdk::image::eImageBufferType).

Example :

$If(B1, I1, I2)$

In this case, we apply a mask operation which leads to $InOptImg1$ where $InOptBinImg1$ pixels are set and to $InOptImg2$ otherwise.

Note: These variables are associated to a ipsdk::image::tools::eImageFormulaResultType::eMFRT_Arithmetic result type.

Applying offset on formula variable operands

Previous image variable operands can be used with combination of an offset value with format $I1(ox, oy)$ in 2d case and $I1(ox, oy, oz)$ in 3d case, where $ox$ , $oy$ and $oz$ represent an offset along $x$ , $y$ and $z$ directions beside current image position.

In 2d case we can use a formula such as :

$mean(I1, I1(-1, 0), I1(0, 1), I1(0, -1), I1(0, 1))$

to compute a local "cross like" mean smoothing operation.

In 3d case this operation becomes :

$mean(I1, I1(-1, 0, 0), I1(0, 1, 0), I1(0, -1, 0), I1(0, 1, 0), I1(0, 0, -1), I1(0, 0, 1))$

to compute a local "cross like" mean smoothing operation.

Applying structuring elements on formula variable operands

As an extension of image offset combination capabilities, image formula allow usable of structuring elements. These features are described by ipsdk::image::tools::eImageFormulaStructuringElement enumerate.

A square structuring element such as :

$square(I1, 1)$

will simply be replaced by its decomposition (in 2d case) :

$I1(-1, -1), I1(0, -1), I1(1, -1), I1(-1, 0), I1(0, 0), I1(1, 0), I1(-1, 1), I1(0, 1), I1(1, 1)$

This allows for example simple image smoothing operations (median filter with a circular structuring element in this case):

$median(circle(I1, 2))$

or morphological operations (erosion with a square structuring element in this case) :

$min(square(I1, 3))$