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