Map and Table Calculation

General syntax

Introduction

To calculate with raster maps, you can use the command line of the Main window; to calculate with columns in a table, you can use the command line of a table window.

A MapCalc or TabCalc formula consists of:

an output raster map name or an output column name that will contain the result of the calculation,
a definition symbol (=), or an assignment symbol (:=), and
an expression.

MapCalc syntax

OutputMap = Expression
OutputMap := Expression

TabCalc syntax

OutputColumn = Expression
OutputColumn := Expression

MapCalc formulae, typed on the command line of the Main window, are always performed on all pixels of the input map(s) and the answers are written to the pixels of the output map. By default, the command line of the Main window assumes raster map objects; when object extensions are specified, you can also work with other objects.
TabCalc formulae, typed on the command line of a table window, are by default performed on the records of the input column(s) and the answers are written to the records of the output column. By default, the command line of a table window assumes columns.

Notes:

It does not matter whether you type in capitals or in small characters; map and table calculation formulae are not case-sensitive.
When you use the Map Calculation dialog box, you have to type the expression part; the output map name has to be specified separately.
Advanced users who are certain that a typed formula is correct, may skip any dialog boxes by ending the expression with a semi-colon (;).
To use TabCalc formulae in a script, i.e. using TabCalc formulae on the command line of the Main window, see Appendices : ILWIS script language (syntax), section TabCalc.
ILWIS integer mathematics is limited to 32 bits (i.e. from -2147483647 to 2147483647). This means that any integer calculation which exceeds these limits, also within memory, may lead to unpredictable results.
Using a MapCalc expression like Map1=Map1*1000 leads to an error message because the expression is cyclic. The same goes for a TabCalc expression like Column1=Column1*100.

Examples

MapCalc example

A simple MapCalc formula reads:

OutMap = InMapA + InMapB

InMapA

InMapB

OutMap

1	2	3
4	5	6
7	8	9

10	20	30
40	50	60
70	80	90

11	22	33
44	55	66
77	88	99

The values of the pixels in OutMap are the sums of the values in the corresponding pixels of InMapA and InMapB.

TabCalc example

A simple TabCalc formula reads:

OutColumn = InColumnA + InColumnB

In the table, this looks as follows:

InColumnA	InColumnB	OutColumn
1	10	11
2	20	22
3	30	33
4	40	44

Each record in column OutColumn stores the sum of the values of the records in InColumnA and InColumnB.

Names of maps and tables

In ILWIS 3, object names, i.e. input or output map or table names, comply with Windows long file names.

In object names, any character may be used except \ / : * ? < > | "
The maximum length of an object name is 255 characters including the full path.

Furthermore, it is not allowed to use % in any ILWIS object name.

However, on the command line, object names must be enclosed by single quotes when the object name:

starts with a digit from 0 to 9;
contains one or more spaces;
contains any of the following characters ` ~ ! @ # $ ^ & ( ) - + = [ ] { } ; ' , .

Object extensions should be left outside the quotes. When an object name already contains a single quote, this single quote must be duplicated.

Thus, on the command line, single quotes around object names can only be omitted when object names start with a character between A to Z and do not contain spaces nor special characters.

Note:

When an existing output map name is specified, a message box will appear asking whether to overwrite the existing map or not.

For more information and examples, see How to use long object names.

Definition symbol = Assignment symbol :=

By using the defintion symbol =, a dependent output map or a dependent output column will be created.

A dependent map or a dependent column has the following advantageous characteristics:

the formula/expression by which the map or column was created is stored (this is also called the definition of a map or column),
the formula/expression by which the output map or column was created can be changed/edited,
a series of dependent maps or columns can be recalculated/made up-to-date, when a single definition or a single input map or column has changed.

You can manage dependent maps and columns through:

the Raster Map Properties sheet of a dependent map,
the Column Properties of a dependent column.

For more information, refer to Basic concepts : dependent data objects.

Tip: To make all columns in a table up-to-date, you can also click the Update all columns button in the toolbar of a table window.

By using the assignment symbol :=, an editable map or column will be created. Dependency links are immediately broken after the output map or the output column has been calculated.

Note: It does not matter whether you type spaces around the definition or assignment symbol, or in the expression or not.

Expression

The expression usually contains one or more input map names or column names combined with operators and/or functions to specify what calculation has to be performed. The operators and functions which can be used in Table Calculations are identical to those in Map Calculation.

For overviews of operators and functions, see:

Operators are for instance + - / * ^ etc.
Some regularly used functions are for instance IFF(a,b,c), a AND b, SQRT(a), POW(a,b), LOG(a), etc.
Some constant values are predefined: the value p can be used by typing PI, the value e can be used by typing EXP(1).
To use line numbers or column numbers as variables in calculations, you can use %L (line) or %C (column).
To use X-coordinates or Y-coordinates as variables in calculations, you can use %X and %Y.
To use record numbers, or class names or IDs from the table domain as variables in calculations, you can use %R (record) and %K (key).

Examples of the usage of a function are presented in the topic on the function.

Furthermore, advanced users may wish to create their own functions. For more information, see Map and Table Calculation : User-defined functions.

Notes:

Input object names that contain spaces or special characters should be enclosed by 'single quotes', see the section on Names of maps and tables above.
When using class names or IDs or their codes in expressions, these should be enclosed by "double quotes", e.g. "Coffee".

Tip:

It is advised to use built-in functions instead of creating a combination of simple functions which perform the same calculation because pre-defined functions are quicker.

Miscellaneous

General information on the command lines:

The maximum length of an expression on the command line is 32000 characters. You can use the (Ctrl+) Left and Right Arrow keys on the keyboard to move back and forth in your formula. Use the somewhat larger MapCalc dialog box if you wish to type a MapCalc formula on multiple lines.
The command line has a history: press the Up Arrow key to retrieve previously used expressions; the Down Arrow key is used to 'scroll' forward again. You can also open the list of previously used commands and expressions by clicking the arrow at the right hand side of the command line. The amount of commands and expressions that can be retrieved can be set in the Preferences.
You can use the command line as a pocket calculator by typing a question mark ? followed by an expression, i.e. do not specify an output map/column name nor a definition or assignment symbol.

Raster Map Definition dialog box:

After typing a MapCalc formula on the command line of the Main window, and pressing Enter, the Raster Map Definition dialog box will appear, in which you can:

accept or modify your expression;
accept or specify the domain that should be used by the output map;
for value maps, accept or modify the value range and precision of the output map;
accept or modify the description of the output map.

Normally, ILWIS will come up with correct defaults for domain, value range and precision.

Column Properties dialog box:

After typing a TabCalc formula on the command line of a table window, and pressing Enter, the Column Properties dialog box will appear, in which you can:

accept or modify your expression;
accept or specify the domain that should be used by the output column;
for value columns, accept or modify the value range and precision of the output column;
specify the position of the column in the table, the width with which the column should be displayed, the number of decimals that should be displayed;
accept or modify the description of the output column.

Normally, ILWIS will come up with correct defaults for domain, value range and precision.

Overruling the default domain, value range and precision:

Generally, ILWIS will use correct defaults for the domain and possible value range and precision of the output map(s) or columns. When using the Raster Map Definition dialog box or the Column Properties dialog box, you will notice this. In scripts however, these dialog boxes will never appear.

To ensure that an output map or column will use a certain domain, and/or a certain value range and/or a certain precision, you can specify this yourself within a pair of curly brackets {} after the output map/column name.

Within the curly brackets, you can specify:

the domain as dom=MyDomain
the value range as vr=min:max:precision, or as vr=min:max, or as vr=::precision

When you specify both domain and value range, separate these with a semicolon.

Notes:

ILWIS expressions are not case-sensitive.
Spaces are allowed after output object names, around the definition or assignment symbol, and before and behind brackets, commas, or semicolons.
Spaces are not allowed before or behind colons.
ILWIS uses its internal defaults to determine whether the internal calculation will be performed in integers or in reals.
In general it can be said, that:
- when the input consists of integers, the internal calculation will also be performed in integers;
- when the input consists of reals, the internal calculation will also be performed in reals.
Any user specification of the desired output domain and value range can only limit the results from the internal calculation. It is thus not possible, that when all input is in integers, to obtain output in reals by using a precision smaller than 1, for instance by using OUT{dom=Value;vr=0:10000:0.001} = ....

Examples

OUT1{dom=MyVal} = expression

OUT2{dom=MyVal;vr=0:10000:1} = expression

OUT3{dom=MyVal;vr=0:10000} = expression

OUT4{dom=MyVal;vr=::0.001} = expression

Tip: For more information and examples, see Appendices : Construction of expressions.