How to use
modified 18 March 2024 by Paweł Netzel
plMapcalc runs macros to perform calculations on spatial data. It is a command line tool. So, a user has to know both command line syntax to run mapcalc command and macro syntax to program calculation procedure or expression.
Command line syntax
To run plMapcalc, a user has to call plmapcalc program. The program can describe itself. One can run it without any option or with -h or --help option. The result is as follows:
$ plmapcalc
usage:
plmapcalc [-hqf] [--check] [--use-nan] [-t <n>]
-i file.tif[[[band_no]:shift_x]:shift_y]
[-i file.tif[[[band_no]:shift_x]:shift_y]]...
[-o file.tif[:type[:no_data:[compression]]]]...
[-m <n>] [-r <file name>] [-s <file name>] [-0]
[-e ' code '] [-p <file>.mc]
[--execute-begin=' code '] [--program-begin=<file>.mc]
[--execute-end=' code '] [--program-end=<file>.mc]
-h, --help program usage
-q, --quiet quiet mode
--check display parameters and check their correctness
-f, --force force to overwrite output file
--use-nan force to treat NAN as a value (default: no-data)
-t, --threads=<n> number of threads
-i, --input=file.tif[[[:band_no]:shift_x]:shift_y]
input layer(s) (GeoTIFF or any other GDAL raster format),
optionally followed by the band number, horizontal shift
by the specified number of cells (a negative value means
a rightward shift), vertical shift by the specified number
of cells (a negative value means a downward shift)
-o, --output=file.tif[:type[:no_data:[compression]]]
output layer(s): file name, data type (Byte, Int16,
UInt16, Int32, UInt32, Float32, default Float64), n
o_data value (default 0.0), compress (NONE, DEFLATE
, DEFLATE2, DEFLATE3, LZW, LZW2, LZW3). (GeoTIFF)
-m, --memory=<n> number of memory cells to store temporary data
-r, --memory-read=<file name>
file to read memory cells (TXT)
-s, --memory-store=<file name>
file to store memory cells (TXT)
-0, --store-zeroes store all memory cells including zeros (defalt: no)
-e, --execute=' code ' code to execute
-p, --program=<file>.mc file with code to execute
--execute-begin=' code '
code to execute at the start
--program-begin=<file>.mc
file with code to execute at the start
--execute-end=' code '
code to execute at the end
--program-end=<file>.mc
file with code to execute at the end
A user has to define -e or -p option!
plMapcalc version: 1.4.728 (20240318.0820)
The minimum number of arguments is one input raster layer and macro to run. Macro can be provided in-line or as script file with a macro definition.
There are four groups of arguments:
- input/output layer definition: -i, -o;
- memory buffer definition: -m, -r, -s, -0;
- macro definition: -e, -p, --check, --execute-begin, --execute-end;
- others: -q, -f, -h, -t.
input/output layer options
A program user has to enter file name of input file using -i option. It could be an absolute or relative path to the file. The option -i can be used multiple times. That enables a user to define many input raster layers. In addition, the user can indicate which band to read from the input layer. The input layers can be shifted (on the fly) by a preset number of cells both horizontally and vertically. This makes it possible to access the surroundings of a central cell by defining the input layer more than once using offsets.
The option -o is to define output layer. This option can be used multiple times as well. A user can add up to three parameters after a file name/path. The first one defines data type of output layer, the second – no-data value, and the last one compression algorithm. These parameters are optional. By default, plMapcalc will store output data as double floating point raster layer, without no-data value, and not compressed.
memory buffer options
One can define storage memory buffer in plMapcalc. This storage can be used for different tasks. For example: to calculate global statistics of raster layer, to build frequency tables or histograms, to reclassify input data etc.
A program user can define how many memory cells should be available. The option -m followed by integer number it is for that.
plMapcalc can read initial data to fill memory buffer from text file. A user has to point path to text file with data to read with option -r. Each line in this file should contain memory cell index, blank space, and memory cell value. An example of such file is below.
0 41623.279724212028668262
1 35513.439075932932610158
2 28021.639102664925303543
3 28041.327999936092965072
4 20369.025455332906858530
The input file can contain lines for all memory cell but this is not a critical condition. One can define only selected cells in the text file. Rest of the memory cells will be initialized with zeroes. plMapcalc will read the data from text file BEFORE start any calculations.
Memory buffer can be stored AFTER all calculations will be finished. If the user adds -w option, plMapcalc will store non-zero memory cells into a text file. The internal structure of the file will be identical to the format of the input text file. To save ALL memory cells, including zeros, a user has to use -0 or –store-zeros option in program call.
macro options
An equation or macro or program (very complex macro) can be entered in two ways: as a command line parameter or as a file containing the macro. A user can specify three macros:
- BEGIN macro – this macro will be run before start calculations; it can be used to do initialization operations;
- CELL macro – this macro will be called for each raster cell;
- END macro – this macro will be run after calculations of all cells in input layers; it can be used to calculate statistics and/or do post-processing operations.
BEGIN and END macros are optional. To specify CELL macro in a command line, the option -e has to be used. The macro should be enclosed in quotation marks. In Linux, it can be single quotation characters. In Windows, it should be double quotation characters.
If the macro is large and complex, it can be stored in a text file. Formatting and text aligning in such file is free and should satisfy rules of C language.
The option -p specifies the file name (with or without full/relative path). The macro will be read into memory and processed in the same way as entered from command line.
There are two options available in long format only to specify BEGIN and END macros - --execute-begin and –execute-end respectively.
plMapcalc has additional option --check to run „dry” calculation. If this option is present in plMapcalc call, the program will only check syntax and try to compile the macros without any calculations. The user can use this option during the macros build.
other options
Among others options, plMapcalc has a small set auxiliary option. The option -q forces the program to run without any messages. The option -f tells the program to overwrite output raster layers. By default, the program prevents raster layers overwriting. The option -h displays a short usage info. The option -t is for specifying number of threads that can be used by plMapcal. plMapcalc can do calculations in parallel with I/O operations. The –use-nan option enables plMapcalc to switch-on using INF and NAN values in calculation. The default behavior is to treat these values as no-data.
Macro and macro’s predefined variables
A user should know C syntax to create macros for mapcalc application. But there is no need to learn C language as a language or to learn how to compile and build executables in C.
The only knowledge necessary to work with plMapcalc is a few C expressions and C-style punctuation. Such knowledge is enough to define most of the spatial raster operations. The macro language of plMapcalc contains all mathematical functions available in C. If needs arise, a user can create more complex macros and even programs implementing advanced algorithms.
When any doubt occurs, refer to ANSI C language documentation and tutorials.
plMapcalc works in the following way: reads macros, compiles macros, run BEGIN macro, walks from cell to cell across region defined by input files and runs the CELL macro for each cell, finally run END macro. Thanks to the binary format of the macros, calculations are very fast.
Input data, output results, and memory buffer are available in macros through set of variables. These variables are named using capitalics. Input and output are not available in BEGIN and END marcos.
Location
The CELL macro should know “where are we”. Answer to this question is couple of variables: COL, ROW. These variables contain location (in terms: which column and which row) of current calculations. Both variables are type of integer.
Input and output
There are four variables responsible for communication with raster layers: IN[], OUT[], INPNUM, OUTNUM. IN[] are an array. That means a user can call an array element with index. All arrays in C are indexed starting from zero. So, a user has to type-in IN[3] to obtain the value of the 4th element of the array. IN array has INPNUM elements. The index can have a value from 0 to INPNUM-1. The value of INPNUM equals to the number of -i options in the program command line call.
OUT[] array and OUTNUM variable work in the same way. The only difference is set of layers. OUT[] and OUTNUM are defined base on a number of output layers.
INPNUM and OUTNUM are integers. IN[] and OUT[] arrays are arrays of double type numbers. Even if input layer contains integer numbers these numbers are converted to double.
Order of layers represented in IN[] and OUT[] arrays depends on order of layers occurrence in command line program call.
Memory buffer
Memory buffer is represented by MEM[] array. The number of elements of this array is defined by -m option. Macro knows the number of elements in MEM[] array thanks to MEMNUM integer variable. MEM[] array is an array of double numbers. When plMapcalc is started with option -r and no -m option is specified, the program calculates MEMNUM value using highest memory cell number from the file pointed by -r.
Multiple input files scanning
It is possible to scan input data multiple times in plMapcalc. A user can call RESTART() function to jump back to input the files beginning at any time. The ROW and COL variables will be set to zero and calculation of the CELL macro will start again. To find out the current iteration number, a user has to call ITERATION() function. This function returns integer value. Iterations are numbered starting from one.
Coordinates
There is a variable providing information about coordinates in projected space. The variable is GEOTRANS[]. This is an array of six double precission floating numbers and contains parameters of affine transformation from column and row space to coordintaes space. X and Y coordinates can be calculated in following way:
X_coordinate = GEOTRANS[0] + COL*GEOTRANS[1] + ROW*GEOTRANS[2]
Y_coordinate = GEOTRANS[3] + COL*GEOTRANS[4] + ROW*GEOTRANS[5]
If GEOTRANS[2] and GEOTRANS[4] are zero then input layers are oriented as a standard geographical map – north is up. Moreover, GEOTRANS[1] and GEOTRANS[5] are cell’s width and height respectively, and GEOTRANS[0] and GEOTRANS[3] are X, Y coordinates of top left corner of the layer.