1r3.mapcalc(1) Grass User's Manual r3.mapcalc(1)
2
6 r3.mapcalc
7
9 r3.mapcalc performs arithmetic on 3D grid volume data. New 3D grids can
10 be created which are arithmetic expressions involving existing 3D
11 grids, integer or floating point constants, and functions.
12
14 If used without command line arguments, r3.mapcalc will read its input,
15 one line at a time, from standard input (which is the keyboard, unless
16 redirected from a file or across a pipe). Otherwise, the expression on
17 the command line is evaluated. r3.mapcalc expects its input to have the
18 form:
19 result=expression
21 where result is the name of a 3D grid to contain the result of the cal‐
23 culation and expression is any legal arithmetic expression involving
24 existing 3D grid, floating point constants, and functions known to the
25 calculator. Parentheses are allowed in the expression and may be nested
26 to any depth. result will be created in the user's current mapset.
27 The formula entered to r3.mapcalc by the user is recorded both in the
29 result grid title (which appears in the category file for result) and
30 in the history file for result.
31 Some characters have special meaning to the command shell. If the user
33 is entering input to r.mapcalc on the command line, expressions should
34 be enclosed within single quotes. See NOTES, below.
35
37 The following operators are supported:
38 Operator Meaning Type Precedence
39 --------------------------------------------------------------
40 - negation Arithmetic 12
41 ~ one's complement Bitwise 12
42 ! not Logical 12
43 ^ exponentiation Arithmetic 11
44 % modulus Arithmetic 10
45 / division Arithmetic 10
46 * multiplication Arithmetic 10
47 + addition Arithmetic 9
48 - subtraction Arithmetic 9
49 << left shift Bitwise 8
50 >> right shift Bitwise 8
51 >>> right shift (unsigned) Bitwise 8
52 > greater than Logical 7
53 >= greater than or equal Logical 7
54 < less than Logical 7
55 <= less than or equal Logical 7
56 == equal Logical 6
57 != not equal Logical 6
58 & bitwise and Bitwise 5
59 | bitwise or Bitwise 4
60 && logical and Logical 3
61 &&& logical and[1] Logical 3
62 || logical or Logical 2
63 ||| logical or[1] Logical 2
64 ?: conditional Logical 1
65 (modulus is the remainder upon division)
66 [1] The &&& and ||| operators handle null values differently to
68 other operators. See the section entitled NULL support below for more
69 details.
70 The operators are applied from left to right, with those of higher
72 precedence applied before those with lower precedence. Division by 0
73 and modulus by 0 are acceptable and give a NULL result. The logical
74 operators give a 1 result if the comparison is true, 0 otherwise.
75
77 Anything in the expression which is not a number, operator, or function
78 name is taken to be a 3D grid name. Examples:
79 volume
82 x3
83 3d.his
84 Most GRASS raster map layers and 3D grids meet this naming convention.
87 However, if a 3D grid has a name which conflicts with the above rule,
88 it should be quoted. For example, the expression
89 x = a-b
92 would be interpreted as: x equals a minus b, whereas
95 x = "a-b"
98 would be interpreted as: x equals the 3D grid named a-b
101 Also
103 x = 3107
106 would create x filled with the number 3107, while
109 x = "3107"
112 would copy the 3D grid 3107 to the 3D grid x.
115 Quotes are not required unless the 3D grid names look like numbers or
117 contain operators, OR unless the program is run non-interactively.
118 Examples given here assume the program is run interactively. See NOTES,
119 below.
120 r3.mapcalc will look for the 3D grids according to the user's current
122 mapset search path. It is possible to override the search path and
123 specify the mapset from which to select the 3D grid. This is done by
124 specifying the 3D grid name in the form:
125 name@mapset
128 For example, the following is a legal expression:
131 result = x@PERMANENT / y@SOILS
134 The mapset specified does not have to be in the mapset search path.
137 (This method of overriding the mapset search path is common to all
138 GRASS commands, not just r3.mapcalc.)
139
141 3D grids are data base files stored in voxel format, i.e., three-dimen‐
142 sional matrices of float/double values. In r3.mapcalc, 3D grids may be
143 followed by a neighborhood modifier that specifies a relative offset
144 from the current cell being evaluated. The format is map[r,c,d], where
145 r is the row offset, c is the column offset and d is the depth offset.
146 For example, map[1,2,3] refers to the cell one row below, two columns
147 to the right and 3 levels below of the current cell, map[-3,-2,-1]
148 refers to the cell three rows above, two columns to the left and one
149 level below of the current cell, and map[0,1,0] refers to the cell one
150 column to the right of the current cell. This syntax permits the devel‐
151 opment of neighborhood-type filters within a single 3D grid or across
152 multiple 3D grids.
153
155 The functions currently supported are listed in the table below. The
156 type of the result is indicated in the last column. F means that the
157 functions always results in a floating point value, I means that the
158 function gives an integer result, and * indicates that the result is
159 float if any of the arguments to the function are floating point values
160 and integer if all arguments are integer.
161 function description type
164 ---------------------------------------------------------------------------
165 abs(x) return absolute value of x *
166 acos(x) inverse cosine of x (result is in degrees) F
167 asin(x) inverse sine of x (result is in degrees) F
168 atan(x) inverse tangent of x (result is in degrees) F
169 atan(x,y) inverse tangent of y/x (result is in degrees) F
170 cos(x) cosine of x (x is in degrees) F
171 double(x) convert x to double-precision floating point F
172 eval([x,y,...,]z) evaluate values of listed expr, pass results to z
173 exp(x) exponential function of x F
174 exp(x,y) x to the power y F
175 float(x) convert x to single-precision floating point F
176 graph(x,x1,y1[x2,y2..]) convert the x to a y based on points in a
177 graph F
178 if decision options: *
179 if(x) 1 if x not zero, 0 otherwise
180 if(x,a) a if x not zero, 0 otherwise
181 if(x,a,b) a if x not zero, b otherwise
182 if(x,a,b,c) a if x > 0, b if x is zero, c if x < 0
183 int(x) convert x to integer [ truncates ] I
184 isnull(x) check if x = NULL
185 log(x) natural log of x F
186 log(x,b) log of x base b F
187 max(x,y[,z...]) largest value of those listed *
188 median(x,y[,z...]) median value of those listed *
189 min(x,y[,z...]) smallest value of those listed *
190 mode(x,y[,z...]) mode value of those listed
191 *
192 not(x) 1 if x is zero, 0 otherwise
193 pow(x,y) x to the power y *
194 rand(a,b) random value x : a <= x < b
195 round(x) round x to nearest integer I
196 sin(x) sine of x (x is in degrees) F
197 sqrt(x) square root of x F
198 tan(x) tangent of x (x is in degrees) F
199 xor(x,y) exclusive-or (XOR) of x and y I
200 Internal variables:
202 row() current row of moving window
203 col() current col of moving window
204 depth() return current depth
205 x() current x-coordinate of moving window
206 y() current y-coordinate of moving window
207 z() return current z value
208 ewres() current east-west resolution
209 nsres() current north-south resolution
210 tbres() current top-bottom resolution
211 null() NULL value
212 Note, that the row(), col() and depth() indexing starts with 1.
213
215 Floating point numbers are allowed in the expression. A floating point
216 number is a number which contains a decimal point:
217 2.3 12.0 12. .81
218 Floating point values in the expression are handled in a special way.
219 With arithmetic and logical operators, if either operand is float, the
220 other is converted to float and the result of the operation is float.
221 This means, in particular that division of integers results in a (trun‐
222 cated) integer, while division of floats results in an accurate float‐
223 ing point value. With functions of type * (see table above), the
224 result is float if any argument is float, integer otherwise.
225 Note: If you calculate with integer numbers, the resulting map will be
227 integer. If you want to get a float result, add the decimal point to
228 integer number(s).
229 If you want floating point division, at least one of the arguments has
231 to be a floating point value. Multiplying one of them by 1.0 will pro‐
232 duce a floating-point result, as will using float():
233 r.mapcalc "ndvi=float(lsat.4 - lsat.3) / (lsat.4 + lsat.3)"
234
237 Division by zero should result in NULL. Modulus by zero should result
238 in NULL. NULL-values in any arithmetic or logical operation should
239 result in NULL. (however, &&& and ||| are treated specially, as
240 described below). The &&& and ||| operators observe the following
241 axioms even when x is NULL:
242 x &&& false == false
243 false &&& x == false
244 x ||| true == true
245 true ||| x == true
246 NULL-values in function arguments should result in NULL (however,
247 if(), eval() and isnull() are treated specially, as described below).
248 The eval() function always returns its last argument The situation for
249 if() is:
250 if(x)
251 NULL if x is NULL; 0 if x is zero; 1 otherwise
252 if(x,a)
253 NULL if x is NULL; a if x is non-zero; 0 otherwise
254 if(x,a,b)
255 NULL if x is NULL; a if x is non-zero; b otherwise
256 if(x,n,z,p)
257 NULL if x is NULL; n if x is negative;
258 z if x is zero; p if x is positive
259 The (new) function isnull(x) returns: 1 if x is NULL; 0 otherwise. The
260 (new) function null() (which has no arguments) returns an integer NULL.
261 Non-NULL, but invalid, arguments to functions should result in NULL.
262 Examples:
263 log(-2)
264 sqrt(-2)
265 pow(a,b) where a is negative and b is not an integer
266 NULL support: Please note that any math performed with NULL cells
269 always results in a NULL value for these cells. If you want to replace
270 a NULL cell on-the-fly, use the isnull() test function in a if-state‐
271 ment.
272 Example: The users wants the NULL-valued cells to be treated like
274 zeros. To add maps A and B (where B contains NULLs) to get a map C the
275 user can use a construction like:
276 C=A + if(isnull(B),0,B)
279 NULL and conditions:
282 For the one argument form:
284 if(x) = NULL if x is NULL
285 if(x) = 0 if x = 0
286 if(x) = 1 otherwise (i.e. x is neither NULL nor 0).
287 For the two argument form:
290 if(x,a) = NULL if x is NULL
291 if(x,a) = 0 if x = 0
292 if(x,a) = a otherwise (i.e. x is neither NULL nor 0).
293 For the three argument form:
296 if(x,a,b) = NULL if x is NULL
297 if(x,a,b) = b if x = 0
298 if(x,a,b) = a otherwise (i.e. x is neither NULL nor 0).
299 For the four argument form:
302 if(x,a,b,c) = NULL if x is NULL
303 if(x,a,b,c) = a if x > 0
304 if(x,a,b,c) = b if x = 0
305 if(x,a,b,c) = c if x < 0
306 More generally, all operators and most functions return NULL if *any*
307 of their arguments are NULL.
308 The functions if(), isnull() and eval() are exceptions.
309 The function isnull() returns 1 if its argument is NULL and 0 other‐
310 wise. If the user wants the opposite, the ! operator, e.g.
311 "!isnull(x)" must be used.
312 All forms of if() return NULL if the first argument is NULL. The 2, 3
314 and 4 argument forms of if() return NULL if the "selected" argument is
315 NULL, e.g.:
316 if(0,a,b) = b regardless of whether a is NULL
317 if(1,a,b) = a regardless of whether b is NULL
318 eval() always returns its last argument, so it only returns NULL if
319 the last argument is NULL.
320 Note: The user cannot test for NULL using the == operator, as that
322 returns NULL if either or both arguments are NULL, i.e. if x and y are
323 both NULL, then "x == y" and "x != y" are both NULL rather than 1 and 0
324 respectively.
325 The behaviour makes sense if the user considers NULL as representing an
326 unknown quantity. E.g. if x and y are both unknown, then the values of
327 "x == y" and "x != y" are also unknown; if they both have unknown val‐
328 ues, the user doesn't know whether or not they both have the same
329 value.
330
332 To compute the average of two 3D grids a and b:
333 ave = (a + b)/2
334 To form a weighted average:
335 ave = (5*a + 3*b)/8.0
336 To produce a binary representation of 3D grid a so that category 0
337 remains 0 and all other categories become 1:
338 mask = a != 0
339 This could also be accomplished by:
340 mask = if(a)
341 To mask 3D grid b by 3D grid a:
342 result = if(a,b)
343 To change all values below 5 to NULL:
344 newmap = if(map<5, null(), 5)
345 The graph function allows users to specify a x-y conversion using
346 pairs of x,y coordinates. In some situations a transformation from one
347 value to another is not easily established mathematically, but can be
348 represented by a 2-D graph. The graph() function provides the opportu‐
349 nity to accomplish this. An x-axis value is provided to the graph
350 function along with the associated graph represented by a series of x,y
351 pairs. The x values must be monotonically increasing (each larger than
352 or equal to the previous). The graph function linearly interpolates
353 between pairs. Any x value lower the lowest x value (i.e. first) will
354 have the associated y value returned. Any x value higher than the last
355 will similarly have the associated y value returned. Consider the
356 request:
357 newmap = graph(map, 1,10, 2,25, 3,50)
358 X (map) values supplied and y (newmap) values returned:
359 0, 10
360 1, 10,
361 1.5, 16.5
362 2.9, 47.5
363 4, 50
364 100, 50
365
368 Extra care must be taken if the expression is given on the command
369 line. Some characters have special meaning to the UNIX shell. These
370 include, among others:
371 * ( ) > & |
373 It is advisable to put single quotes around the expression; e.g.:
375 result = 'elevation * 2'
376 Without the quotes, the *, which has special meaning to the UNIX
377 shell, would be altered and r3.mapcalc would see something other than
378 the *.
379 If the input comes directly from the keyboard and the result 3D grid
381 exists, the user will be asked if it can be overwritten. Otherwise, the
382 result 3D grid will automatically be overwritten if it exists.
383 Quoting result is not allowed. However, it is never necessary to quote
385 result since it is always taken to be a 3D grid name.
386 For formulas that the user enters from standard input (rather than from
388 the command line), a line continuation feature now exists. If the user
389 adds \e to the end of an input line, r3.mapcalc assumes that the for‐
390 mula being entered by the user continues on to the next input line.
391 There is no limit to the possible number of input lines or to the
392 length of a formula.
393 If the r3.mapcalc formula entered by the user is very long, the map
395 title will contain only some of it, but most (if not all) of the for‐
396 mula will be placed into the history file for the result map.
397 When the user enters input to r3.mapcalc non-interactively on the com‐
399 mand line, the program will not warn the user not to overwrite existing
400 3D grids. Users should therefore take care to assign program outputs 3D
401 grid file names that do not yet exist in their current mapsets.
402 The environment variable GRASS_RND_SEED is read to initialise the ran‐
404 dom number generator.
405
407 Continuation lines must end with a \ and have NO trailing white space
408 (blanks or tabs). If the user does leave white space at the end of
409 continuation lines, the error messages produced by r.mapcalc will be
410 meaningless and the equation will not work as the user intended. This
411 is important for the eval() function.
412 Error messages produced by r.mapcalc are almost useless. In future,
414 r.mapcalc should make some attempt to point the user to the offending
415 section of the equation, e.g.:
416 x = a * b ++ c
417 ERROR: somewhere in line 1: ... b ++ c ...
418 Currently, there is no comment mechanism in r3.mapcalc. Perhaps adding
421 a capability that would cause the entire line to be ignored when the
422 user inserted a # at the start of a line as if it were not present,
423 would do the trick.
424 The function should require the user to type "end" or "exit" instead of
426 simply a blank line. This would make separation of multiple scripts
427 separable by white space.
428 r.mapcalc does not print a warning in case of operations on NULL cells.
430 It is left to the user to utilize the isnull() function.
431
433 r.mapcalc: An Algebra for GIS and Image Processing, by Michael Shapiro
434 and Jim Westervelt, U.S. Army Construction Engineering Research Labora‐
435 tory (March/1991).
436 Performing Map Calculations on GRASS Data: r.mapcalc Program Tutorial,
438 by Marji Larson, Michael Shapiro and Scott Tweddale, U.S. Army Con‐
439 struction Engineering Research Laboratory (December 1991)
440 r.mapcalc
442
444 Tomas Paudits & Jaro Hofierka, funded by GeoModel s.r.o., Slovakia
445 tpaudits@mailbox.sk, hofierka@geomodel.sk
446 Last changed: $Date: 2007-08-24 06:13:51 +0200 (Fri, 24 Aug 2007) $
448GRASS 6.3.0 r3.mapcalc(1)