1r3.mapcalc(1) Grass User's Manual r3.mapcalc(1)
2
6 r3.mapcalc - Raster map calculator.
7
9 raster, algebra
10
12 r3.mapcalc
13 r3.mapcalc --help
14 r3.mapcalc [-sl] [expression=string] [region=string] [file=name]
15 [seed=integer] [--overwrite] [--help] [--verbose] [--quiet]
16 [--ui]
17 Flags:
19 -s
20 Generate random seed (result is non-deterministic)
21 -l
23 List input and output maps
24 --overwrite
26 Allow output files to overwrite existing files
27 --help
29 Print usage summary
30 --verbose
32 Verbose module output
33 --quiet
35 Quiet module output
36 --ui
38 Force launching GUI dialog
39 Parameters:
41 expression=string
42 Expression to evaluate
43 region=string
45 The computational region that should be used.
46 - current uses the current region of the mapset.
47 - intersect computes the intersection region between
48 all input maps and uses the smallest resolution
49 - union computes the union extent of all map regions
50 and uses the smallest resolution
51 Options: current, intersect, union
52 Default: current
53 file=name
55 File containing expression(s) to evaluate
56 seed=integer
58 Seed for rand() function
59
61 r3.mapcalc performs arithmetic on raster map layers. New raster map
62 layers can be created which are arithmetic expressions involving exist‐
63 ing raster map layers, integer or floating point constants, and func‐
64 tions.
65 Program use
67 r3.mapcalc expression have the form:
68 result = expression
70 where result is the name of a raster map layer to contain the result of
72 the calculation and expression is any legal arithmetic expression
73 involving existing raster map layers (except result itself), integer or
74 floating point constants, and functions known to the calculator.
75 Parentheses are allowed in the expression and may be nested to any
76 depth. result will be created in the user’s current mapset.
77 As expression= is the first option, it is the default. This means that
79 passing an expression on the command line is possible as long as the
80 expression is quoted and a space is included before the first = sign.
81 Example (’foo’ is the resulting map):
82 r3.mapcalc "foo = 1"
83 or:
84 r3.mapcalc ’foo = 1’
85 An unquoted expression (i.e. split over multiple arguments) won’t work,
86 nor will omitting the space before the = sign:
87 r3.mapcalc ’foo=1’
88 Sorry, <foo> is not a valid parameter
89 If no options are given, it manufactures "file=-" (which reads from
90 stdin), so you can continue to use e.g.:
91 r3.mapcalc < file
92 or:
93 r3.mapcalc <<EOF
94 foo = 1
95 EOF
96 But unless you need compatibility with previous versions, use file=
97 explicitly, e.g.:
98 r3.mapcalc file=file
99 or:
100 r3.mapcalc file=- <<EOF
101 foo = 1
102 EOF
103 The formula entered to r3.mapcalc by the user is recorded both in the
105 result map title (which appears in the category file for result) and in
106 the history file for result.
107 Some characters have special meaning to the command shell. If the user
109 is entering input to r3.mapcalc on the command line, expressions should
110 be enclosed within single quotes. See NOTES, below.
111 Operators and order of precedence
113 The following operators are supported:
114 Operator Meaning Type Precedence
115 --------------------------------------------------------------
116 - negation Arithmetic 12
117 ~ one’s complement Bitwise 12
118 ! not Logical 12
119 ^ exponentiation Arithmetic 11
120 % modulus Arithmetic 10
121 / division Arithmetic 10
122 * multiplication Arithmetic 10
123 + addition Arithmetic 9
124 - subtraction Arithmetic 9
125 << left shift Bitwise 8
126 >> right shift Bitwise 8
127 >>> right shift (unsigned) Bitwise 8
128 > greater than Logical 7
129 >= greater than or equal Logical 7
130 < less than Logical 7
131 <= less than or equal Logical 7
132 == equal Logical 6
133 != not equal Logical 6
134 & bitwise and Bitwise 5
135 | bitwise or Bitwise 4
136 && logical and Logical 3
137 &&& logical and[1] Logical 3
138 || logical or Logical 2
139 ||| logical or[1] Logical 2
140 ?: conditional Logical 1
141 (modulus is the remainder upon division)
142 [1] The &&& and ||| operators handle null values differently to other
144 operators. See the section entitled NULL support below for more
145 details.
146 The operators are applied from left to right, with those of higher
148 precedence applied before those with lower precedence. Division by 0
149 and modulus by 0 are acceptable and give a NULL result. The logical
150 operators give a 1 result if the comparison is true, 0 otherwise.
151 3D Grid names
153 Anything in the expression which is not a number, operator, or function
154 name is taken to be a 3D grid name. Examples:
155 volume
157 x3
158 3d.his
159 Most GRASS raster map layers and 3D grids meet this naming convention.
161 However, if a 3D grid has a name which conflicts with the above rule,
162 it should be quoted. For example, the expression
163 x = a-b
165 would be interpreted as: x equals a minus b, whereas
167 x = "a-b"
169 would be interpreted as: x equals the 3D grid named a-b
171 Also
173 x = 3107
175 would create x filled with the number 3107, while
177 x = "3107"
179 would copy the 3D grid 3107 to the 3D grid x.
181 Quotes are not required unless the 3D grid names look like numbers or
183 contain operators, OR unless the program is run non-interactively.
184 Examples given here assume the program is run interactively. See NOTES,
185 below.
186 r3.mapcalc will look for the 3D grids according to the user’s current
188 mapset search path. It is possible to override the search path and
189 specify the mapset from which to select the 3D grid. This is done by
190 specifying the 3D grid name in the form:
191 name@mapset
193 For example, the following is a legal expression:
195 result = x@PERMANENT / y@SOILS
197 The mapset specified does not have to be in the mapset search path.
199 (This method of overriding the mapset search path is common to all
200 GRASS commands, not just r3.mapcalc.)
201 The neighborhood modifier
203 3D grids are data base files stored in voxel format, i.e., three-dimen‐
204 sional matrices of float/double values. In r3.mapcalc, 3D grids may be
205 followed by a neighborhood modifier that specifies a relative offset
206 from the current cell being evaluated. The format is map[r,c,d], where
207 r is the row offset, c is the column offset and d is the depth offset.
208 For example, map[1,2,3] refers to the cell one row below, two columns
209 to the right and 3 levels below of the current cell, map[-3,-2,-1]
210 refers to the cell three rows above, two columns to the left and one
211 level below of the current cell, and map[0,1,0] refers to the cell one
212 column to the right of the current cell. This syntax permits the devel‐
213 opment of neighborhood-type filters within a single 3D grid or across
214 multiple 3D grids.
215 Functions
217 The functions currently supported are listed in the table below. The
218 type of the result is indicated in the last column. F means that the
219 functions always results in a floating point value, I means that the
220 function gives an integer result, and * indicates that the result is
221 float if any of the arguments to the function are floating point values
222 and integer if all arguments are integer.
223 function description type
225 ---------------------------------------------------------------------------
226 abs(x) return absolute value of x *
227 acos(x) inverse cosine of x (result is in degrees) F
228 asin(x) inverse sine of x (result is in degrees) F
229 atan(x) inverse tangent of x (result is in degrees) F
230 atan(x,y) inverse tangent of y/x (result is in degrees) F
231 cos(x) cosine of x (x is in degrees) F
232 double(x) convert x to double-precision floating point F
233 eval([x,y,...,]z) evaluate values of listed expr, pass results to z
234 exp(x) exponential function of x F
235 exp(x,y) x to the power y F
236 float(x) convert x to single-precision floating point F
237 graph(x,x1,y1[x2,y2..]) convert the x to a y based on points in a graph F
238 graph2(x,x1[,x2,..],y1[,y2..])
239 alternative form of graph() F
240 if decision options: *
241 if(x) 1 if x not zero, 0 otherwise
242 if(x,a) a if x not zero, 0 otherwise
243 if(x,a,b) a if x not zero, b otherwise
244 if(x,a,b,c) a if x > 0, b if x is zero, c if x < 0
245 int(x) convert x to integer [ truncates ] I
246 isnull(x) check if x = NULL
247 log(x) natural log of x F
248 log(x,b) log of x base b F
249 max(x,y[,z...]) largest value of those listed *
250 median(x,y[,z...]) median value of those listed *
251 min(x,y[,z...]) smallest value of those listed *
252 mode(x,y[,z...]) mode value of those listed *
253 nmax(x,y[,z...]) largest value of those listed, excluding NULLs *
254 nmedian(x,y[,z...]) median value of those listed, excluding NULLs *
255 nmin(x,y[,z...]) smallest value of those listed, excluding NULLs *
256 nmode(x,y[,z...]) mode value of those listed, excluding NULLs *
257 not(x) 1 if x is zero, 0 otherwise
258 pow(x,y) x to the power y *
259 rand(a,b) random value x : a <= x < b *
260 round(x) round x to nearest integer I
261 round(x,y) round x to nearest multiple of y
262 round(x,y,z) round x to nearest y*i+z for some integer i
263 sin(x) sine of x (x is in degrees) F
264 sqrt(x) square root of x F
265 tan(x) tangent of x (x is in degrees) F
266 xor(x,y) exclusive-or (XOR) of x and y I
267 Internal variables:
268 row() current row of moving window I
269 col() current col of moving window I
270 depth() return current depth I
271 nrows() number of rows in computation region I
272 ncols() number of columns in computation region I
273 ndepths() number of depth levels in computation region I
274 x() current x-coordinate of moving window F
275 y() current y-coordinate of moving window F
276 z() return current z value F
277 ewres() current east-west resolution F
278 nsres() current north-south resolution F
279 tbres() current top-bottom resolution F
280 area() area of current cell in square meters F
281 null() NULL value
282 Note, that the row(), col() and depth() indexing starts with 1.
283 Floating point values in the expression
285 Floating point numbers are allowed in the expression. A floating point
286 number is a number which contains a decimal point:
287 2.3 12.0 12. .81
288 Floating point values in the expression are handled in a special way.
289 With arithmetic and logical operators, if either operand is float, the
290 other is converted to float and the result of the operation is float.
291 This means, in particular that division of integers results in a (trun‐
292 cated) integer, while division of floats results in an accurate float‐
293 ing point value. With functions of type * (see table above), the
294 result is float if any argument is float, integer otherwise.
295 Note: If you calculate with integer numbers, the resulting map will be
297 integer. If you want to get a float result, add the decimal point to
298 integer number(s).
299 If you want floating point division, at least one of the arguments has
301 to be a floating point value. Multiplying one of them by 1.0 will pro‐
302 duce a floating-point result, as will using float():
303 r3.mapcalc "ratio = float(soil.4 - soil.3) / soil.3)"
304 NULL support
306 · Division by zero should result in NULL.
307 · Modulus by zero should result in NULL.
309 · NULL-values in any arithmetic or logical operation should
311 result in NULL. (however, &&& and ||| are treated specially, as
312 described below).
313 · The &&& and ||| operators observe the following axioms even
315 when x is NULL:
316 x &&& false == false
317 false &&& x == false
318 x ||| true == true
319 true ||| x == true
320 · NULL-values in function arguments should result in NULL (how‐
322 ever, if(), eval() and isnull() are treated specially, as
323 described below).
324 · The eval() function always returns its last argument
326 · The situation for if() is:
328 if(x)
329 NULL if x is NULL; 0 if x is zero; 1 otherwise
330 if(x,a)
331 NULL if x is NULL; a if x is non-zero; 0 otherwise
332 if(x,a,b)
333 NULL if x is NULL; a if x is non-zero; b otherwise
334 if(x,n,z,p)
335 NULL if x is NULL; n if x is negative;
336 z if x is zero; p if x is positive
337 · The (new) function isnull(x) returns: 1 if x is NULL; 0 other‐
339 wise. The (new) function null() (which has no arguments)
340 returns an integer NULL.
341 · Non-NULL, but invalid, arguments to functions should result in
343 NULL.
344 Examples:
345 log(-2)
346 sqrt(-2)
347 pow(a,b) where a is negative and b is not an integer
348 NULL support: Please note that any math performed with NULL cells
350 always results in a NULL value for these cells. If you want to replace
351 a NULL cell on-the-fly, use the isnull() test function in a if-state‐
352 ment.
353 Example: The users wants the NULL-valued cells to be treated like
355 zeros. To add maps A and B (where B contains NULLs) to get a map C the
356 user can use a construction like:
357 C = A + if(isnull(B),0,B)
359 NULL and conditions:
361 For the one argument form:
363 if(x) = NULL if x is NULL
364 if(x) = 0 if x = 0
365 if(x) = 1 otherwise (i.e. x is neither NULL nor 0).
366 For the two argument form:
368 if(x,a) = NULL if x is NULL
369 if(x,a) = 0 if x = 0
370 if(x,a) = a otherwise (i.e. x is neither NULL nor 0).
371 For the three argument form:
373 if(x,a,b) = NULL if x is NULL
374 if(x,a,b) = b if x = 0
375 if(x,a,b) = a otherwise (i.e. x is neither NULL nor 0).
376 For the four argument form:
378 if(x,a,b,c) = NULL if x is NULL
379 if(x,a,b,c) = a if x > 0
380 if(x,a,b,c) = b if x = 0
381 if(x,a,b,c) = c if x < 0
382 More generally, all operators and most functions return NULL if *any*
383 of their arguments are NULL.
384 The functions if(), isnull() and eval() are exceptions.
385 The function isnull() returns 1 if its argument is NULL and 0 other‐
386 wise. If the user wants the opposite, the ! operator, e.g.
387 "!isnull(x)" must be used.
388 All forms of if() return NULL if the first argument is NULL. The 2, 3
390 and 4 argument forms of if() return NULL if the "selected" argument is
391 NULL, e.g.:
392 if(0,a,b) = b regardless of whether a is NULL
393 if(1,a,b) = a regardless of whether b is NULL
394 eval() always returns its last argument, so it only returns NULL if the
395 last argument is NULL.
396 Note: The user cannot test for NULL using the == operator, as that
398 returns NULL if either or both arguments are NULL, i.e. if x and y are
399 both NULL, then "x == y" and "x != y" are both NULL rather than 1 and 0
400 respectively.
401 The behaviour makes sense if the user considers NULL as representing an
402 unknown quantity. E.g. if x and y are both unknown, then the values of
403 "x == y" and "x != y" are also unknown; if they both have unknown val‐
404 ues, the user doesn’t know whether or not they both have the same
405 value.
406
408 Usage from command line
409 Extra care must be taken if the expression is given on the command
410 line. Some characters have special meaning to the UNIX shell. These
411 include, among others:
412 * ( ) > & |
413 It is advisable to put single quotes around the expression; e.g.:
415 ’result = volume * 2’
416 Without the quotes, the *, which has special meaning to the UNIX shell,
417 would be altered and r3.mapcalc would see something other than the *.
418 Multiple computations
420 In general, it’s preferable to do as much as possible in each r3.map‐
421 calc command using multi-line input.
422 Backwards compatibility
424 For the backwards compatibility with GRASS 6, if no options are given,
425 it manufactures file=- (which reads from stdin), so you can continue to
426 use e.g.:
427 r3.mapcalc < file
428 or:
429 r3.mapcalc <<EOF
430 foo = 1
431 EOF
432 But unless you need compatibility with previous GRASS GIS versions, use
433 file= explicitly, as stated above.
434 When the map name contains uppercase letter(s) or a dot which are not
436 allowed to be in module option names, the r3.mapcalc command will be
437 valid also without quotes:
438 r3.mapcalc volume_A=1
439 r3.mapcalc volume.1=1
440 However, this syntax is not recommended as quotes as stated above more
441 safe. Using quotes is both backwards compatible and valid in future.
442 Interactive input in command line
444 For formulas that the user enters from standard input (rather than from
445 the command line), a line continuation feature now exists. If the user
446 adds a backslash to the end of an input line, r3.mapcalc assumes that
447 the formula being entered by the user continues on to the next input
448 line. There is no limit to the possible number of input lines or to
449 the length of a formula.
450 If the r3.mapcalc formula entered by the user is very long, the map
452 title will contain only some of it, but most (if not all) of the for‐
453 mula will be placed into the history file for the result map.
454 When the user enters input to r3.mapcalc non-interactively on the com‐
456 mand line, the program will not warn the user not to overwrite existing
457 map layers. Users should therefore take care to assign program outputs
458 raster map names that do not yet exist in their current mapsets.
459 3D GRID MASK handling
461 r3.mapcalc follows the common GRASS behavior of raster MASK handling,
462 so the MASK is only applied when reading an existing GRASS raster map.
463 This implies that, for example, the command:
464 r3.mapcalc "volume_amplified = volume * 3"
465 create a map respecting the masked pixels if MASK is active.
466 However, when creating a map which is not based on any map, e.g. a map
468 from a constant:
469 r3.mapcalc "volume_const = 200.0"
470 the created raster map is limited only by a computation region but it
471 is not affected by an active MASK. This is expected because, as men‐
472 tioned above, MASK is only applied when reading, not when writing a
473 raster map.
474 If also in this case the MASK should be applied, an if() statement
476 including the MASK should be used, e.g.:
477 r3.mapcalc "volume_const = if(MASK, 200.0, null())"
478 When testing MASK related expressions keep in mind that when MASK is
479 active you don’t see data in masked areas even if they are not NULL.
480 See r.mask for details.
481 Random number generator initialization
483 The pseudo-random number generator used by the rand() function can be
484 initialised to a specific value using the seed option. This can be
485 used to replicate a previous calculation.
486 Alternatively, it can be initialised from the system time and the PID
488 using the -r flag. This should result in a different seed being used
489 each time.
490 In either case, the seed will be written to the map’s history, and can
492 be seen using r.info.
493 If you want other people to be able to verify your results, it’s
495 preferable to use the seed option to supply a seed which is either
496 specified in the script or generated from a determenistic process such
497 as a pseudo-random number generator given an explicit seed.
498 Note that the rand() function will generate a fatal error if neither
500 the seed option nor the -s flag are given.
501
503 To compute the average of two 3D grids a and b:
504 ave = (a + b)/2
505 To form a weighted average:
506 ave = (5*a + 3*b)/8.0
507 To produce a binary representation of 3D grid a so that category 0
508 remains 0 and all other categories become 1:
509 mask = a != 0
510 This could also be accomplished by:
511 mask = if(a)
512 To mask 3D grid b by 3D grid a:
513 result = if(a,b)
514 To change all values below 5 to NULL, keep otherwise:
515 newmap = if(map < 5, null(), map)
516 The graph() function allows users to specify a x-y conversion using
517 pairs of x,y coordinates. In some situations a transformation from one
518 value to another is not easily established mathematically, but can be
519 represented by a 2-D graph and then linearly interpolated. The graph()
520 function provides the opportunity to accomplish this. An x-axis value
521 is provided to the graph function along with the associated graph rep‐
522 resented by a series of x,y pairs. The x values must be monotonically
523 increasing (each larger than or equal to the previous). The graph
524 function linearly interpolates between pairs. Any x value lower the
525 lowest x value (i.e. first) will have the associated y value returned.
526 Any x value higher than the last will similarly have the associated y
527 value returned. Consider the request:
528 newmap = graph(map, 1,10, 2,25, 3,50)
529 X (map) values supplied and y (newmap) values returned:
530 0, 10
531 1, 10
532 1.5, 17.5
533 2.9, 47.5
534 4, 50
535 100, 50
536
538 The result variable on the left hand side of the equation should not
539 appear in the expression on the right hand side.
540 mymap = if( mymap > 0, mymap, 0)
541 Any maps generated by a r3.mapcalc command only exist after the entire
543 command has completed. All maps are generated concurrently, row-by-row
544 (i.e. there is an implicit "for row in rows {...}" around the entire
545 expression). Thus the #, @, and [ ] operators cannot be used on a map
546 generated within same r3.mapcalc command run.
547 newmap = oldmap * 3.14
548 othermap = newmap[-1, 0] / newmap[1, 0]
549 Continuation lines must end with a \ and have no trailing white space
551 (blanks or tabs). If the user does leave white space at the end of con‐
552 tinuation lines, the error messages produced by r3.mapcalc will be
553 meaningless and the equation will not work as the user intended. This
554 is particularly important for the eval() function.
555 Currently, there is no comment mechanism in r3.mapcalc. Perhaps adding
557 a capability that would cause the entire line to be ignored when the
558 user inserted a # at the start of a line as if it were not present,
559 would do the trick.
560 The function should require the user to type "end" or "exit" instead of
562 simply a blank line. This would make separation of multiple scripts
563 separable by white space.
564 r3.mapcalc does not print a warning in case of operations on NULL
566 cells. It is left to the user to utilize the isnull() function.
567
569 g.region, r3.colors, r.mapcalc
570
572 r.mapcalc: An Algebra for GIS and Image Processing, by Michael Shapiro
573 and Jim Westervelt, U.S. Army Construction Engineering Research Labora‐
574 tory (March/1991).
575 Performing Map Calculations on GRASS Data: r.mapcalc Program Tutorial,
577 by Marji Larson, Michael Shapiro and Scott Tweddale, U.S. Army Con‐
578 struction Engineering Research Laboratory (December 1991)
579 Neteler, M. (2001): Volume modelling of soils using GRASS GIS 3D tools.
581 - in: Brovelli, M. (ed.)(2001): The Geomatics Workbook N. 2. Politec‐
582 nico di Milano, Italy (ISSN 1591-092X) (PDF)
583
585 Tomas Paudits & Jaro Hofierka, funded by GeoModel s.r.o., Slovakia
586 tpaudits@mailbox.sk, hofierka@geomodel.sk
587 Glynn Clements
589 Last changed: $Date: 2016-12-01 14:20:05 +0100 (Thu, 01 Dec 2016) $
591
593 Available at: r3.mapcalc source code (history)
594 Main index | 3D raster index | Topics index | Keywords index | Graphi‐
596 cal index | Full index
597 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
599GRASS 7.4.4 r3.mapcalc(1)