Measure formula syntax and usage. More...

Classes
struct	ipsdk::shape::analysis::ImageConstantId
	Formula identifier for image constant optionally associated to a color index . More...

struct	ipsdk::shape::analysis::FormulaVariableId
	Formula variable identifier optionally associated to an array and a color index . More...

struct	ipsdk::shape::analysis::ImageConstant
	Image Constant associated to an identifier and a value . More...

struct	ipsdk::shape::analysis::FormulaVariable
	Formula variable associated to an identifier and a value . More...

struct	ipsdk::shape::analysis::FormulaGenericArithmeticFunctionInfo
	Formula generic arithmetic function informations . More...

struct	ipsdk::shape::analysis::FormulaCoupledArithmeticFunctionInfo
	Formula coupled arithmetic function informations . More...

Typedefs
typedef ProcessingResult< eFormulaEvaluationStatus >	ipsdk::shape::analysis::EvalStatus
	formula evaluation status

typedef boost::variant< ipBool, ipReal64 >	ipsdk::shape::analysis::FormulaResult
	formula result (floating point or logical result)

typedef boost::shared_ptr< ipReal64 >	ipsdk::shape::analysis::VariableValuePtr
	shared pointer to value associated to a variable

typedef std::map< ImageConstantId, VariableValuePtr >	ipsdk::shape::analysis::ConstantMap
	map associating an image constant id to its value

typedef std::map< FormulaVariableId, VariableValuePtr >	ipsdk::shape::analysis::VariableMap
	map associating a formula variable id to its value

typedef boost::shared_ptr< FormulaManager >	ipsdk::shape::analysis::FormulaManagerPtr
	shared pointer to formula manager

Enumerations
enum	ipsdk::shape::analysis::eMsrFormulaOperatorType { ipsdk::shape::analysis::eMFOT_UnaryPlus, ipsdk::shape::analysis::eMFOT_UnaryMinus, ipsdk::shape::analysis::eMFOT_Not, ipsdk::shape::analysis::eMFOT_Plus, ipsdk::shape::analysis::eMFOT_Minus, ipsdk::shape::analysis::eMFOT_Multiply, ipsdk::shape::analysis::eMFOT_Divide, ipsdk::shape::analysis::eMFOT_Power, ipsdk::shape::analysis::eMFOT_And, ipsdk::shape::analysis::eMFOT_Or, ipsdk::shape::analysis::eMFOT_Equal, ipsdk::shape::analysis::eMFOT_NotEqual, ipsdk::shape::analysis::eMFOT_Greater, ipsdk::shape::analysis::eMFOT_GreaterOrEqual, ipsdk::shape::analysis::eMFOT_Lower, ipsdk::shape::analysis::eMFOT_LowerOrEqual }
	Enumerate describing measure formula operation type. More...

enum	ipsdk::shape::analysis::eMsrFormulaUnaryArithmeticFunctionType { ipsdk::shape::analysis::eMFUAFT_Abs, ipsdk::shape::analysis::eMFUAFT_Sqrt, ipsdk::shape::analysis::eMFUAFT_Exp, ipsdk::shape::analysis::eMFUAFT_Log, ipsdk::shape::analysis::eMFUAFT_Cos, ipsdk::shape::analysis::eMFUAFT_Sin, ipsdk::shape::analysis::eMFUAFT_Tan, ipsdk::shape::analysis::eMFUAFT_ACos, ipsdk::shape::analysis::eMFUAFT_ASin, ipsdk::shape::analysis::eMFUAFT_ATan, ipsdk::shape::analysis::eMFUAFT_CosH, ipsdk::shape::analysis::eMFUAFT_SinH, ipsdk::shape::analysis::eMFUAFT_TanH }
	Enumerate describing measure formula unary arithmetical function type. More...

enum	ipsdk::shape::analysis::eMsrFormulaBinaryArithmeticFunctionType { ipsdk::shape::analysis::eMFBAFT_ATan2 }
	Enumerate describing measure formula binary arithmetical function type. More...

enum	ipsdk::shape::analysis::eMsrFormulaGenericArithmeticFunctionType { ipsdk::shape::analysis::eMFGAFT_Min, ipsdk::shape::analysis::eMFGAFT_Max, ipsdk::shape::analysis::eMFGAFT_Sum, ipsdk::shape::analysis::eMFGAFT_Mean, ipsdk::shape::analysis::eMFGAFT_Median, ipsdk::shape::analysis::eMFGAFT_StdDev, ipsdk::shape::analysis::eMFGAFT_Variance, ipsdk::shape::analysis::eMFGAFT_NormL1, ipsdk::shape::analysis::eMFGAFT_NormL2 }
	Enumerate describing measure formula generic arithmetical function type. More...

enum	ipsdk::shape::analysis::eMsrFormulaCoupledArithmeticFunctionType { ipsdk::shape::analysis::eMFCAFT_Distance }
	Enumerate describing measure coupled formula arithmetical function type. More...

enum	ipsdk::shape::analysis::eMsrFormulaTernaryLogicFunctionType { ipsdk::shape::analysis::eMFTLFT_If }
	Enumerate describing measure formula ternary logical function type. More...

enum	ipsdk::shape::analysis::eMsrFormulaReserved { ipsdk::shape::analysis::eMFR_ImageSizeX, ipsdk::shape::analysis::eMFR_ImageSizeY, ipsdk::shape::analysis::eMFR_ImageSizeZ, ipsdk::shape::analysis::eMFR_ImageCenterX, ipsdk::shape::analysis::eMFR_ImageCenterY, ipsdk::shape::analysis::eMFR_ImageCenterZ, ipsdk::shape::analysis::eMFR_PlanMinGL, ipsdk::shape::analysis::eMFR_PlanMaxGL }
	enumerate describing formula reserved variable More...

enum	ipsdk::shape::analysis::eMsrFormulaResultType { ipsdk::shape::analysis::eMFRT_Logic, ipsdk::shape::analysis::eMFRT_Arithmetic }
	Enumerate describing measure formula result type. More...

enum	ipsdk::shape::analysis::eFormulaEvaluationStatus { ipsdk::shape::analysis::eMES_Success, ipsdk::shape::analysis::eMES_Warning, ipsdk::shape::analysis::eMES_Failure }
	Enumerate describing measure formula evaluation status. More...

Functions
IPSDKBASESHAPEANALYSIS_API Real64Vector	ipsdk::shape::analysis::applyArithmeticFormula (const std::string &formulaStr, const MeasureSet &measureSet, const ipUInt64 cPlanIdx=0, const eMsrInputImageId &msrInputImageId=eMsrInputImageId::eMIII_Image1)
	function allowing to apply an arithmetic formula on an existing measure set More...

IPSDKBASESHAPEANALYSIS_API BoolResult	ipsdk::shape::analysis::applyArithmeticFormula (const std::string &formulaStr, const MeasureSet &measureSet, const ipUInt64 cPlanIdx, const eMsrInputImageId &msrInputImageId, Real64Vector &resultsColl)
	function allowing to apply an arithmetic formula on an existing measure set More...

IPSDKBASESHAPEANALYSIS_API BoolVector	ipsdk::shape::analysis::applyLogicFormula (const std::string &formulaStr, const MeasureSet &measureSet, const ipUInt64 cPlanIdx=0, const eMsrInputImageId &msrInputImageId=eMsrInputImageId::eMIII_Image1)
	function allowing to apply a logic formula on an existing measure set More...

IPSDKBASESHAPEANALYSIS_API BoolResult	ipsdk::shape::analysis::applyLogicFormula (const std::string &formulaStr, const MeasureSet &measureSet, const ipUInt64 cPlanIdx, const eMsrInputImageId &msrInputImageId, BoolVector &resultsColl)
	function allowing to apply a logic formula on an existing measure set More...

Detailed Description

Measure formula syntax and usage.

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)$

or

$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)$

or

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

Enumeration Type Documentation

◆ eMsrFormulaOperatorType

enum ipsdk::shape::analysis::eMsrFormulaOperatorType

Enumerate describing measure formula operation type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFOT_UnaryPlus	Addition unary operator [example : '+value'].
eMFOT_UnaryMinus	Subtraction unary operator [example : '-value'].
eMFOT_Not	Logical not unary operator [example : '!value'].
eMFOT_Plus	Addition binary operator [example : 'value1 + value2'].
eMFOT_Minus	Subtraction binary operator [example : 'value1 - value2'].
eMFOT_Multiply	Multiplication binary operator [example : 'value1 * value2'].
eMFOT_Divide	Division binary operator [example : 'value1 / value2'].
eMFOT_Power	Power binary operator [example : 'value1 ^ value2'].
eMFOT_And	Logical and binary operator [example : 'value1 && value2'].
eMFOT_Or	Logical or binary operator [example : 'value1 \|\| value2'].
eMFOT_Equal	Equal comparison operator [example : 'value1 == value2'].
eMFOT_NotEqual	Not equal comparison operator [example : 'value1 != value2'].
eMFOT_Greater	Greater comparison operator [example : 'value1 > value2'].
eMFOT_GreaterOrEqual	Greater or equal comparison operator [example : 'value1 >= value2'].
eMFOT_Lower	Lower comparison operator [example : 'value1 < value2'].
eMFOT_LowerOrEqual	Lower or equal comparison operator [example : 'value1 <= value2'].

◆ eMsrFormulaUnaryArithmeticFunctionType

enum ipsdk::shape::analysis::eMsrFormulaUnaryArithmeticFunctionType

Enumerate describing measure formula unary arithmetical function type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFUAFT_Abs	Absolute value [example : 'abs(value)'].
eMFUAFT_Sqrt	Square root value [example : 'sqrt(value)'].
eMFUAFT_Exp	Exponential value [example : 'exp(value)'].
eMFUAFT_Log	Neperian logarithm value [example : 'log(value)'].
eMFUAFT_Cos	Cosinus value of an angle (in radian) [example : 'cos(value)'].
eMFUAFT_Sin	Sinus value of an angle (in radian) [example : 'sin(value)'].
eMFUAFT_Tan	Tangent value of an angle (in radian) [example : 'tan(value)'].
eMFUAFT_ACos	Arc Cosinus value [example : 'acos(value)'].
eMFUAFT_ASin	Arc Sinus value [example : 'asin(value)'].
eMFUAFT_ATan	Arc Tangent value [example : 'atan(value)'].
eMFUAFT_CosH	Hyperbolic cosinus value [example : 'cosH(value)'].
eMFUAFT_SinH	Hyperbolic sinus value [example : 'sinH(value)'].
eMFUAFT_TanH	Hyperbolic tangent value [example : 'tanH(value)'].

◆ eMsrFormulaBinaryArithmeticFunctionType

enum ipsdk::shape::analysis::eMsrFormulaBinaryArithmeticFunctionType

Enumerate describing measure formula binary arithmetical function type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFBAFT_ATan2	Arc Tangent value [example : 'atan2(valueY, valueX)'].

◆ eMsrFormulaGenericArithmeticFunctionType

enum ipsdk::shape::analysis::eMsrFormulaGenericArithmeticFunctionType

Enumerate describing measure formula generic arithmetical function type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFGAFT_Min	Minimum value computation [example : 'min(value1, value2, value3, ...)'].
eMFGAFT_Max	Maximum value computation [example : 'max(value1, value2, value3, ...)'].
eMFGAFT_Sum	Sum value computation [example : 'sum(value1, value2, value3, ...)'].
eMFGAFT_Mean	Mean value computation [example : 'mean(value1, value2, value3, ...)'].
eMFGAFT_Median	Median value computation [example : 'median(value1, value2, value3, ...)'].
eMFGAFT_StdDev	Standard deviation value computation [example : 'stddev(value1, value2, value3, ...)'].
eMFGAFT_Variance	Variance value computation [example : 'variance(value1, value2, value3, ...)'].
eMFGAFT_NormL1	L1 norm (ie. absolute value norm) computation [example : 'normL1(value1, value2, value3, ...)'].
eMFGAFT_NormL2	L2 norm (ie. euclidian norm) computation [example : 'normL2(value1, value2, value3, ...)'].

◆ eMsrFormulaCoupledArithmeticFunctionType

enum ipsdk::shape::analysis::eMsrFormulaCoupledArithmeticFunctionType

Enumerate describing measure coupled formula arithmetical function type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFCAFT_Distance	Distance value computation [example : 'distance(x0, x1, y0, y1, ...)', with a list of arguments formed by cuples].

◆ eMsrFormulaTernaryLogicFunctionType

enum ipsdk::shape::analysis::eMsrFormulaTernaryLogicFunctionType

Enumerate describing measure formula ternary logical function type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFTLFT_If	If logical ternary function [example : 'if(predicateValue, successValue, failureValue)'].

◆ eMsrFormulaReserved

enum ipsdk::shape::analysis::eMsrFormulaReserved

enumerate describing formula reserved variable

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFR_ImageSizeX	Image size X [example : 'ImageSizeX'].
eMFR_ImageSizeY	Image size Y [example : 'ImageSizeY'].
eMFR_ImageSizeZ	Image size Z [example : 'ImageSizeZ'].
eMFR_ImageCenterX	Image center X [example : 'ImageCenterX'].
eMFR_ImageCenterY	Image center Y [example : 'ImageCenterY'].
eMFR_ImageCenterZ	Image center Z [example : 'ImageCenterZ'].
eMFR_PlanMinGL	Current image plan minimum grey level [example : 'PlanMinGL' or 'PlanMinGL{1}' or 'PlanMinGL{green}'].
eMFR_PlanMaxGL	Current image plan maximum grey level [example : 'PlanMaxGL' or 'PlanMaxGL{1}' or 'PlanMaxGL{green}'].

◆ eMsrFormulaResultType

enum ipsdk::shape::analysis::eMsrFormulaResultType

Enumerate describing measure formula result type.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMFRT_Logic	Measure formula is associated to a logical result.
eMFRT_Arithmetic	Measure formula is associated to an arithmetical result.

◆ eFormulaEvaluationStatus

enum ipsdk::shape::analysis::eFormulaEvaluationStatus

Enumerate describing measure formula evaluation status.

Note: This object is associated to a strong enumerate definition

See also: IPSDK_Enum

Enumerator
eMES_Success	Measure formula evaluation is successful.
eMES_Warning	Measure formula evaluation is successful with warnings.
eMES_Failure	Measure formula evaluation failed.

Function Documentation

◆ applyArithmeticFormula() [1/2]

IPSDKBASESHAPEANALYSIS_API Real64Vector ipsdk::shape::analysis::applyArithmeticFormula	(	const std::string &	formulaStr,
		const MeasureSet &	measureSet,
		const ipUInt64	cPlanIdx = `0`,
		const eMsrInputImageId &	msrInputImageId = `eMsrInputImageId::eMIII_Image1`
	)

function allowing to apply an arithmetic formula on an existing measure set

Note: call applyArithmeticFormula(formulaStr, measureSet, 0, eMsrInputImageId::eMIII_Image1, resultsColl)

Exceptions

ipsdk::shape::analysis::IPSDKBaseShapeAnalysisException if in case of failure

◆ applyArithmeticFormula() [2/2]

IPSDKBASESHAPEANALYSIS_API BoolResult ipsdk::shape::analysis::applyArithmeticFormula	(	const std::string &	formulaStr,
		const MeasureSet &	measureSet,
		const ipUInt64	cPlanIdx,
		const eMsrInputImageId &	msrInputImageId,
		Real64Vector &	resultsColl
	)