Homepage > Man Pages > Category > General Commands
Homepage > Man Pages > Name > R

# r.mapcalc

## man page of r.mapcalc

### r.mapcalc:

```NAME
r.mapcalc

DESCRIPTION
r.mapcalc  performs  arithmetic  on  raster map layers.  New raster map
layers can  be  created  which  are  arithmetic  expressions  involving
existing  raster  map  layers, integer or floating point constants, and
functions.

PROGRAM USE
If used without command line arguments, r.mapcalc will read its  input,
one  line at a time, from standard input (which is the keyboard, unless
redirected from a file or across a pipe).  Otherwise, the expression on
the command line is evaluated.  r.mapcalc expects its input to have the
form:

result=expression

where result is the name of a raster map layer to contain the result of
the  calculation  and  expression  is  any  legal arithmetic expression
involving  existing  raster  map  layers,  integer  or  floating  point
constants,  and  functions  known  to  the calculator.  Parentheses are
allowed in the expression and may be nested to any depth.  result  will
be created in the user's current mapset.

The  formula  entered  to r.mapcalc by the user is recorded both in the
result map title (which appears in the category file for result) and in
the history file for result.

Some  characters have special meaning to the command shell. If the user
is entering input to r.mapcalc on the command line, expressions  should
be enclosed within single quotes.  See NOTES, below.

OPERATORS AND ORDER OF PRECEDENCE
The following operators are supported:
Operator   Meaning                    Type        Precedence
--------------------------------------------------------------
-          negation                   Arithmetic  12
~          one's complement           Bitwise     12
!          not                        Logical     12
^          exponentiation             Arithmetic  11
%          modulus                    Arithmetic  10
/          division                   Arithmetic  10
*          multiplication             Arithmetic  10
-          subtraction                Arithmetic   9
<<         left shift                 Bitwise      8
>>         right shift                Bitwise      8
>>>        right shift (unsigned)     Bitwise      8
>          greater than               Logical      7
>=         greater than or equal      Logical      7
<          less than                  Logical      7
<=         less than or equal         Logical      7
==         equal                      Logical      6
!=         not equal                  Logical      6
&          bitwise and                Bitwise      5
|          bitwise or                 Bitwise      4
&&         logical and                Logical      3
&&&        logical and[1]             Logical      3
||         logical or                 Logical      2
|||        logical or[1]              Logical      2
?:         conditional                Logical      1
(modulus is the remainder upon division)

[1]  The  &&&  and  ||| operators handle null values differently to
other operators. See the section entitled NULL support below  for  more
details.

The  operators  are  applied  from  left to right, with those of higher
precedence applied before those with lower precedence.  Division  by  0
and  modulus  by  0 are acceptable and give a NULL result.  The logical
operators give a 1 result if the comparison is true, 0 otherwise.

RASTER MAP LAYER NAMES
Anything in the expression which is not a number, operator, or function
name is taken to be a raster map layer name.  Examples:

elevation
x3
3d.his

Most  GRASS raster map layers meet this naming convention.  However, if
a raster map layer has a name which conflicts with the above  rule,  it
should be quoted.  For example, the expression

x = a-b

would be interpreted as:  x equals a minus b, whereas

x = "a-b"

would be interpreted as:  x equals the raster map layer named a-b

Also

x = 3107

would create x filled with the number 3107, while

x = "3107"

would copy the raster map layer 3107 to the raster map layer x.

Quotes  are  not  required  unless the raster map layer names look like
numbers or contain  operators,  OR  unless  the  program  is  run  non-
interactively.    Examples   given  here  assume  the  program  is  run
interactively.  See NOTES, below.

r.mapcalc will look for the raster map layers according to  the  user's
current mapset search path.  It is possible to override the search path
and specify the mapset from which to select the raster map layer.  This
is done by specifying the raster map layer name in the form:

name@mapset

For example, the following is a legal expression:

result = x@PERMANENT / y@SOILS

The  mapset  specified  does  not have to be in the mapset search path.
(This method of overriding the mapset search  path  is  common  to  all
GRASS commands, not just r.mapcalc.)

THE NEIGHBORHOOD MODIFIER
Maps and images are data base files stored in raster format, i.e., two-
dimensional matrices of integer values.   In  r.mapcalc,  maps  may  be
followed  by  a  neighborhood modifier that specifies a relative offset
from the current cell being evaluated.  The format is map[r,c], where r
is  the  row  offset and c is the column offset.  For example, map[1,2]
refers to the cell one row below and two columns to the  right  of  the
current  cell,  map[-2,-1]  refers  to  the cell two rows above and one
column to the left of the current cell, and map[0,1] refers to the cell
one  column  to the right of the current cell.  This syntax permits the
development of neighborhood-type filters within a single map or  across
multiple maps.

RASTER MAP LAYER VALUES FROM THE CATEGORY FILE
Sometimes  it  is desirable to use a value associated with a category's
label instead of the category value itself.  If a raster map layer name
is preceded by the @ operator, then the labels in the category file for
the raster map layer are used in the expression instead of the category
value.

For  example,  suppose  that the raster map layer soil.ph (representing
soil pH values) has a category file with labels as follows:

cat  label
------------------
0    no data
1    1.4
2    2.4
3    3.5
4    5.8
5    7.2
6    8.8
7    9.4

Then the expression:

result = @soils.ph

would produce a result with category values 0, 1.4, 2.4, 3.5, 5.8, 7.2,
8.8 and 9.4.

Note  that  this  operator may only be applied to raster map layers and
produces a floating point value  in  the  expression.   Therefore,  the
category  label  must start with a valid number.  If the category label
is integer, it will be represented by a floating point  number.  I  the
category  label  does not start with a number or is missing, it will be
represented by NULL (no data) in the resulting raster map.

GREY SCALE EQUIVALENTS AND COLOR SEPARATES
It  is  often  helpful  to  manipulate  the  colors  assigned  to   map
categories.   This  is particularly useful when the spectral properties
of cells have meaning (as with imagery data), or when the map  category
values  represent real quantities (as when category values reflect true
elevation  values).   Map  color  manipulation  can  also  aid   visual
recognition, and map printing.

The  #  operator  can  be used to either convert map category values to
their grey scale equivalents or to extract  the  red,  green,  or  blue
components of a raster map layer into separate raster map layers.

result = #map

converts each category value in map to a value in the range 0-255 which
represents the grey scale level implied by the color for the  category.
If  the  map  has a grey scale color table, then the grey level is what
#map evaluates to.  Otherwise, it is computed as:

0.10 * red + 0.81 * green + 0.01 * blue

Alternatively, you can use:

result = y#map

to use the NTSC weightings:

0.30 * red + 0.59 * green + 0.11 * blue

Or, you can use:

result = i#map

to use equal weightings:

0.33 * red + 0.33 * green + 0.33 * blue

The # operator has three other  forms:   r#map,  g#map,  b#map.   These
extract  the  red,  green,  or blue components in the named raster map,
respectively.  The GRASS shell script r.blend extracts  each  of  these
components  from  two  raster  map layers, and combines them by a user-
specified percentage.  These forms allow color separates  to  be  made.
For  example, to extract the red component from map and store it in the
new 0-255 map layer red, the user could type:

red = r#map

To assign this map grey colors type:

r.colors map=red color=rules
black
white

To assign this map red colors type:

r.colors map=red color=rules
black
red

FUNCTIONS
The functions currently supported are listed in the table  below.   The
type  of  the result is indicated in the last column.  F means that the
functions always results in a floating point value, I  means  that  the
function  gives  an  integer result, and * indicates that the result is
float if any of the arguments to the function are floating point values
and integer if all arguments are integer.

function       description                        type
---------------------------------------------------------------------------
abs(x)              return absolute value of x              *
acos(x)             inverse cosine of x (result is in degrees)   F
asin(x)             inverse sine of x (result is in degrees)     F
atan(x)             inverse tangent of x (result is in degrees)  F
atan(x,y)      inverse tangent of y/x (result is in degrees)     F
cos(x)              cosine of x (x is in degrees)           F
double(x)      convert x to double-precision floating point F
eval([x,y,...,]z)   evaluate values of listed expr, pass results to z
exp(x)              exponential function of x               F
exp(x,y)       x to the power y                   F
float(x)       convert x to single-precision floating point F
graph(x,x1,y1[x2,y2..])  convert the x to a y  based  on  points  in  a
graph   F
if             decision options:                  *
if(x)               1 if x not zero, 0 otherwise
if(x,a)             a if x not zero, 0 otherwise
if(x,a,b)      a if x not zero, b otherwise
if(x,a,b,c)         a if x > 0, b if x is zero, c if x < 0
int(x)              convert x to integer [ truncates ]      I
isnull(x)               check if x = NULL
log(x)              natural log of x                   F
log(x,b)       log of x base b                         F
max(x,y[,z...])          largest value of those listed           *
median(x,y[,z...])  median value of those listed            *
min(x,y[,z...])          smallest value of those listed               *
mode(x,y[,z...])             mode     value     of     those     listed
*
not(x)              1 if x is zero, 0 otherwise
pow(x,y)       x to the power y                   *
rand(a,b)      random value x : a <= x < b
round(x)       round x to nearest integer              I
sin(x)              sine of x (x is in degrees)             F
sqrt(x)             square root of x                   F
tan(x)              tangent of x (x is in degrees)               F
xor(x,y)       exclusive-or (XOR) of x and y           I

Internal variables:
row()                  current row of moving window
col()                  current col of moving window
x()                    current x-coordinate of moving window
y()                    current y-coordinate of moving window
ewres()                current east-west resolution
nsres()                current north-south resolution
null()                 NULL value
Note, that the row() and col() indexing starts with 1.

FLOATING POINT VALUES IN THE EXPRESSION
Floating point numbers are allowed in the expression. A floating  point
number is a number which contains a decimal point:
2.3   12.0   12.   .81
Floating point values in the expression are handled in a special way.
With arithmetic and logical operators, if either operand is float,  the
other  is  converted to float and the result of the operation is float.
This means, in particular  that  division  of  integers  results  in  a
(truncated)  integer,  while  division of floats results in an accurate
floating point value.  With functions of type * (see table above),  the
result is float if any argument is float, integer otherwise.

Note:  If you calculate with integer numbers, the resulting map will be
integer. If you want to get a float result, add the  decimal  point  to
integer number(s).

If  you want floating point division, at least one of the arguments has
to be a floating point value. Multiplying  one  of  them  by  1.0  will
produce a floating-point result, as will using float():
r.mapcalc "ndvi=float(lsat.4 - lsat.3) / (lsat.4 + lsat.3)"

NULL support
Division by zero should result in NULL.

Modulus by zero should result in NULL.

NULL-values  in  any arithmetic or logical operation
should result in NULL.  (however,  &&&  and  |||  are
treated specially, as described below).

The &&& and ||| operators observe the following
axioms even when x is NULL:
x &&& false == false
false &&& x == false
x ||| true == true
true ||| x == true

NULL-values in function arguments should  result  in
NULL  (however,  if(),  eval()  and  isnull() are treated
specially, as described below).

The  eval()  function  always  returns  its   last
argument

The situation for if() is:
if(x)
NULL if x is NULL; 0 if x is zero; 1 otherwise
if(x,a)
NULL if x is NULL; a if x is non-zero; 0 otherwise
if(x,a,b)
NULL if x is NULL; a if x is non-zero; b otherwise
if(x,n,z,p)
NULL if x is NULL; n if x is negative;
z if x is zero; p if x is positive

The  (new)  function  isnull(x)  returns:  1 if x is
NULL; 0 otherwise. The (new) function null()  (which  has
no arguments) returns an integer NULL.

Non-NULL,  but  invalid,  arguments  to  functions should
result in NULL.
Examples:
log(-2)
sqrt(-2)
pow(a,b) where a is negative and b is not an integer

NULL support: Please note that  any  math  performed  with  NULL  cells
always  results in a NULL value for these cells. If you want to replace
a NULL cell on-the-fly,  use  the  isnull()  test  function  in  a  if-
statement.

Example:  The  users  wants  the  NULL-valued  cells to be treated like
zeros. To add maps A and B (where B contains NULLs) to get a map C  the
user can use a construction like:

C=A + if(isnull(B),0,B)

NULL and conditions:

For the one argument form:
if(x) = NULL        if x is NULL
if(x) = 0      if x = 0
if(x) = 1      otherwise (i.e. x is neither NULL nor 0).

For the two argument form:
if(x,a) = NULL      if x is NULL
if(x,a) = 0         if x = 0
if(x,a) = a         otherwise (i.e. x is neither NULL nor 0).

For the three argument form:
if(x,a,b) = NULL    if x is NULL
if(x,a,b) = b       if x = 0
if(x,a,b) = a       otherwise (i.e. x is neither NULL nor 0).

For the four argument form:
if(x,a,b,c) = NULL  if x is NULL
if(x,a,b,c) = a          if x > 0
if(x,a,b,c) = b          if x = 0
if(x,a,b,c) = c          if x < 0
More generally, all operators and most functions return NULL if *any*
of their arguments are NULL.
The functions if(), isnull() and eval() are exceptions.
The function  isnull()  returns  1  if  its  argument  is  NULL  and  0
otherwise.   If  the  user  wants  the  opposite,  the ! operator, e.g.
"!isnull(x)" must be used.

All forms of if() return NULL if the first argument is NULL. The  2,  3
and  4 argument forms of if() return NULL if the "selected" argument is
NULL, e.g.:
if(0,a,b) = b  regardless of whether a is NULL
if(1,a,b) = a  regardless of whether b is NULL
eval() always returns its last argument, so it only  returns  NULL  if
the last argument is NULL.

Note:  The  user  cannot  test  for NULL using the == operator, as that
returns NULL if either or both arguments are NULL, i.e. if x and y  are
both NULL, then "x == y" and "x != y" are both NULL rather than 1 and 0
respectively.
The behaviour makes sense if the user considers NULL as representing an
unknown  quantity. E.g. if x and y are both unknown, then the values of
"x == y" and "x != y" are also  unknown;  if  they  both  have  unknown
values,  the  user  doesn't know whether or not they both have the same
value.

NOTES
Extra care must be taken if the expression  is  given  on  the  command
line.   Some  characters have special meaning to the UNIX shell.  These
include, among others:

* ( ) > & |

It is advisable to put single quotes around the expression; e.g.:
result = 'elevation * 2'
Without the quotes, the *, which  has  special  meaning  to  the  UNIX
shell,  would  be  altered and r.mapcalc would see something other than
the *.

In general, it's preferable to do as much as possible in each r.mapcalc
command. E.g. rather than:
r.mapcalc     "\$GIS_OPT_OUTPUT.r     =    r#\$GIS_OPT_FIRST    *
.\$GIS_OPT_PERCENT + (1.0 - .\$GIS_OPT_PERCENT) * r#\$GIS_OPT_SECOND"
r.mapcalc    "\$GIS_OPT_OUTPUT.g    =     g#\$GIS_OPT_FIRST     *
.\$GIS_OPT_PERCENT + (1.0 - .\$GIS_OPT_PERCENT) * g#\$GIS_OPT_SECOND"
r.mapcalc     "\$GIS_OPT_OUTPUT.b     =    b#\$GIS_OPT_FIRST    *
.\$GIS_OPT_PERCENT + (1.0 - .\$GIS_OPT_PERCENT) * b#\$GIS_OPT_SECOND"
use:
r.mapcalc <<EOF
\$GIS_OPT_OUTPUT.r = r#\$GIS_OPT_FIRST * .\$GIS_OPT_PERCENT + (1.0
- .\$GIS_OPT_PERCENT) * r#\$GIS_OPT_SECOND
\$GIS_OPT_OUTPUT.g = g#\$GIS_OPT_FIRST * .\$GIS_OPT_PERCENT + (1.0
- .\$GIS_OPT_PERCENT) * g#\$GIS_OPT_SECOND
\$GIS_OPT_OUTPUT.b = b#\$GIS_OPT_FIRST * .\$GIS_OPT_PERCENT + (1.0
- .\$GIS_OPT_PERCENT) * b#\$GIS_OPT_SECOND
EOF
as the latter will read each input map only once.  If the input comes
directly from the keyboard and the result raster map layer exists,  the
user  will  be  asked  if it can be overwritten.  Otherwise, the result
raster map layer will automatically be overwritten if it exists.

Quoting result is not allowed.  However, it is never necessary to quote
result since it is always taken to be a raster map layer name.

For formulas that the user enters from standard input (rather than from
the command line), a line continuation feature now exists.  If the user
adds  a  backslash  to the end of an input line, r.mapcalc assumes that
the formula being entered by the user continues on to  the  next  input
line.   There  is  no limit to the possible number of input lines or to
the length of a formula.

If the r.mapcalc formula entered by the user  is  very  long,  the  map
title  will  contain  only  some  of  it,  but most (if not all) of the
formula will be placed into the history file for the result map.

When the user  enters  input  to  r.mapcalc  non-interactively  on  the
command  line,  the  program  will  not  warn the user not to overwrite
existing map layers.   Users  should  therefore  take  care  to  assign
program outputs raster map names that do not yet exist in their current
mapsets.

The environment variable  GRASS_RND_SEED  is  read  to  initialise  the
random number generator.

EXAMPLES
To compute the average of two raster map layers a and b:
ave = (a + b)/2
To form a weighted average:
ave = (5*a + 3*b)/8.0
To  produce a binary representation of the raster map layer a so that
category 0 remains 0 and all other categories become 1:
This could also be accomplished by:
To mask raster map layer b by raster map layer a:
result = if(a,b)
To change all values below 5 to NULL:
newmap = if(map<5, null(), 5)
The graph() function allows users to specify a  x-y  conversion  using
pairs of x,y coordinates.  In some situations a transformation from one
value to another is not easily established mathematically, but  can  be
represented  by a 2-D graph and then linearly interpolated. The graph()
function provides the opportunity to accomplish this.  An x-axis  value
is  provided  to  the  graph  function  along with the associated graph
represented  by  a  series  of  x,y  pairs.   The  x  values  must   be
monotonically  increasing  (each larger than or equal to the previous).
The graph function linearly interpolates between pairs.   Any  x  value
lower  the lowest x value (i.e. first) will have the associated y value
returned.  Any x value higher than the last  will  similarly  have  the
associated y value returned.  Consider the request:
newmap = graph(map, 1,10, 2,25, 3,50)
X (map) values supplied and y (newmap) values returned:
0, 10
1, 10
1.5, 17.5
2.9, 47.5
4, 50
100, 50

BUGS
Continuation  lines  must end with a \ and have NO trailing white space
(blanks or tabs).  If the user does leave white space  at  the  end  of
continuation  lines,  the  error messages produced by r.mapcalc will be
meaningless and the equation will not work as the user intended.   This
is important for the eval() function.

Error  messages  produced  by r.mapcalc are almost useless.  In future,
r.mapcalc should make some attempt to point the user to  the  offending
section of the equation, e.g.:
x = a * b ++ c
ERROR: somewhere in line 1: ...  b ++ c ...

Currently,  there is no comment mechanism in r.mapcalc.  Perhaps adding
a capability that would cause the entire line to be  ignored  when  the
user  inserted  a  #  at the start of a line as if it were not present,
would do the trick.

The function should require the user to type "end" or "exit" instead of
simply  a  blank  line.  This would make separation of multiple scripts
separable by white space.

r.mapcalc does not print a warning in case of operations on NULL cells.
It is left to the user to utilize the isnull() function.

r.mapcalc:  An Algebra for GIS and Image Processing, by Michael Shapiro
and  Jim  Westervelt,  U.S.  Army  Construction  Engineering   Research
Laboratory (March/1991).

Performing  Map Calculations on GRASS Data: r.mapcalc Program Tutorial,
by  Marji  Larson,  Michael  Shapiro  and  Scott  Tweddale,  U.S.  Army
Construction Engineering Research Laboratory (December 1991)

Grey  scale  conversion  is  based  on  the C.I.E. x,y,z system where y
represents luminance.  See "Fundamentals of Digital Image  Processing,"
by Anil K. Jain (Prentice Hall, NJ, 1989; p 67).

g.region, r.bitpattern, r.blend, r.colors, r.fillnulls

AUTHORS
Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

Glynn Clements

Last changed: \$Date: 2010-05-05 23:20:15 +0200 (Wed, 05 May 2010) \$

Full index

(C) 1999-2009 GRASS Development Team

R.MAPCALC(1)
```