1r.mapcalc(1)                  Grass User's Manual                 r.mapcalc(1)
2
3
4

NAME

6       r.mapcalc  - Raster map calculator.
7

KEYWORDS

9       raster, algebra
10

SYNOPSIS

12       r.mapcalc
13       r.mapcalc --help
14       r.mapcalc  [-sl]   [expression=string]    [region=string]   [file=name]
15       [seed=integer]    [--overwrite]    [--help]    [--verbose]    [--quiet]
16       [--ui]
17
18   Flags:
19       -s
20           Generate random seed (result is non-deterministic)
21
22       -l
23           List input and output maps
24
25       --overwrite
26           Allow output files to overwrite existing files
27
28       --help
29           Print usage summary
30
31       --verbose
32           Verbose module output
33
34       --quiet
35           Quiet module output
36
37       --ui
38           Force launching GUI dialog
39
40   Parameters:
41       expression=string
42           Expression to evaluate
43
44       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
54       file=name
55           File containing expression(s) to evaluate
56
57       seed=integer
58           Seed for rand() function
59

DESCRIPTION

61       r.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
66   Program use
67       r.mapcalc expression have the form:
68
69       result = expression
70
71       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
78       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       r.mapcalc "foo = 1"
83       or:
84       r.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       r.mapcalc ’foo=1’
88       Sorry, <foo> is not a valid parameter
89       To read command from the file, use file= explicitly, e.g.:
90       r.mapcalc file=file
91       or:
92       r.mapcalc file=- < file
93       or:
94       r.mapcalc file=- <<EOF
95       foo = 1
96       EOF
97
98       The  formula  entered  to r.mapcalc by the user is recorded both in the
99       result map title (which appears in the category file for result) and in
100       the history file for result.
101
102       Some  characters have special meaning to the command shell. If the user
103       is entering input to r.mapcalc on the command line, expressions  should
104       be enclosed within single quotes. See NOTES, below.
105
106   Computational regions in r.mapcalc
107       By  default  r.mapcalc  uses the current region as computational region
108       that was set with g.region for processing.  Sometimes it  is  necessary
109       to  use a region that is derived from the raster maps in the expression
110       to set the computational region.  This is of high importance  for  mod‐
111       ules  that use r.mapcalc internally to process time series of satellite
112       images that all have different spatial extents. A module that  requires
113       this  feature  is  t.rast.algebra.   The region option of r.mapcalc was
114       implemented to address this requirement.  It allows computing and using
115       a  region  based  on  all raster maps in an expression. Three modes are
116       supported:
117
118           ·   Setting the region parameter to current will result in the  use
119               of  the  current  region  as  computational region. This is the
120               default.  The current region can be set with g.region.
121
122           ·   The parameter union will force r.mapcalc to  compute  the  dis‐
123               joint  union  of  all regions from raster maps specified in the
124               expression. This computed region will then be used as  computa‐
125               tional region at runtime.  The region of the mapset will not be
126               modified.  The smallest spatial resolution of all  raster  maps
127               will be used for processing.
128
129           ·   The  parameter  intersect  will  force r.mapcalc to compute the
130               intersection of all regions from raster maps specified  in  the
131               expression.  This computed region will then be used as computa‐
132               tional region at runtime.  The region of the mapset will not be
133               modified.   The  smallest spatial resolution of all raster maps
134               will be used for processing.
135
136   Operators and order of precedence
137       The following operators are supported:
138            Operator   Meaning                    Type        Precedence
139            --------------------------------------------------------------
140            -          negation                   Arithmetic  12
141            ~          one’s complement           Bitwise     12
142            !          not                        Logical     12
143            ^          exponentiation             Arithmetic  11
144            %          modulus                    Arithmetic  10
145            /          division                   Arithmetic  10
146            *          multiplication             Arithmetic  10
147            +          addition                   Arithmetic   9
148            -          subtraction                Arithmetic   9
149            <<         left shift                 Bitwise      8
150            >>         right shift                Bitwise      8
151            >>>        right shift (unsigned)     Bitwise      8
152            >          greater than               Logical      7
153            >=         greater than or equal      Logical      7
154            <          less than                  Logical      7
155            <=         less than or equal         Logical      7
156            ==         equal                      Logical      6
157            !=         not equal                  Logical      6
158            &          bitwise and                Bitwise      5
159            |          bitwise or                 Bitwise      4
160            &&         logical and                Logical      3
161            &&&        logical and[1]             Logical      3
162            ||         logical or                 Logical      2
163            |||        logical or[1]              Logical      2
164            ?:         conditional                Logical      1
165       (modulus is the remainder upon division)
166
167       [1] The &&& and ||| operators handle null values differently  to  other
168       operators.  See  the  section  entitled  NULL  support  below  for more
169       details.
170
171       The operators are applied from left to  right,  with  those  of  higher
172       precedence  applied  before those with lower precedence.  Division by 0
173       and modulus by 0 are acceptable and give a NULL  result.   The  logical
174       operators give a 1 result if the comparison is true, 0 otherwise.
175
176   Raster map layer names
177       Anything in the expression which is not a number, operator, or function
178       name is taken to be a raster map layer name.  Examples:
179
180       elevation
181       x3
182       3d.his
183
184       Most GRASS raster map layers meet this naming convention.  However,  if
185       a  raster  map layer has a name which conflicts with the above rule, it
186       should be quoted.  For example, the expression
187
188       x = a-b
189
190       would be interpreted as:  x equals a minus b, whereas
191
192       x = "a-b"
193
194       would be interpreted as:  x equals the raster map layer named a-b
195
196       Also
197
198       x = 3107
199
200       would create x filled with the number 3107, while
201
202       x = "3107"
203
204       would copy the raster map layer 3107 to the raster map layer x.
205
206       Quotes are not required unless the raster map  layer  names  look  like
207       numbers or contain operators, OR unless the program is run non-interac‐
208       tively.  Examples given here assume the program is  run  interactively.
209       See NOTES, below.
210
211       r.mapcalc  will  look for the raster map layers according to the user’s
212       current mapset search path.  It is possible to override the search path
213       and specify the mapset from which to select the raster map layer.  This
214       is done by specifying the raster map layer name in the form:
215
216       name@mapset
217
218       For example, the following is a legal expression:
219
220       result = x@PERMANENT / y@SOILS
221
222       The mapset specified does not have to be in  the  mapset  search  path.
223       (This  method  of  overriding  the  mapset search path is common to all
224       GRASS commands, not just r.mapcalc.)
225
226   The neighborhood modifier
227       Maps and images are data base files  stored  in  raster  format,  i.e.,
228       two-dimensional  matrices of integer values.  In r.mapcalc, maps may be
229       followed by a neighborhood modifier that specifies  a  relative  offset
230       from the current cell being evaluated.  The format is map[r,c], where r
231       is the row offset and c is the column offset.   For  example,  map[1,2]
232       refers  to  the  cell one row below and two columns to the right of the
233       current cell, map[-2,-1] refers to the cell two rows above and one col‐
234       umn  to  the  left of the current cell, and map[0,1] refers to the cell
235       one column to the right of the current cell.  This syntax  permits  the
236       development  of neighborhood-type filters within a single map or across
237       multiple maps.
238
239   Raster map layer values from the category file
240       Sometimes it is desirable to use a value associated with  a  category’s
241       label instead of the category value itself.  If a raster map layer name
242       is preceded by the @ operator, then the labels in the category file for
243       the raster map layer are used in the expression instead of the category
244       value.
245
246       For example, suppose that the raster map  layer  soil.ph  (representing
247       soil pH values) has a category file with labels as follows:
248
249       cat     label
250       ------------------
251       0       no data
252       1       1.4
253       2       2.4
254       3       3.5
255       4       5.8
256       5       7.2
257       6       8.8
258       7       9.4
259
260       Then the expression:
261
262       result = @soils.ph
263
264       would produce a result with category values 0, 1.4, 2.4, 3.5, 5.8, 7.2,
265       8.8 and 9.4.
266
267       Note that this operator may only be applied to raster  map  layers  and
268       produces a floating point value in the expression.  Therefore, the cat‐
269       egory label must start with a valid number.  If the category  label  is
270       integer, it will be represented by a floating point number. I the cate‐
271       gory label does not start with a number or is missing, it will be  rep‐
272       resented by NULL (no data) in the resulting raster map.
273
274   Grey scale equivalents and color separates
275       It  is  often  helpful  to  manipulate the colors assigned to map cate‐
276       gories.  This is particularly useful when the  spectral  properties  of
277       cells  have  meaning  (as  with imagery data), or when the map category
278       values represent real quantities (as when category values reflect  true
279       elevation values).  Map color manipulation can also aid visual recogni‐
280       tion, and map printing.
281
282       The # operator can be used to either convert  map  category  values  to
283       their grey scale equivalents or to extract the red, green, or blue com‐
284       ponents of a raster map layer into separate raster map layers.
285
286       result = #map
287
288       converts each category value in map to a value in the range 0-255 which
289       represents  the grey scale level implied by the color for the category.
290       If the map has a grey scale color table, then the grey  level  is  what
291       #map evaluates to.  Otherwise, it is computed as:
292
293        0.10 * red + 0.81 * green + 0.01 * blue
294
295       Alternatively, you can use:
296
297       result = y#map
298
299       to use the NTSC weightings:
300
301        0.30 * red + 0.59 * green + 0.11 * blue
302
303       Or, you can use:
304
305       result = i#map
306
307       to use equal weightings:
308
309        0.33 * red + 0.33 * green + 0.33 * blue
310
311       The  #  operator  has  three  other forms:  r#map, g#map, b#map.  These
312       extract the red, green, or blue components in  the  named  raster  map,
313       respectively.   The  GRASS  shell script r.blend extracts each of these
314       components  from  two  raster  map  layers,  and  combines  them  by  a
315       user-specified  percentage.   These  forms  allow color separates to be
316       made.  For example, to extract the red component from map and store  it
317       in the new 0-255 map layer red, the user could type:
318
319       red = r#map
320
321       To assign this map grey colors type:
322
323       r.colors map=red color=rules
324       black
325       white
326
327       To assign this map red colors type:
328
329       r.colors map=red color=rules
330       black
331       red
332
333   Functions
334       The  functions  currently supported are listed in the table below.  The
335       type of the result is indicated in the last column.  F means  that  the
336       functions  always  results  in a floating point value, I means that the
337       function gives an integer result, and * indicates that  the  result  is
338       float if any of the arguments to the function are floating point values
339       and integer if all arguments are integer.
340
341       function                description                                     type
342       ---------------------------------------------------------------------------
343       abs(x)                  return absolute value of x                      *
344       acos(x)                 inverse cosine of x (result is in degrees)      F
345       asin(x)                 inverse sine of x (result is in degrees)        F
346       atan(x)                 inverse tangent of x (result is in degrees)     F
347       atan(x,y)               inverse tangent of y/x (result is in degrees)   F
348       ceil(x)                 the smallest integral value not less than x     *
349       cos(x)                  cosine of x (x is in degrees)                   F
350       double(x)               convert x to double-precision floating point    F
351       eval([x,y,...,]z)       evaluate values of listed expr, pass results to z
352       exp(x)                  exponential function of x                       F
353       exp(x,y)                x to the power y                                F
354       float(x)                convert x to single-precision floating point    F
355       floor(x)                the largest integral value not greater than x   *
356       graph(x,x1,y1[x2,y2..]) convert the x to a y based on points in a graph F
357       graph2(x,x1[,x2,..],y1[,y2..])
358                               alternative form of graph()                     F
359       if                      decision options:                               *
360       if(x)                   1 if x not zero, 0 otherwise
361       if(x,a)                 a if x not zero, 0 otherwise
362       if(x,a,b)               a if x not zero, b otherwise
363       if(x,a,b,c)             a if x > 0, b if x is zero, c if x < 0
364       int(x)                  convert x to integer [ truncates ]              I
365       isnull(x)               check if x = NULL
366       log(x)                  natural log of x                                F
367       log(x,b)                log of x base b                                 F
368       max(x,y[,z...])         largest value of those listed                   *
369       median(x,y[,z...])      median value of those listed                    *
370       min(x,y[,z...])         smallest value of those listed                  *
371       mode(x,y[,z...])        mode value of those listed                      *
372       nmax(x,y[,z...])        largest value of those listed, excluding NULLs  *
373       nmedian(x,y[,z...])     median value of those listed, excluding NULLs   *
374       nmin(x,y[,z...])        smallest value of those listed, excluding NULLs *
375       nmode(x,y[,z...])       mode value of those listed, excluding NULLs     *
376       not(x)                  1 if x is zero, 0 otherwise
377       pow(x,y)                x to the power y                                *
378       rand(a,b)               random value x : a <= x < b                     *
379       round(x)                round x to nearest integer                      I
380       round(x,y)              round x to nearest multiple of y
381       round(x,y,z)            round x to nearest y*i+z for some integer i
382       sin(x)                  sine of x (x is in degrees)                     F
383       sqrt(x)                 square root of x                                F
384       tan(x)                  tangent of x (x is in degrees)                  F
385       xor(x,y)                exclusive-or (XOR) of x and y                   I
386       Internal variables:
387        row()                  current row of moving window                    I
388        col()                  current col of moving window                    I
389        nrows()                number of rows in computation region            I
390        ncols()                number of columns in computation region         I
391        x()                    current x-coordinate of moving window           F
392        y()                    current y-coordinate of moving window           F
393        ewres()                current east-west resolution                    F
394        nsres()                current north-south resolution                  F
395        area()                 area of current cell in square meters           F
396        null()                 NULL value
397       Note, that the row() and col() indexing starts with 1.
398
399   Floating point values in the expression
400       Floating point numbers are allowed in the expression. A floating  point
401       number is a number which contains a decimal point:
402           2.3   12.0   12.   .81
403       Floating  point  values in the expression are handled in a special way.
404       With arithmetic and logical operators, if either operand is float,  the
405       other  is  converted to float and the result of the operation is float.
406       This means, in particular that division of integers results in a (trun‐
407       cated)  integer, while division of floats results in an accurate float‐
408       ing point value.  With functions of  type  *  (see  table  above),  the
409       result is float if any argument is float, integer otherwise.
410
411       Note:  If you calculate with integer numbers, the resulting map will be
412       integer. If you want to get a float result, add the  decimal  point  to
413       integer number(s).
414
415       If  you want floating point division, at least one of the arguments has
416       to be a floating point value. Multiplying one of them by 1.0 will  pro‐
417       duce a floating-point result, as will using float():
418             r.mapcalc "ndvi = float(lsat.4 - lsat.3) / (lsat.4 + lsat.3)"
419
420   NULL support
421           ·   Division by zero should result in NULL.
422
423           ·   Modulus by zero should result in NULL.
424
425           ·   NULL-values  in  any  arithmetic  or  logical  operation should
426               result in NULL. (however, &&& and ||| are treated specially, as
427               described below).
428
429           ·   The  &&&  and  |||  operators observe the following axioms even
430               when x is NULL:
431                    x &&& false == false
432                    false &&& x == false
433                    x ||| true == true
434                    true ||| x == true
435
436           ·   NULL-values in function arguments should result in  NULL  (how‐
437               ever,  if(),  eval()  and  isnull()  are  treated specially, as
438               described below).
439
440           ·   The eval() function always returns its last argument
441
442           ·   The situation for if() is:
443               if(x)
444                    NULL if x is NULL; 0 if x is zero; 1 otherwise
445               if(x,a)
446                    NULL if x is NULL; a if x is non-zero; 0 otherwise
447               if(x,a,b)
448                    NULL if x is NULL; a if x is non-zero; b otherwise
449               if(x,n,z,p)
450                    NULL if x is NULL; n if x is negative;
451               z if x is zero; p if x is positive
452
453           ·   The (new) function isnull(x) returns: 1 if x is NULL; 0  other‐
454               wise.  The  (new)  function  null()  (which  has  no arguments)
455               returns an integer NULL.
456
457           ·   Non-NULL, but invalid, arguments to functions should result  in
458               NULL.
459               Examples:
460               log(-2)
461               sqrt(-2)
462               pow(a,b) where a is negative and b is not an integer
463
464       NULL  support:  Please  note  that  any  math performed with NULL cells
465       always results in a NULL value for these cells. If you want to  replace
466       a  NULL  cell on-the-fly, use the isnull() test function in a if-state‐
467       ment.
468
469       Example: The users wants the  NULL-valued  cells  to  be  treated  like
470       zeros.  To add maps A and B (where B contains NULLs) to get a map C the
471       user can use a construction like:
472
473       C = A + if(isnull(B),0,B)
474
475       NULL and conditions:
476
477       For the one argument form:
478       if(x) = NULL        if x is NULL
479       if(x) = 0      if x = 0
480       if(x) = 1      otherwise (i.e. x is neither NULL nor 0).
481
482       For the two argument form:
483       if(x,a) = NULL      if x is NULL
484       if(x,a) = 0         if x = 0
485       if(x,a) = a         otherwise (i.e. x is neither NULL nor 0).
486
487       For the three argument form:
488       if(x,a,b) = NULL    if x is NULL
489       if(x,a,b) = b       if x = 0
490       if(x,a,b) = a       otherwise (i.e. x is neither NULL nor 0).
491
492       For the four argument form:
493       if(x,a,b,c) = NULL  if x is NULL
494       if(x,a,b,c) = a          if x > 0
495       if(x,a,b,c) = b          if x = 0
496       if(x,a,b,c) = c          if x < 0
497       More generally, all operators and most functions return NULL  if  *any*
498       of their arguments are NULL.
499       The functions if(), isnull() and eval() are exceptions.
500       The  function  isnull()  returns 1 if its argument is NULL and 0 other‐
501       wise.   If  the  user  wants  the  opposite,  the  !   operator,   e.g.
502       "!isnull(x)" must be used.
503
504       All  forms  of if() return NULL if the first argument is NULL. The 2, 3
505       and 4 argument forms of if() return NULL if the "selected" argument  is
506       NULL, e.g.:
507       if(0,a,b) = b  regardless of whether a is NULL
508       if(1,a,b) = a  regardless of whether b is NULL
509       eval() always returns its last argument, so it only returns NULL if the
510       last argument is NULL.
511
512       Note: The user cannot test for NULL using  the  ==  operator,  as  that
513       returns  NULL if either or both arguments are NULL, i.e. if x and y are
514       both NULL, then "x == y" and "x != y" are both NULL rather than 1 and 0
515       respectively.
516       The behaviour makes sense if the user considers NULL as representing an
517       unknown quantity. E.g. if x and y are both unknown, then the values  of
518       "x  == y" and "x != y" are also unknown; if they both have unknown val‐
519       ues, the user doesn’t know whether or  not  they  both  have  the  same
520       value.
521

NOTES

523   Usage from command line
524       Extra  care  must  be  taken  if the expression is given on the command
525       line.  Some characters have special meaning to the UNIX  shell.   These
526       include, among others:
527       * ( ) > & |
528
529       It is advisable to put single quotes around the expression; e.g.:
530       ’result = elevation * 2’
531       Without the quotes, the *, which has special meaning to the UNIX shell,
532       would be altered and r.mapcalc would see something other than the *.
533
534   Multiple computations
535       In general, it’s preferable to do as much as possible in each r.mapcalc
536       command. E.g. rather than:
537               r.mapcalc "$GIS_OPT_OUTPUT.r = r#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * r#$GIS_OPT_SECOND"
538               r.mapcalc "$GIS_OPT_OUTPUT.g = g#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * g#$GIS_OPT_SECOND"
539               r.mapcalc "$GIS_OPT_OUTPUT.b = b#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * b#$GIS_OPT_SECOND"
540
541       use:
542            r.mapcalc <<EOF
543               $GIS_OPT_OUTPUT.r = r#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * r#$GIS_OPT_SECOND
544               $GIS_OPT_OUTPUT.g = g#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * g#$GIS_OPT_SECOND
545               $GIS_OPT_OUTPUT.b = b#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * b#$GIS_OPT_SECOND
546               EOF
547
548       as the latter will read each input map only once.
549
550   Backwards compatibility
551       For  the backwards compatibility with GRASS 6, if no options are given,
552       it manufactures file=- (which reads from stdin), so you can continue to
553       use e.g.:
554       r.mapcalc < file
555       or:
556       r.mapcalc <<EOF
557       foo = 1
558       EOF
559       But unless you need compatibility with previous GRASS GIS versions, use
560       file= explicitly, as stated above.
561
562       When the map name contains uppercase letter(s) or a dot which  are  not
563       allowed  to  be  in  module option names, the r.mapcalc command will be
564       valid also without quotes:
565       r.mapcalc elevation_A=1
566       r.mapcalc elevation.1=1
567       However, this syntax is not recommended as quotes as stated above  more
568       safe.  Using quotes is both backwards compatible and valid in future.
569
570   Interactive input in command line
571       For formulas that the user enters from standard input (rather than from
572       the command line), a line continuation feature now exists.  If the user
573       adds  a  backslash  to the end of an input line, r.mapcalc assumes that
574       the formula being entered by the user continues on to  the  next  input
575       line.   There  is  no limit to the possible number of input lines or to
576       the length of a formula.
577
578       If the r.mapcalc formula entered by the user  is  very  long,  the  map
579       title  will  contain only some of it, but most (if not all) of the for‐
580       mula will be placed into the history file for the result map.
581
582   Raster MASK handling
583       r.mapcalc follows the common GRASS behavior of raster MASK handling, so
584       the  MASK  is  only  applied when reading an existing GRASS raster map.
585       This implies that, for example, the command:
586       r.mapcalc "elevation_exaggerated = elevation * 3"
587       create a map respecting the masked pixels if MASK is active.
588
589       However, when creating a map which is not based on any map, e.g. a  map
590       from a constant:
591       r.mapcalc "base_height = 200.0"
592       the  created  raster map is limited only by a computation region but it
593       is not affected by an active MASK.  This is expected because,  as  men‐
594       tioned  above,  MASK  is  only applied when reading, not when writing a
595       raster map.
596
597       If also in this case the MASK should  be  applied,  an  if()  statement
598       including the MASK should be used, e.g.:
599       r.mapcalc "base_height = if(MASK, 200.0, null())"
600       When  testing  MASK  related expressions keep in mind that when MASK is
601       active you don’t see data in masked areas even if they  are  not  NULL.
602       See r.mask for details.
603
604   eval function
605       If the output of the computation should be only one map but the expres‐
606       sion is so complex that it is better to split  it  to  several  expres‐
607       sions, the eval function can be used:
608       r.mapcalc << EOF
609       eval(elev_200 = elevation - 200, \
610            elev_5 = 5 * elevation, \
611            elev_p = pow(elev_5, 2))
612       elevation_result = (0.5 * elev_200) + 0.8 * elev_p
613       EOF
614       This  example  uses  unix-like << EOF syntax to provide input to r.map‐
615       calc.
616
617       Note that the temporary variables (maps) are not created  and  thus  it
618       does  not  matter whether they exists or not.  In the example above, if
619       map elev_200 exists it will not be overwritten and  no  error  will  be
620       generated.  The reason is that the name elev_200 now denotes the tempo‐
621       rary variable (map) and not the existing map.  The following  parts  of
622       the  expression  will  use  the  temporary  elev_200  and  the existing
623       elev_200 will be left intact and will not be used.  If a user  want  to
624       use  the existing map, the name of the temporary variable (map) must be
625       changed.
626
627   Using the same map for input and output results
628       A map cannot be used both as an input and  as  an  output  as  in  this
629       invalid  expression  oldmap  =  oldmap + 1, instead a subsequent rename
630       using g.rename is needed when the same name is desired:
631       r.mapcalc "newmap = oldmap + 1"
632       g.rename raster=newmap,oldmap
633
634   Random number generator initialization
635       The pseudo-random number generator used by the rand() function  can  be
636       initialised  to  a  specific  value using the seed option.  This can be
637       used to replicate a previous calculation.
638
639       Alternatively, it can be initialised from the system time and  the  PID
640       using  the  -r  flag. This should result in a different seed being used
641       each time.
642
643       In either case, the seed will be written to the map’s history, and  can
644       be seen using r.info.
645
646       If  you  want  other  people  to  be  able to verify your results, it’s
647       preferable to use the seed option to supply  a  seed  which  is  either
648       specified  in the script or generated from a determenistic process such
649       as a pseudo-random number generator given an explicit seed.
650
651       Note that the rand() function will generate a fatal  error  if  neither
652       the seed option nor the -s flag are given.
653

EXAMPLES

655       To compute the average of two raster map layers a and b:
656       ave = (a + b)/2
657
658       To form a weighted average:
659       ave = (5*a + 3*b)/8.0
660
661       To  produce  a  binary representation of the raster map layer a so that
662       category 0 remains 0 and all other categories become 1:
663       mapmask = a != 0
664       This could also be accomplished by:
665       mapmask = if(a)
666
667       To mask raster map layer b by raster map layer a:
668       result = if(a,b)
669
670       To change all values below 5 to NULL:
671       newmap = if(map<5, null(), 5)
672
673       To create a map with random values in a defined range (needs either the
674       usage  of  -s  flag  or the seed parameter). The precision of the input
675       values determines the output precision (the resulting raster map type):
676       # write result as integer map (CELL)
677       random_int   = rand(-100,100)
678       # write result as double precision floating point map (DCELL)
679       random_dcell = rand(-100.0,100.0)
680       # write result as single precision floating point map (FCELL)
681       random_fcell = float(rand(-100.0,100.0))
682
683       The graph() function allows users to specify  a  x-y  conversion  using
684       pairs of x,y coordinates.  In some situations a transformation from one
685       value to another is not easily established mathematically, but  can  be
686       represented  by a 2-D graph and then linearly interpolated. The graph()
687       function provides the opportunity to accomplish this.  An x-axis  value
688       is  provided to the graph function along with the associated graph rep‐
689       resented by a series of x,y pairs.  The x values must be  monotonically
690       increasing  (each  larger  than  or  equal to the previous).  The graph
691       function linearly interpolates between pairs.  Any x  value  lower  the
692       lowest  x value (i.e. first) will have the associated y value returned.
693       Any x value higher than the last will similarly have the  associated  y
694       value returned.  Consider the request:
695       newmap = graph(map, 1,10, 2,25, 3,50)
696       X (map) values supplied and y (newmap) values returned:
697       0, 10
698       1, 10
699       1.5, 17.5
700       2.9, 47.5
701       4, 50
702       100, 50
703

KNOWN ISSUES

705       The  result  variable  on the left hand side of the equation should not
706       appear in the expression on the right hand side.
707       mymap = if( mymap > 0, mymap, 0)
708
709       Any maps generated by a r.mapcalc command only exist after  the  entire
710       command  has completed. All maps are generated concurrently, row-by-row
711       (i.e. there is an implicit "for row in rows {...}"  around  the  entire
712       expression).   Thus the #, @, and [ ] operators cannot be used on a map
713       generated within same r.mapcalc command run.  Consequently, the follow‐
714       ing (strikethrough code) does not work:
715       newmap = oldmap * 3.14
716       othermap = newmap[-1, 0] / newmap[1, 0]
717
718       Continuation  lines  must end with a \ and have no trailing white space
719       (blanks or tabs). If the user does leave white space at the end of con‐
720       tinuation lines, the error messages produced by r.mapcalc will be mean‐
721       ingless and the equation will not work as the user intended.   This  is
722       particularly important for the eval() function.
723
724       Currently,  there is no comment mechanism in r.mapcalc.  Perhaps adding
725       a capability that would cause the entire line to be  ignored  when  the
726       user  inserted  a  #  at the start of a line as if it were not present,
727       would do the trick.
728
729       The function should require the user to type "end" or "exit" instead of
730       simply  a  blank  line.  This would make separation of multiple scripts
731       separable by white space.
732
733       r.mapcalc does not print a warning in case of operations on NULL cells.
734       It is left to the user to utilize the isnull() function.
735

SEE ALSO

737        g.region, r.bitpattern, r.blend, r.colors, r.fillnulls, r.mapcalc.sim‐
738       ple
739

REFERENCES

741       r.mapcalc: An Algebra for GIS and Image Processing, by Michael  Shapiro
742       and Jim Westervelt, U.S. Army Construction Engineering Research Labora‐
743       tory (March/1991).
744
745       Performing Map Calculations on GRASS Data: r.mapcalc Program  Tutorial,
746       by  Marji  Larson,  Michael  Shapiro and Scott Tweddale, U.S. Army Con‐
747       struction Engineering Research Laboratory (December 1991)
748
749       Grey scale conversion is based on the C.I.E. x,y,z system where y  rep‐
750       resents  luminance.  See "Fundamentals of Digital Image Processing," by
751       Anil K. Jain (Prentice Hall, NJ, 1989; p 67).
752

AUTHORS

754       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
755
756       Glynn Clements
757
758       Last changed: $Date: 2018-12-14 22:43:04 +0100 (Fri, 14 Dec 2018) $
759

SOURCE CODE

761       Available at: r.mapcalc source code (history)
762
763       Main index | Raster index | Topics index | Keywords index  |  Graphical
764       index | Full index
765
766       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
767
768
769
770GRASS 7.6.0                                                       r.mapcalc(1)
Impressum