IPSDK 4.1.0.2
IPSDK : Image Processing Software Development Kit
IPSDK Concepts documentation

Introduction

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

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

Result type

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

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 \]

or

\[ (((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) \]

or

\[ 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) \]

or

\[ 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) \]

or

\[ 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) \]

or

\[ 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) \]

or

\[ if(2>3, true, false) \]

or

\[ if(I1>100, I1, 100) \]

Function evaluation returns :

Note
Associated operands types must respect following rules :
  • $predicateValue$ must be associated to a ipsdk::ipBool value.
  • $successValue$ and $failureValue$ 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 $successValue$ (and so $failureValue$) 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 :

Note
Associated operands types must respect following rules :
  • $predicateValue_i$ must be associated to a ipsdk::ipBool value.
  • all $targetValue_i$ must be associated to same value type.
  • if $optionalDefaultValue$ is provided it must be associated to same value type as $targetValue_1$ 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 $targetValue_1$ value type.

Formula operands

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

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 :

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)) \]