Introduction

Measure 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.

Management of measure formula is ensured by ipsdk::shape::analysis::FormulaManager.

Result type

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

ipsdk::ipReal64 for arithmetical cases (ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Arithmetic case)
Example :
$3 * 2 + 5$
ipsdk::ipBool for logical cases (ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Logic case)
Example :
$log(3.2) > 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

Formula operators

This section regroups information about used formula operators. Formula operators are described by ipsdk::shape::analysis::eMsrFormulaOperatorType enumerate.

These operators allow all classical equation combinations such as :

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

Note: Associated result type will depends on operators combination.

Formula functions

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

Note: Formula function name are not case sensitive

Formula arithmetic functions

Formula unary arithmetical functions

Formula unary arithmetical functions are described by ipsdk::shape::analysis::eMsrFormulaUnaryArithmeticFunctionType enumerate.

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

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

Note: These functions are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::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::shape::analysis::eMsrFormulaBinaryArithmeticFunctionType enumerate.

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

$atan2(2, 3)$

Note: These functions are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::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::shape::analysis::eMsrFormulaGenericArithmeticFunctionType 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)$

These functions can be used with one or more operands.

Note: These functions are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Arithmetic result type.
Function operand must be associated to a ipsdk::ipReal64 type.

Formula coupled arithmetical functions

Formula coupled arithmetical functions are described by ipsdk::shape::analysis::eMsrFormulaCoupledArithmeticFunctionType 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)$

These functions can be used with one or more operands.

Note: These functions are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::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::shape::analysis::eMsrFormulaTernaryLogicFunctionType 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)$

Function evaluation returns :

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

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::shape::analysis::eMsrFormulaResultType::eMFRT_Arithmetic or a ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Logic result type in function of (and so ) 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 symbols : or (logical symbols are not case sensitive)
predefined numerical symbols : $\pi$ , $e \left \{=\exp(1) \right \}$ ) (numerical symbols are not case sensitive)
predefined image constant values
variables which are simply other measure values

Formula color indexes

This section describes color indexes as they can be used with some predefined image constant values and with variables.

Color indexes syntax must respect following the rules (in the following $X$ is an image constant value or a variable) :

$X\left \{i\right\}$ with an unsigned integer :
$MeanMsr\left \{1\right\}$
which will retrieve mean measure for color plan with index 1.
$X\left \{channel\right\}$ with $channel \in \left \{red, green, blue \right \}$ (color channel symbols are not case sensitive) :
$PlanMinGL\left \{blue\right\}$
which will retrieve minimum grey level value of image for 'blue' color plan.

Warning: Used color indexes must respect image color geometry.

Formula image constant operands

Formula image constant operands are described by ipsdk::shape::analysis::eMsrFormulaReserved enumerate. These constants will be replaced in equation by value extracted from used image informations.

These constants can be introduced into equations as follows :

$ImageSizeX / 2$

Special constants $PlanMinGL$ and $PlanMaxGL$ , which allows to retrieve minimum and maximum grey level values for a given image plan can be associated (if image color geometry allows it) to a color plan index :

$\begin{matrix} PlanMinGL=PlanMinGL\left \{0\right\}=PlanMinGL\left \{red\right\}\\ PlanMinGL\left \{1\right\}=PlanMinGL\left \{green\right\}\\ PlanMinGL\left \{2\right\}=PlanMinGL\left \{blue\right\} \end{matrix}$

Note: These constants are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Arithmetic result type.

Formula variable operands

Formula variable operands are associated to other measures. These variable names (which are not case sensitive) can refer to :

a measure default name.
List of available measures (default names) can be retrieved interrogating ipsdk::shape::analysis::MeasureInfoFactory singleton to query registred measure defaults names collection.
Example :
$Area2dMsr / Perimeter2dMsr$
In this case, Area2dMsr and Perimeter2dMsr will be used with their respective default parametrization. These measures will be automatically added to used ipsdk::shape::analysis::MeasureInfoSet object list of processed measures if not already included.
an existing measure name retrieved from used ipsdk::shape::analysis::MeasureInfoSet object.
Example :
(in case where ipsdk::shape::analysis::MeasureInfoSet object already contains a measure named )
$AreaMinusHoles / Perimeter2dMsr$

As described in Formula color indexes, formula variable can be associated to a color plan index. It can also be associated to a second index which will represent the array index in case of measures associated to a collection results type (ipsdk::shape::analysis::eMsrResultType::eMRT_Coll).
Array indexes syntax must respect following rule : $X\left [j\right]$ with $j$ an unsigned integer and can be cumulated with color indexes : $X\left \{i\right\}\left [j\right]$ or $X\left \{blue\right\}\left [j\right]$ . Array indexes must be valid regards to measure result array size.

Warning: Formula variable measures can't be associated to custom results type (ipsdk::shape::analysis::eMsrResultType::eMRT_Custom)

Note: These variables are associated to a ipsdk::shape::analysis::eMsrFormulaResultType::eMFRT_Arithmetic result type.