Purpose

This module performs voxel-wise arithmetic operations with up to ten input images. The output is the processed image according to the entered arithmetic expression and chosen variables.

Usage

Enter the arithmetic expression you want to apply to the input images. You can specify additional variables in the respective fields. The expression is evaluated voxel-wise. Input images must have the same extent, otherwise no output will be calculated. The min/max values of the output image will be the minimum and maximum, respectively, of the inputs’ min/max values. The voxel-to-world matrix will be taken from the first valid input image. Note that for the aforementioned properties all connected and valid images are considered. This holds for the output type as well (see below), and in particular for the constant expressions that don’t use image variables. This module supports multi-threading.

Output type

The output type is chosen so that it can hold the result. It is possible to combine input images of different types to a certain degree, as long as the types are reasonably compatible. Furthermore, if the expression will result in fractional results (i.e. by using fractional constants or trigonometric functions), the output type will changed to the next higher type able to hold such results. This may lead to a loss of precision when using MLint64 as input type. Note that due to the determination of the output type from the input types, functions such as real, imag and arg retain the complex input type, but exhibit an imaginary part of zero. If the expression uses unary minus, the type is likewise changed so that it can hold signed values. If the expression uses bitwise logical functions, the type is changed to an unsigned integer type. If variables are used, the type is changed so that it can hold their values. If the type requirements of the expression, the input images and the variables cannot be met by any type, no output will be calculated.

The following table summarizes the conditions that change the output type when met.

Condition Output type is at least
Decimal number (e.g. ‘1.2’) MLfloat
Constant ‘pi’ MLdouble
Double variable (d1-d12) MLdouble
Trigonometric and certain other functions:
cos, sin, tan, acos, asin, atan,
cosh, sinh, tanh, exp, log,
log10, log2, sqrt, root
 MLfloat
Unary minus (e.g. ‘-i1’) MLint8
Bitwise functions MLuint8

Output page extent

The page extent of the output image will be copied from the left-most image that is connected. The page extent is never modified. This table exemplifies some use cases:

Image0 Page Extent Image1 Page Extent Expression Output Page Extent
48x16 32x32 a + b 48x16
48x16 48x16 a + b 48x16
48x16 32x32 b 48x16

Combination of input types

Generally, the inputs must be of the same type. Combinations of different types, e.g., vectors and scalars or matrices and vectors, are not possible. Scalar types can be arbitrarily combined, but certain combinations may lead to loss of precision or information. Other types that are compatible internally, such as complexf and complexd, or Vector16 and Vector64, may be used together under the same conditions. Scalar multiplication and division of vectors (vec and vecf types) and matrices (mat and matf types) is realized through component-wise multiplication and division, respectively, with a vector/matrix containing the value of the scalar in all components.

Support of registered types

The dimension of input and output types is always the same. This means that you cannot, for example, calculate the norm of a vector. Instead, many functions that are available for registered types will be calculated component-wise (e.g. cos on each component instead of cos on a whole vector). However, many functions are not supported at all for certain types. Note that there will be no error message if you try to use incompatible types and functions. The output image will simply not be computed. See the tables below for more information.

This table shows the available types and their association to type groups (for ease of read):

Type group ML types
Standard
MLint8, MLuint8, MLint16, MLuint16, MLint32, MLuint32, MLint64, MLuint64,
MLfloat, MLdouble
Complex complexf, complexd, complexld
Quaternion quaternionf, quaterniond, quaternionld
Vector
vec2, vec3, vec4, vec5, vec6, vec7, vec8, vec9, vec10, vec16, vec32, vec64,
vecf2, vecf3, vecf4, vecf5, vecf6, vecf7, vecf8, vecf9, vecf10, vecf16,
vecf32, vecf64
Matrix mat2, mat3, mat4, mat5, mat6, matf2, matf3, matf4, matf5, matf6

This table shows which type group supports which functions. While ‘Y’ and ‘-’ indicate (native) support and no support, respectively, ‘C’ indicates support by means of component-wise calculation.

Function Standard Complex Quaternion Vector Matrix
Basic functions
+ Y Y Y Y Y
- Y Y Y Y Y
* Y Y Y C C
/ Y Y - C C
% Y - - - -
- (unary) Y Y Y Y Y
min Y - - C C
max Y - - C C
diff Y - Y C C
abs Y Y C C C
sgn Y - C C C
absmin Y - - C -
absmax Y - - C -
Trigonometric functions
cos Y - - C C
sin Y - - C C
tan Y - - C C
cosh Y - - C C
sinh Y - - C C
tanh Y - - C C
acos Y - - - -
asin Y - - - -
atan Y - - - -
atan2 Y - - - -
Exponential and logarithmic functions
pow Y Y - C -
sqr Y Y - C -
root Y - - - -
sqrt Y Y - C C
exp Y - - C C
log Y - - C C
log10 Y - - C C
log2 Y - - C C
Logical functions
== Y Y Y Y Y
!= Y Y Y Y Y
< Y - - C C
> Y - - C C
<= Y - - C C
>= Y - - C C
and Y - - - -
or Y - - - -
xor Y - - - -
imp Y - - - -
! Y - - - -
& [1] Y - - - -
| [1] Y - - - -
^ [1] Y - - - -
if Y - - - -
[1](1, 2, 3) for unsigned integer types only
Rounding functions
floor Y - - C C
ceil Y - - C C
round Y - - C C
Functions on complex values
arg - Y - - -
real - Y - - -
imag - Y - - -
conj - Y - - -
Functions on vector and matrix values
.* - - - Y Y
./ - - - Y Y
norm - - - Y -
dot - - - Y -
cross - - - Y [2] -
length - - - Y -
[2]for vec3 and vecf3 only

Operator precedence

The following table lists the precedence of infix functions, where a higher precedence group means higher precedence.

Precedence group Functions
1 imp
2 or / ||
3 xor
4 and / &&
5 |
6 ^
7 &
8 ==, !=
9 <, >, <=, >=
10 +, -
11 *, /, %, .*, ./

Details

The arithmetic language over images used in this module combines functions and arguments to form an arithmetic expression.

If you enter an invalid expression, a message indicating the error will be displayed in the module panel.

Functions

Function Syntax Description
Basic functions
+ a + b Addition
- a - b Subtraction
* a * b Multiplication
/ a / b
Division
If b is zero, a domain error occurs
% a % b Modulo
- - a Unary minus (invert)
min min(a, b)
Minimum of arguments
Applied component-wise to vector and matrix values
max max(a, b)
Maximum of arguments
Applied component-wise to vector and matrix values
diff diff(a, b) Difference (absolute value after subtraction)
abs abs(a) Absolute value
sgn sgn(a) Signum (result is 1 for positive values, 0 for zero and -1 for negative values)
absmin absmin(a, b)
Returns the argument that has the minimum absolute value
If the absolute values are equal, the minimum is returned
Applied component-wise to vector values
absmax absmax(a, b)
Returns the argument that has the maximum absolute value.
If the absolute values are equal, the maximum is returned
Applied component-wise to vector values
Trigonometric functions
cos cos(a) Cosine
sin sin(a) Sine
tan tan(a) Tangent
cosh cosh(a) Hyperbolic cosine
sinh sinh(a) Hyperbolic sine
tanh tanh(a) Hyperbolic tangent
acos acos(a)
Inverse cosine
If a is outside of range [-1;1], a domain error occurs
asin asin(a)
Inverse sine
If a is outside of range [-1;1], a domain error occurs
atan atan(a) Inverse tangent
atan2 atan2(y, x) atan2 (note reversed argument order)
Exponential and logarithmic functions
pow pow(a, b) a raised to the power of b
sqr sqr(a) a squared
root root(a, b)
b-th root of a
If b is zero, a domain error occurs
sqrt sqrt(a)
Square root
If a is negative, a domain error occurs
exp exp(a) e raise to the power of a
log log(a)
Natural logarithm
If a is zero or negative, a domain error occurs
log10 log10(a)
Decadic logarithm
If a is zero or negative, a domain error occurs
log2 log2(a)
Binary logarithm
If a is zero or negative, a domain error occurs
Logical functions
== a == b Equality
!= a != b Inequality
< a < b
a is less than b
Applied component-wise to vector and matrix types
For those types, the comparison is true if all components compare true
> a > b
a is greater than b
Applied component-wise to vector and matrix types
For those types, the comparison is true if all components compare true
<= a <= b
a is equal to or less than b
Applied component-wise to vector and matrix types
For those types, the comparison is true if all components compare true
>= a >= b
a is equal to or greater than b
Applied component-wise to vector and matrix types
For those types, the comparison is true if all components compare true
and
&&
a and b
a && b
 Logical AND
or
||
a or b
a || b
 Logical OR
xor a xor b Logical XOR (exclusive OR)
imp a imp b Logical implication
! ! a Logical NOT
& a & b Bitwise AND
| a | b Bitwise OR
^ a ^ b Bitwise XOR (exclusive OR)
if if(a, b, c) Conditional expression | This is replaced by (a)*(b)+!(a)*(c) internally for now.
Rounding functions
floor floor(a) Floor value
ceil ceil(a) Ceil value
round round(a) Rounded value
Functions on complex values
arg arg(a) Argument of complex value | Result is a complex value where both parts are set to the result
real real(a) Real part of complex value | Result is a complex value where both parts are set to the result
imag imag(a) Imaginary part of complex value | Result is a complex value where both parts are set to the result
conj conj(a) Complex conjugate of complex value
Functions on vector and matrix values
.* a .* b Component-wise multiplication
./ a ./ b Component-wise division
norm norm(a) Normalize a to unit vector
dot dot(a, b)
Dot product
Result is a vector where all components are set to the result
cross cross(a, b)
Cross product
Available only for vec3 and vecf3 types
length length(a)
Length of vector
Result is a vector where all components are set to the result

Arguments

A function argument can be one of the following:

  • An input image (a through j). The expression is evaluated for every voxel of the indicated input image.
  • A literal value (for example 5, -5 or 1.3, but not 2.). When the expression is evaluated over a multi-component type such as vectors or matrices, a literal number is converted to a value of that type where all components are set to that number.
  • A built-in constant: pi
  • A variable (i1-i6, d1-d12). The variable is evaluated to the value set in the module panel.
  • A coordinate variable (cx, cy, cz, cc, ct, cu). During evaluation, these variables hold the dimensional coordinates of the current voxel.

Legacy Support

The variables f1-f6 and ld1-ld6 redirect to d1-d6 and d7-d12 both as fields and as variables in the expression.

Tips

Pure constant expressions

You can create a constant image by omitting any input image arguments from the expression and enabling the data type and image extend setting fields. In some cases this might be better than using a ConstantImage or TestPattern as input image for the Arithmetic.

Setting min/max values

Typically, the min value of the output image is the minimum of the min values all used input images (likewise the maximum of all values for the max value). This heuristic will usually produce somewhat reasonable, but still wrong min/max values. If you or your application know the exact (or desired) values, you should set them manually in the Settings tab.

Input connectors

If less than ten inputs are required, the open connectors can be hidden by setting an appropriate number here. If a connector is hidden by this, it is disconnected.

Windows

Default Panel

../../../Modules/ML/MLArithmetic/mhelp/Images/Screenshots/Arithmetic._default.png

Input Fields

The module has ten image inputs and one output image. Inputs ‘c’ and above are hidden by default.

input0

name: input0, type: Image

Image ‘a’ in expression

input1

name: input1, type: Image

Image ‘b’ in expression

input2 (hidden)

name: input2, type: Image

Image ‘c’ in expression

input3 (hidden)

name: input3, type: Image

Image ‘d’ in expression

input4 (hidden)

name: input4, type: Image

Image ‘e’ in expression

input5 (hidden)

name: input5, type: Image

Image ‘f’ in expression

input6 (hidden)

name: input6, type: Image

Image ‘g’ in expression

input7 (hidden)

name: input7, type: Image

Image ‘h’ in expression

input8 (hidden)

name: input8, type: Image

Image ‘i’ in expression

input9 (hidden)

name: input9, type: Image

Image ‘j’ in expression

Output Fields

output0

name: output0, type: Image

Result of evaluated expression

Parameter Fields

Field Index

Apply Mode: Enum d6: Double i4: Integer
Clear Variables: Trigger d7: Double i5: Integer
Comments: String d8: Double i6: Integer
d1: Double d9: Double Info: String
d10: Double Data Type: Enum Max: Float
d11: Double Expression: String Min: Float
d12: Double Expression Comment: String Set data type: Bool
d2: Double Handling on Domain Error: Enum Set min/max values: Bool
d3: Double i1: Integer Update: Trigger
d4: Double i2: Integer Update Mode: Enum
d5: Double i3: Integer Visible Inputs: Integer

Visible Fields

Expression

name: expression, type: String

Enter an expression.

i1

name: i1, type: Integer, default: 0, deprecated name: intConstant0

Integer variable i1

i2

name: i2, type: Integer, default: 0, deprecated name: intConstant1

Integer variable i2

i3

name: i3, type: Integer, default: 0, deprecated name: intConstant2

Integer variable i3

i4

name: i4, type: Integer, default: 0, deprecated name: intConstant3

Integer variable i4

i5

name: i5, type: Integer, default: 0, deprecated name: intConstant4

Integer variable i5

i6

name: i6, type: Integer, default: 0, deprecated name: intConstant5

Integer variable i6

d1

name: d1, type: Double, default: 0, deprecated name: ld1,longDoubleConstant0

Double variable d1

d2

name: d2, type: Double, default: 0, deprecated name: ld2,longDoubleConstant1

Double variable d2

d3

name: d3, type: Double, default: 0, deprecated name: ld3,longDoubleConstant2

Double variable d3

d4

name: d4, type: Double, default: 0, deprecated name: ld4,longDoubleConstant3

Double variable d4

d5

name: d5, type: Double, default: 0, deprecated name: longDoubleConstant4,ld5

Double variable d5

d6

name: d6, type: Double, default: 0, deprecated name: ld6,longDoubleConstant5

Double variable d6

d7

name: d7, type: Double, default: 0, deprecated name: floatConstant0,f1

Double variable d7

d8

name: d8, type: Double, default: 0, deprecated name: f2,floatConstant1

Double variable d8

d9

name: d9, type: Double, default: 0, deprecated name: floatConstant2,f3

Double variable d9

d10

name: d10, type: Double, default: 0, deprecated name: floatConstant3,f4

Double variable d10

d11

name: d11, type: Double, default: 0, deprecated name: floatConstant4,f5

Double variable d11

d12

name: d12, type: Double, default: 0, deprecated name: floatConstant5,f6

Double variable d12

Min

name: minValue, type: Float, default: 0

New min value of the output image.

Max

name: maxValue, type: Float, default: 1

New max value of the output image.

Set min/max values

name: setMinMaxValues, type: Bool, default: FALSE

If checked, the min/max values of the output image are set to the indicated values.

Data Type

name: dataType, type: Enum, default: int8

Set the desired data type here.

Values:

Title Name
int8 int8
unsigned int8 unsigned int8
int16 int16
unsigned int16 unsigned int16
int32 int32
unsigned int32 unsigned int32
float float
double double
int64 int64
unsigned int64 unsigned int64
complexf complexf
complexd complexd
quaternionf quaternionf
quaterniond quaterniond
vec2 vec2
vec3 vec3
vec4 vec4
vec5 vec5
vec6 vec6
vec7 vec7
vec8 vec8
vec9 vec9
vec10 vec10
vec16 vec16
vec32 vec32
vec64 vec64
mat2 mat2
mat3 mat3
mat4 mat4
mat5 mat5
mat6 mat6
matf2 matf2
matf3 matf3
matf4 matf4
matf5 matf5
matf6 matf6
vecf2 vecf2
vecf3 vecf3
vecf4 vecf4
vecf5 vecf5
vecf6 vecf6
vecf7 vecf7
vecf8 vecf8
vecf9 vecf9
vecf10 vecf10
vecf16 vecf16
vecf32 vecf32
vecf64 vecf64

Set data type

name: setDataType, type: Bool, default: FALSE

If checked, the output image is set to the indicated type, and the expression is evaluated over that type. Keep in mind that mixing incompatible types and expressions can produce very odd results.

Info

name: statusBar, type: String, persistent: no

When the expression is invalid or an error occurred during evaluation, an error message is shown here.

Update Mode

name: updateMode, type: Enum, default: AutoUpdate, deprecated name: autoUpdate

Set the desired behavior when the input images change.

Values:

Title Name Deprecated Name Description
Auto Clear AutoClear FALSE The output is cleared when an input image changes.
Auto Update AutoUpdate TRUE The output is updated when an input image changes.

Apply Mode

name: applyMode, type: Enum, default: AutoApply

Set the desired behavior when parameter fields change. For this purpose, the following fields are parameter fields: the expression field, all variable fields, the min and max value setting fields, the data type setting field and the image extent setting field.

Values:

Title Name Description
Auto Clear AutoClear The output is cleared when a parameter field changes.
Auto Apply AutoApply The output is updated when a parameter field changes.

Update

name: update, type: Trigger

Force update with the current input images, variables and settings.

Handling on Domain Error

name: domainErrorHandling, type: Enum, default: ErrorMessage

Set what should happen when evaluation of a voxel generates a domain error. Note that the result image will always contain a 0 (or equivalent value) at the affected voxels.

Values:

Title Name Deprecated Name Description
Error Message ErrorMessage Nothing Print an error message. For every page with a domain error, one message is printed.
Throw Error ThrowError   Throw an error that will break page calculation and print an error message. For every page with a domain error, one message is printed.

Visible Inputs

name: numberOfInputs, type: Integer, default: 2, minimum: 0, maximum: 10

Enter number of visible input connectors.

Clear Variables

name: clearScalarVariables, type: Trigger, deprecated name: clearScalarConstants

Set all variables to zero.

Expression Comment

name: expressionComment, type: String

You can document the purpose of the expression here.

Comments

name: scalarVariablesComment, type: String, deprecated name: scalarConstantsComment

You can document the purpose of the variables here. This can be useful when external fields are connected.