genre | Arithmetic |
authors | Lennart Tautz, Ola Friman |
package | FMEstable/ReleaseMeVis |
dll | MLArithmetic |
definition | MLArithmetic.def |
see also | Arithmetic0, Arithmetic1, Arithmetic2, ComplexArithmetic1, ComplexArithmetic2, SoCalculator, Calculator, TypeArithmetic1, TypeArithmetic2, TestPattern, ConstantImage |
keywords | arithmetic, expression, evaluation, calculator, calculation, voxelwise, image, operation, mathematics, logic, log, exp, abs, sin, cos, tan, min, max, add, subtract, minus, multiply, divide, scalar, vector, complex, quaternion, matrix |
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.
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 and used input image. Note that for the aforementioned properties only those images are considered that are used in the expression. This holds for the output type as well (see below). This module supports multi-threading.
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 |
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.
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 | - | - | - | - | ||
|
|||||||
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 | - | ||
|
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 | *, /, %, .*, ./ |
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.
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) |
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
|
A function argument can be one of the following:
The variables f1-f6 and ld1-ld6 redirect to d1-d6 and d7-d12 both as fields and as variables in the expression.
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.
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.
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.
The module has ten image inputs and one output image. Inputs 'c' and above are hidden by default.
Apply Mode: Enum | d7: Double | Info: String |
Clear Variables: Trigger | d8: Double | Max: Float |
Comment: String | d9: Double | Min: Float |
Comments: String | Data Type: Enum | Replacement Value on Domain Error: Enum |
d1: Double | Expression: String | Set data type: Bool |
d10: Double | Handling on Domain Error: Enum | Set image extent: Bool |
d11: Double | i1: Integer | Set min/max values: Bool |
d12: Double | i2: Integer | Update: Trigger |
d2: Double | i3: Integer | Update Mode: Enum |
d3: Double | i4: Integer | Visible Inputs: Integer |
d4: Double | i5: Integer | Warn On Deprecated Expression Parts: Bool |
d5: Double | i6: Integer | |
d6: Double | Image Extent: String |
Double variable d1
Double variable d2
Double variable d3
Double variable d4
Double variable d5
Double variable d6
If checked, the min/max values of the output image are set to the indicated values.
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 |
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.
Set the desired extent as string. Each of the six dimensions is given by an integer, separated by spaces. Minimum extent is 1, which will be used when the extent for a dimension is less than 1.
If checked, the extent of the output image is set to the indicated extent string.
When the expression is invalid or an error occurred during evaluation, an error message is shown here.
Set the desired behavior when the input images change.
Values:
Title | Name | Description |
---|---|---|
Auto Clear | AutoClear | The output is cleared when an input image changes. |
Auto Update | AutoUpdate | The output is updated when an input image changes. |
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. |
Force update with the current input images, variables and settings.
Set what should happen when evaluation of a voxel generates a domain error. Note that the result image will always contain the replacement value at the affected voxels.
Values:
Title | Name | Description |
---|---|---|
Nothing | Nothing | Only fill the result with the replacement value. |
Error Message | ErrorMessage | Print an error message. |
Throw Error | ThrowError | Throw an error that will break page calculation. |
Set what should be used as replacement value if a result voxel cannot be computed properly because of a domain error.
Values:
Title | Name | Description |
---|---|---|
Zeroes | Zeroes | Fill with "zeroes" of the result data type. |
Enter number of visible input connectors.
Set all variables to zero.
You can document the purpose of the expression here.