1r.mapcalc(1)                GRASS GIS 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 in‐
73       volving 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 im‐
114       plemented to address this requirement.  It allows computing and using a
115       region  based on all raster maps in an expression. Three modes are sup‐
116       ported:
117
118           •   Setting the region parameter to current will result in the  use
119               of  the current region as computational region. This is the de‐
120               fault.  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 in‐
130               tersection of all regions from raster maps specified in the ex‐
131               pression.  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 de‐
169       tails.
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       The neighborhood modifier cannot be used on maps generated within  same
240       r.mapcalc command run (see "KNOWN ISSUES" section).
241
242   Raster map layer values from the category file
243       Sometimes  it  is desirable to use a value associated with a category’s
244       label instead of the category value itself.  If a raster map layer name
245       is preceded by the @ operator, then the labels in the category file for
246       the raster map layer are used in the expression instead of the category
247       value.
248
249       For  example,  suppose  that the raster map layer soil.ph (representing
250       soil pH values) has a category file with labels as follows:
251
252       cat     label
253       ------------------
254       0       no data
255       1       1.4
256       2       2.4
257       3       3.5
258       4       5.8
259       5       7.2
260       6       8.8
261       7       9.4
262
263       Then the expression:
264
265       result = @soils.ph
266
267       would produce a result with category values 0, 1.4, 2.4, 3.5, 5.8, 7.2,
268       8.8 and 9.4.
269
270       Note  that  this  operator may only be applied to raster map layers and
271       produces a floating point value in the expression.  Therefore, the cat‐
272       egory  label  must start with a valid number.  If the category label is
273       integer, it will be represented by a floating point number. I the cate‐
274       gory  label does not start with a number or is missing, it will be rep‐
275       resented by NULL (no data) in the resulting raster map.
276
277   Grey scale equivalents and color separates
278       It is often helpful to manipulate the  colors  assigned  to  map  cate‐
279       gories.   This  is  particularly useful when the spectral properties of
280       cells have meaning (as with imagery data), or  when  the  map  category
281       values  represent real quantities (as when category values reflect true
282       elevation values).  Map color manipulation can also aid visual recogni‐
283       tion, and map printing.
284
285       The  #  operator  can  be used to either convert map category values to
286       their grey scale equivalents or to extract the red, green, or blue com‐
287       ponents of a raster map layer into separate raster map layers.
288
289       result = #map
290
291       converts each category value in map to a value in the range 0-255 which
292       represents the grey scale level implied by the color for the  category.
293       If  the  map  has a grey scale color table, then the grey level is what
294       #map evaluates to.  Otherwise, it is computed as:
295
296        0.10 * red + 0.81 * green + 0.01 * blue
297
298       Alternatively, you can use:
299
300       result = y#map
301
302       to use the NTSC weightings:
303
304        0.30 * red + 0.59 * green + 0.11 * blue
305
306       Or, you can use:
307
308       result = i#map
309
310       to use equal weightings:
311
312        0.33 * red + 0.33 * green + 0.33 * blue
313
314       The # operator has three other forms:  r#map, g#map, b#map.  These  ex‐
315       tract  the  red, green, or blue components in the named raster map, re‐
316       spectively.  The GRASS shell script r.blend extracts each of these com‐
317       ponents  from two raster map layers, and combines them by a user-speci‐
318       fied percentage.  These forms allow color separates to  be  made.   For
319       example,  to extract the red component from map and store it in the new
320       0-255 map layer red, the user could type:
321
322       red = r#map
323
324       To assign this map grey colors type:
325
326       r.colors map=red color=rules
327       black
328       white
329
330       To assign this map red colors type:
331
332       r.colors map=red color=rules
333       black
334       red
335
336   Functions
337       The functions currently supported are listed in the table  below.   The
338       type  of  the result is indicated in the last column.  F means that the
339       functions always results in a floating point value, I  means  that  the
340       function  gives  an  integer result, and * indicates that the result is
341       float if any of the arguments to the function are floating point values
342       and integer if all arguments are integer.
343
344       function                description                                     type
345       ---------------------------------------------------------------------------
346       abs(x)                  return absolute value of x                      *
347       acos(x)                 inverse cosine of x (result is in degrees)      F
348       asin(x)                 inverse sine of x (result is in degrees)        F
349       atan(x)                 inverse tangent of x (result is in degrees)     F
350       atan(x,y)               inverse tangent of y/x (result is in degrees)   F
351       ceil(x)                 the smallest integral value not less than x     *
352       cos(x)                  cosine of x (x is in degrees)                   F
353       double(x)               convert x to double-precision floating point    F
354       eval([x,y,...,]z)       evaluate values of listed expr, pass results to z
355       exp(x)                  exponential function of x                       F
356       exp(x,y)                x to the power y                                F
357       float(x)                convert x to single-precision floating point    F
358       floor(x)                the largest integral value not greater than x   *
359       graph(x,x1,y1[x2,y2..]) convert the x to a y based on points in a graph F
360       graph2(x,x1[,x2,..],y1[,y2..])
361                               alternative form of graph()                     F
362       if                      decision options:                               *
363       if(x)                   1 if x not zero, 0 otherwise
364       if(x,a)                 a if x not zero, 0 otherwise
365       if(x,a,b)               a if x not zero, b otherwise
366       if(x,a,b,c)             a if x > 0, b if x is zero, c if x < 0
367       int(x)                  convert x to integer [ truncates ]              I
368       isnull(x)               check if x = NULL
369       log(x)                  natural log of x                                F
370       log(x,b)                log of x base b                                 F
371       max(x,y[,z...])         largest value of those listed                   *
372       median(x,y[,z...])      median value of those listed                    *
373       min(x,y[,z...])         smallest value of those listed                  *
374       mod(x,y)                return the modulus (the remainder) of x/y       *
375       mode(x,y[,z...])        mode value of those listed                      *
376       nmax(x,y[,z...])        largest value of those listed, excluding NULLs  *
377       nmedian(x,y[,z...])     median value of those listed, excluding NULLs   *
378       nmin(x,y[,z...])        smallest value of those listed, excluding NULLs *
379       nmode(x,y[,z...])       mode value of those listed, excluding NULLs     *
380       not(x)                  1 if x is zero, 0 otherwise
381       pow(x,y)                x to the power y                                *
382       rand(a,b)               random value x : a <= x < b                     *
383       round(x)                round x to nearest integer                      I
384       round(x,y)              round x to nearest multiple of y
385       round(x,y,z)            round x to nearest y*i+z for some integer i
386       sin(x)                  sine of x (x is in degrees)                     F
387       sqrt(x)                 square root of x                                F
388       tan(x)                  tangent of x (x is in degrees)                  F
389       xor(x,y)                exclusive-or (XOR) of x and y                   I
390       Internal variables:
391        row()                  current row of moving window                    I
392        col()                  current col of moving window                    I
393        nrows()                number of rows in computation region            I
394        ncols()                number of columns in computation region         I
395        x()                    current x-coordinate of moving window           F
396        y()                    current y-coordinate of moving window           F
397        ewres()                current east-west resolution                    F
398        nsres()                current north-south resolution                  F
399        area()                 area of current cell in square meters           F
400        null()                 NULL value
401       Note, that the row() and col() indexing starts with 1.
402
403   Floating point values in the expression
404       Floating  point numbers are allowed in the expression. A floating point
405       number is a number which contains a decimal point:
406           2.3   12.0   12.   .81
407       Floating point values in the expression are handled in a  special  way.
408       With  arithmetic and logical operators, if either operand is float, the
409       other is converted to float and the result of the operation  is  float.
410       This means, in particular that division of integers results in a (trun‐
411       cated) integer, while division of floats results in an accurate  float‐
412       ing  point  value.  With functions of type * (see table above), the re‐
413       sult is float if any argument is float, integer otherwise.
414
415       Note: If you calculate with integer numbers, the resulting map will  be
416       integer.  If  you  want to get a float result, add the decimal point to
417       integer number(s).
418
419       If you want floating point division, at least one of the arguments  has
420       to  be a floating point value. Multiplying one of them by 1.0 will pro‐
421       duce a floating-point result, as will using float():
422             r.mapcalc "ndvi = float(lsat.4 - lsat.3) / (lsat.4 + lsat.3)"
423
424   NULL support
425           •   Division by zero should result in NULL.
426
427           •   Modulus by zero should result in NULL.
428
429           •   NULL-values in any arithmetic or logical operation  should  re‐
430               sult  in  NULL. (however, &&& and ||| are treated specially, as
431               described below).
432
433           •   The &&& and ||| operators observe  the  following  axioms  even
434               when x is NULL:
435                    x &&& false == false
436                    false &&& x == false
437                    x ||| true == true
438                    true ||| x == true
439
440           •   NULL-values  in  function arguments should result in NULL (how‐
441               ever, if(), eval() and isnull() are treated specially,  as  de‐
442               scribed below).
443
444           •   The eval() function always returns its last argument
445
446           •   The situation for if() is:
447               if(x)
448                    NULL if x is NULL; 0 if x is zero; 1 otherwise
449               if(x,a)
450                    NULL if x is NULL; a if x is non-zero; 0 otherwise
451               if(x,a,b)
452                    NULL if x is NULL; a if x is non-zero; b otherwise
453               if(x,n,z,p)
454                    NULL if x is NULL; n if x is negative;
455               z if x is zero; p if x is positive
456
457           •   The  (new) function isnull(x) returns: 1 if x is NULL; 0 other‐
458               wise. The (new) function null() (which has  no  arguments)  re‐
459               turns an integer NULL.
460
461           •   Non-NULL,  but invalid, arguments to functions should result in
462               NULL.
463               Examples:
464               log(-2)
465               sqrt(-2)
466               pow(a,b) where a is negative and b is not an integer
467
468       NULL support: Please note that any math performed with NULL  cells  al‐
469       ways  results in a NULL value for these cells. If you want to replace a
470       NULL cell on-the-fly, use the isnull() test function in a if-statement.
471
472       Example: The users wants the NULL-valued cells to be treated  like  ze‐
473       ros.  To  add  maps A and B (where B contains NULLs) to get a map C the
474       user can use a construction like:
475
476       C = A + if(isnull(B),0,B)
477
478       NULL and conditions:
479
480       For the one argument form:
481       if(x) = NULL        if x is NULL
482       if(x) = 0      if x = 0
483       if(x) = 1      otherwise (i.e. x is neither NULL nor 0).
484
485       For the two argument form:
486       if(x,a) = NULL      if x is NULL
487       if(x,a) = 0         if x = 0
488       if(x,a) = a         otherwise (i.e. x is neither NULL nor 0).
489
490       For the three argument form:
491       if(x,a,b) = NULL    if x is NULL
492       if(x,a,b) = b       if x = 0
493       if(x,a,b) = a       otherwise (i.e. x is neither NULL nor 0).
494
495       For the four argument form:
496       if(x,a,b,c) = NULL  if x is NULL
497       if(x,a,b,c) = a          if x > 0
498       if(x,a,b,c) = b          if x = 0
499       if(x,a,b,c) = c          if x < 0
500       More generally, all operators and most functions return NULL  if  *any*
501       of their arguments are NULL.
502       The functions if(), isnull() and eval() are exceptions.
503       The  function  isnull()  returns 1 if its argument is NULL and 0 other‐
504       wise.  If the user wants the  opposite,  the  !  operator,  e.g.  "!is‐
505       null(x)" must be used.
506
507       All  forms  of if() return NULL if the first argument is NULL. The 2, 3
508       and 4 argument forms of if() return NULL if the "selected" argument  is
509       NULL, e.g.:
510       if(0,a,b) = b  regardless of whether a is NULL
511       if(1,a,b) = a  regardless of whether b is NULL
512       eval() always returns its last argument, so it only returns NULL if the
513       last argument is NULL.
514
515       Note: The user cannot test for NULL using the == operator, as that  re‐
516       turns  NULL  if  either or both arguments are NULL, i.e. if x and y are
517       both NULL, then "x == y" and "x != y" are both NULL rather than 1 and 0
518       respectively.
519       The behaviour makes sense if the user considers NULL as representing an
520       unknown quantity. E.g. if x and y are both unknown, then the values  of
521       "x  == y" and "x != y" are also unknown; if they both have unknown val‐
522       ues, the user doesn’t know whether or  not  they  both  have  the  same
523       value.
524

NOTES

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

EXAMPLES

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

KNOWN ISSUES

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

REFERENCES

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

SEE ALSO

753        g.region, r.bitpattern, r.blend, r.colors, r.fillnulls, r.mapcalc.sim‐
754       ple
755

AUTHORS

757       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
758
759       Glynn Clements
760

SOURCE CODE

762       Available at: r.mapcalc source code (history)
763
764       Accessed: Saturday Oct 28 18:17:25 2023
765
766       Main index | Raster index | Topics index | Keywords index  |  Graphical
767       index | Full index
768
769       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
770
771
772
773GRASS 8.3.1                                                       r.mapcalc(1)
Impressum