# Calculator Operation

On this page, you will find general help for the ProRaster product family including links to documentation, instructional videos, and training videos.
Previous Topic: Reproject – Resample – Realign Operation
Next Topic: Create Raster Mask Operation
Back to: ProRaster Scientific Help
Back to: ProRaster Help
Back to: ProRaster
Go to: ProRaster Essential help page, ProRaster Premium help page, ProRaster Scientific help page.

The Calculator operation outputs an MVR virtual raster that applies a calculator expression to the input data. The MVR will contain a single output band. You can select data from any inputs as variables in the expression. Those inputs can either be a raster source (which may contain multiple raster files), or a single raster file you have selected by browsing. Calculator does not support batch processing.

The Calculator evaluates the mathematical and logical expression that you have defined, at every raster location requested by the virtual raster engine. For example, when rendering, the virtual engine will evaluate the expression at every pixel centre. Calculator creates an MVR with a single Continuous field that contains one 32-bit floating point real value band. Be cognisant of the fact that the expression result will always be returned as a 32-bit real value.

Raster cells can either contain a valid value or an invalid value. In the calculator, an invalid value is referred to as a “null”. It is likely that your expression will generate either valid values or “null”, depending on the inputs and the evaluation of the expression logic. You may want to test to see if an input value is valid within the expression, to decide whether to process the value or not. To do this you can use the function “isnull()” or you can use a logical expression and the constant “null”.

You can define input variables that are linked to a raster, field, and band. When the Calculator evaluates the expression at a requested (X, Y) location, it will acquire the value of each input variable raster at that location. The Calculator can do this regardless of the coordinate systems of the input and output rasters, the cell sizes, cell data types, etc. It will acquire data in an appropriate projection, from an appropriate resolution level, using an appropriate interpolation technique, in real-time. Note that because a variable has a defined field and band, there is no “band notation” syntax supported in the calculator expression, and the expression only emits a single band output.

When you browse to a raster or select a raster source, a new dialog will open asking you to define the fields and bands that you want to include in your calculator expression.

The Calculator dialog will automatically generate a unique alias for every raster input. The alias will look like “A00” or “B14”. You will use these alias names when you refer to an input raster in the calculator expression. In the dialog, select the alias in the list, and the alias name is copied to the clipboard so you can paste it into your expression.

If an input variable is invalid (“null”) and it is used in a mathematical function, then the result will be invalid. For example, the expression “sin(A00)” will return the sin() of the variable A00 when it is valid, and it will return “null” otherwise. If an invalid value is consumed by a mathematical operator, then there are two different outcomes that you can control. For example, the expression “A00 + B00” adds two grids together. If either A00 or B00 is invalid, then we can either return “null” (strict null handling) or we can return that valid value and treat the invalid value as though it does not exist (relaxed null handling). In this example, relaxed null handling would result in valid data over the union of the two rasters and strict null handling would result in valid data over the intersection of the two rasters. This rule affects the operators (+, -, *, /), the comparison operators (<, <=, >=, >), and the ”cond”, “min” and “max” functions as described below.

+, –
If one of the input values is invalid, it is treated as though it is zero.

*
If one of the input values is invalid, it is treated as though it is one.

/
If either the numerator or denominator is invalid, it is treated as though it is one.

<, <=, >, >=
Invalid values are treated as though they are -infinite.

Cond
If the condition is invalid, return the result for a false condition.

Min
If one of the input values is invalid, return the other value.

Max
If one of the input values is invalid, return the other value.

The Calculator supports brackets “(“ and “)”. If you use a left bracket, you must close the bracket with a right bracket. Do not use square brackets “[]” or curly braces “{}”.

The Calculator supports two constants – “pi” (3.141592654) and “null” (a magic number). To use other constants in your expression, enter them as though they are real numbers. You can use the unary minus sign (e.g., -2.45) but it is a good idea to enclose values that use unary minus in brackets (e.g., A00+(-2.45)*B00). Otherwise, the expression parser gets confused and you may get an incorrect result. You can also use exponential notation using either “e” or “E” (e.g., 2.45e-2, -1e10, -1e-03, 2.45E-2).

Example expressions

To add two rasters together, use “A00 + B00”. With strict null handling, you will get a result only at the intersection of the two rasters. With relaxed null handling, you will get the union.

To merge two rasters together, use “A00 + B00” and use relaxed null handling.

To find the difference between two rasters, use “A00 – B00” and use strict null handling.

To average two rasters, use “(A00 + B00)/2” and use relaxed null handling.

To transform a raster Y = A*X + B, use “2.5*A00 + 2000” and use strict null handling.

To output a result where a raster is less than a constant, use “cond(A00<100,A00,null)” and use strict null handling.

To output a result where a raster is between two constants, use “cond(A00>=100 and A00<=200,A00,null)” and use strict null handling.

If you want to explicitly handle invalid values, then you can nest your conditions like this.

“cond(A00=null,null,cond(A00<100,A00,null))”

Rather than test against “null”, you can use the “isnull()” function.

“cond(isnull(A00),null,cond(A00<100,A00,null))”

This is equivalent to saying “if A00 is null, then output null, otherwise if A00 is less than 100 output A00, otherwise output null”.

Here is a complete list of all supported syntax and functions.

Constants

pi             3.141592654
null         -1E32 (a magic number representing an invalid cell value)

Mathematical Operators

–               subtraction
*              multiplication
/              division
^              power (A00^2 raises A00 to the power 2)

Brackets

()             Always close your brackets and do not use square brackets or curly braces.

Unary Minus

–               Negates the value of the operand. I recommend you surround the operand in brackets.

Logical Operators

=              Equal to. You can also use “==”.
< >           Not equal to. Do not use “!=”.
<              Less than
<=           Less than or equal to
>=           Greater than or equal to
>              Greater than
&             And. You can also use “&&” or “and”.
|              Or. You can also use “||” or “or”.

Conditional Functions

cond(exp,a,b)       Returns “a” if the expression evaluates true, or “b” otherwise.
You can also use an “IF exp THEN a ELSE b ENDIF” syntax.

isnull(a)                  Returns true if “a” is invalid (“null”).
any(x,…)                 Returns true if the operand x is equal to any of the following operands, or within the range of any of the following operands.

Specify a range of values as “x1:x2”. For example, use this expression to return several values and bands of values and invalidate the rest –
cond(any(A00,0,10,50,100:200,500:1000,5000:10000),A00,null)

Standard Numeric Functions

cos(x)                     Cosine of an angle of x radians.
sin(x)                      Sine of an angle of x radians.
tan(x)                      Tangent of an angle of x radians.
acos(x)                   Inverse of cosine.
asin(x)                    Inverse of sine.
atan(x)                    Inverse of tangent.
atan2(y,x)              Arc tangent of y/x, in radians.
cosh(x)                   Hyperbolic cosine of x.
sinh(x)                    Hyperbolic sine of x.
tanh(x)                   Hyperbolic tangent of x.
acosh(x)                 Inverse of hyperbolic cosine.
asinh(x)                  Inverse of hyperbolic sine.
atanh(x)                 Inverse of hyperbolic tangent.
pow(x,y)                 x raised to the power y.
sqrt(x)                    Square root of x.
exp(x)                     Eulers number raised to the power x.
log(x)                      Common base 10 logarithm of x, see log10().
ln(x)                        Natural logarithm of x, see log().
alog(x)                    Inverse common logarithm, pow(10,x).
aln(x)                      Inverse natural logarithm, exp(x).
abs(x)                     Absolute value of x.
mod(x)                   Floating point remainder of x/y, see fmod().
ceil(x)                     Rounds x upward, returning the smallest integral value that is not less than x.
floor(x)                   Rounds x downward, returning the largest integral value that is not greater than x.

These functions call the standard C or C++ functions of the same name (except where indicated). For help on these standard mathematical functions consult any C++ online reference.

Numeric Functions

round(x)                 Rounds x up or down to the nearest integer.
min(a,b)                 Returns minimum of a and b.
max(a,b)                 Returns the maximum of a and b.
rand()                     Returns a random number between 0 and 1.
unit(x)                    Clamps x to the range>=0 and <=1. Values below 0 are returned as zero and values above 1 are returned as one.
clamp(x,a,b)          Clamps x to the range>=a and <=b. Values below a are returned as a and values above b are returned as b.
clip(x,a,b)               Clips x to the range>=a and <=b. Values below a are returned as null and values above b are returned as null.

Even if a function takes no parameters, make sure you include the trailing closed brackets.

Bitwise Functions

bitand(a,b)             Bitwise “and” operator on the operands cast to unsigned 64-bit integers.
bitor(a,b)               Bitwise “and” operator on the operands cast to unsigned 64-bit integers.
bitxor(a,b)             Bitwise “xor” operator on the operands cast to unsigned 64-bit integers.
bitnot64(a)            Bitwise “not” operator on the operand cast to unsigned 64-bit integer.
bitnot32(a)            Bitwise “not” operator on the operand cast to unsigned 32-bit integer.
bitnot16(a)            Bitwise “not” operator on the operand cast to unsigned 16-bit integer.
bitnot8(a)              Bitwise “not” operator on the operand cast to unsigned 8-bit integer.
bitshl(a,b)              Bitwise shift left “b” bits on “a” cast to unsigned 64-bit integer.
bitshr(a,b)              Bitwise shift right “b” bits on “a” cast to unsigned 64-bit integer.

Logical Functions

not(a)                     Returns true when a is equal to zero.

Color Manipulation

rgba(r,g,b,a)          Converts r, g, b, alpha components (0–255) to a 32 bit 0xABGR value.
red(col)                  Return the red component (0-255) from a 0xFFBGR or 0xABGR value.
green(col)             Return the green component (0-255) from a 0xFFBGR or 0xABGR value.
blue(col)                Return the blue component (0-255) from a 0xFFBGR or 0xABGR value.
alpha(col)              Return the alpha component (0-255) from a 0xABGR value.
hue(r,g,b)              Convert color components (0-255) from RGB to HSI space and return hue.
saturation(r,g,b)   Convert color components (0-255) from RGB to HSI space and return saturation.
intensity(r,g,b)      Convert color components (0-255) from RGB to HSI space and return intensity.

Raster Constants

GetXOrigin()          Returns the x coordinate of the bottom left corner of the bottom left cell of the output raster.
GetYOrigin()          Returns the y coordinate of the bottom left corner of the bottom left cell of the output raster.
GetCellSizeX()       Returns the width of the base resolution cell size of the output raster.
GetCellSizeY()       Returns the height of the base resolution cell size of the output raster.
GetCols()                Returns the number of columns in the base resolution level of the output raster.
GetRows()              Returns the number of rows in the base resolution level of the output raster.

Even though these functions take no parameters, make sure you include the trailing closed brackets.

Raster Variables

GetX()                     Returns the X coordinate of the centre of the pixel being evaluated.
GetY()                     Returns the Y coordinate of the centre of the pixel being evaluated.

Even though these functions take no parameters, make sure you include the trailing closed brackets.