r.mapcalc(1)	       Grass User's Manual	     r.mapcalc(1)



NNAAMMEE
       rr..mmaappccaallcc  - Raster map layer data calculator.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..mmaappccaallcc
       rr..mmaappccaallcc [rreessuulltt==_e_x_p_r_e_s_s_i_o_n]

DDEESSCCRRIIPPTTIIOONN
       _r_._m_a_p_c_a_l_c  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.

PPRROOGGRRAAMM UUSSEE
       If used without command	line  arguments,  _r_._m_a_p_c_a_l_c  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_._m_a_p_c_a_l_c expects its  input  to  have
       the form:


       rreessuulltt==_e_x_p_r_e_s_s_i_o_n


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


       The  formula  entered to _r_._m_a_p_c_a_l_c by the user is recorded
       both in the _r_e_s_u_l_t map TITLE (which appears in  the  cate-
       gory  file for _r_e_s_u_l_t) and in the history file for _r_e_s_u_l_t.


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



OOPPEERRAATTOORRSS AANNDD OORRDDEERR OOFF PPRREECCEEDDEENNCCEE
       The following operators are supported:

	    Operator	     Meaning			     Type
       Precedence
	    --------------------------------------------------------------
	    %	       modulus			  Arithmetic  4
	    /	       division 		  Arithmetic  4
	    *	       multiplication		  Arithmetic  4
	    +	       addition 		  Arithmetic  3
	    -	       subtraction		  Arithmetic  3
	    ==	       equal			  Logical     2
	    !=	       not equal		  Logical     2
	    >	       greater than		  Logical     2
	    >=	       greater than or equal	  Logical     2
	    <	       less than		  Logical     2
	    <=	       less than or equal	  Logical     2
	    &&	       and			  Logical     1
	    ||	       or			  Logical     1
	    #	       color separator operator   Arithmetic

       (modulus is the remainder upon division)


       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 0 result.   The  logical  operators  give  a	1
       result if the comparison is true, 0 otherwise.





RRAASSTTEERR MMAAPP LLAAYYEERR NNAAMMEESS
       Anything  in  the expression which is not a number, opera-
       tor, 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 _3_1_0_7 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 pro-
       gram is run non-interactively.  Examples given here assume
       the program is run interactively.  See NOTES, below.


       _r_._m_a_p_c_a_l_c 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  specify-
       ing 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_._m_a_p_c_a_l_c.)



TTHHEE NNEEIIGGHHBBOORRHHOOOODD MMOODDIIFFIIEERR
       Maps and images are data base files stored in raster  for-
       mat, i.e., two-dimensional matrices of integer values.  In
       _r_._m_a_p_c_a_l_c, maps may be followed by a _n_e_i_g_h_b_o_r_h_o_o_d modifier
       that  specifies	a  relative  offset from the current cell
       being evaluated.  The format is _m_a_p_[_r_,_c_], where _r  is  the
       row  offset  and  _c  is	the  column offset.  For example,
       _m_a_p_[_1_,_2_] refers to the cell one row below and two  columns
       to the right of the current cell, _m_a_p_[_-_2_,_-_1_] refers to the
       cell two rows above and one column to the left of the cur-
       rent  cell,  and _m_a_p_[_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.



RRAASSTTEERR MMAAPP LLAAYYEERR VVAALLUUEESS FFRROOMM TTHHEE CCAATTEEGGOORRYY FFIILLEE
       Sometimes it is desirable to use a value associated with a
       category's  _c_o_n_t_e_n_t_s 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 _s_o_i_l_._p_h
       (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 * 10



       would produce a result with category values 0, 14, 24, 35,
       58, 72, 88 and 94.


       Note that this operator may only be applied to raster  map
       layers  and produces a floating point value in the expres-
       sion.  Also the category label must  start  with  a  valid
       number.	 Missing labels, or labels that do not start with
       a number will (silently) produce a 0 value for that  cate-
       gory.

GGRREEYY SSCCAALLEE EEQQUUIIVVAALLEENNTTSS AANNDD CCOOLLOORR SSEEPPAARRAATTEESS
       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 _m_a_p  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 evalu-
       ates to.  Otherwise, it is computed as:







       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 _b_l_e_n_d_._s_h 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  _m_a_p  and
       store  it  in  the new 0-255 map layer _r_e_d, 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






FFUUNNCCTTIIOONNSS
       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	      *
       atan(x)		   inverse tangent of  x  (result  is  in
       degrees)  F
       cos(x)		   cosine     of     x	   (x	 is    in
       degrees) 	  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 floating point	      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
       *
       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



       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.

FFLLOOAATTIINNGG PPOOIINNTT VVAALLUUEESS IINN TTHHEE EEXXPPRREESSSSIIOONN
       Floating point numbers are allowed in  the  expression.	A
       floating point number is a number which contains a decimal
       point:

       2.3   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  (trun-
       cated)  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).

NNUULLLL ssuuppppoorrtt
	      Division by zero should result in NULL.

	      Modulus by zero should result in NULL.

		   NULL-values in any arithmetic operation should
	      result in NULL.

		   NULL-values	in  logical  operations should be
	      handled as follows:

			    NULL || true = true
			    NULL || false = NULL
			    NULL || NULL = NULL
			    NULL && true = NULL
			    NULL && false = false
			    NULL && NULL = NULL


		   NULL-values	in  function   arguments   should
	      result in NULL.

		   Even  though  this  is  also true for the if()
	      function, if() is spelled out here  for  clarifica-
	      tion:

		   if(x)
		       NULL  if x is NULL; 0 if x is zero; 1 oth-
	      erwise
		   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

		   Exceptions:	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)

EEXXAAMMPPLLEESS
       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:

	    mask = a/a

       This could also be accomplished by:

	    mask = if(a)

       To mask raster map layer _b by raster map layer _a:

	    result = if(a,b)

       To change all map values below 5 to NULL:

	       newmap = if(map<5, null(), 5)


RREEGGIIOONN//MMAASSKK
       The  user  must	be aware of the current geographic region
       and current  mask  settings  when  using  _r_._m_a_p_c_a_l_c.   All
       raster  map  layers  are  read into the current geographic
       region masked by the current mask.  If it  is  desired  to
       modify  an  existing  raster  map  layer without involving
       other raster map layers, the geographic region  should  be
       set  to	agree  with  the  cell	header for the raster map
       layer.  For example, suppose it	is  determined	that  the
       _e_l_e_v_a_t_i_o_n  raster  map layer must have each category value
       increased by 10 meters.	The following expression is legal
       and will do the job:

	    new_elevation = elevation + 10

       Since a category value of 0 is used in GRASS for locations
       which do not exist in the raster map layer, the new raster
       map  layer will contain the category value 10 in the loca-
       tions that  did	not  exist  in	the  original  elevation.
       Therefore,  in  this  example,  it  is  essential that the
       boundaries of the geographic region be set to  agree  with
       the cell header.


       However,  if  there  is a current mask, then the resultant
       raster map layer is masked when it  is  written;  i.e.,	0
       category  values in the mask force zero values in the out-
       put.

NNOOTTEESS
       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  expres-
       sion;  e.g.:

	    result = 'elevation * 2'

       Without	the  quotes,  the *, which has special meaning to
       the UNIX shell, would be altered and _r_._m_a_p_c_a_l_c  would  see
       something other than the *.


       If  the	input  comes  directly	from the keyboard and the
       _r_e_s_u_l_t raster map layer exists, the user will be asked  if
       it  can	be overwritten.  Otherwise, the _r_e_s_u_l_t raster map
       layer will automatically be overwritten if it exists.


       Quoting _r_e_s_u_l_t is not allowed.  However, it is never  nec-
       essary  to  quote  _r_e_s_u_l_t 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 \ to the end  of  an
       input  line,  _r_._m_a_p_c_a_l_c	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_._m_a_p_c_a_l_c 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 _r_e_s_u_l_t map.


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

BBUUGGSS
       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_._m_a_p_c_a_l_c 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_._m_a_p_c_a_l_c are  almost  useless.
       In future, _r_._m_a_p_c_a_l_c 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_._m_a_p_c_a_l_c.
       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.

SSEEEE AALLSSOO
       rr..mmaappccaallcc::  AAnn  AAllggeebbrraa	ffoorr  GGIISS aanndd IImmaaggee PPrroocceessssiinngg, by
       Michael Shapiro and Jim Westervelt, U.S. Army Construction
       Engineering Research Laboratory (March/1991).


       PPeerrffoorrmmiinngg  MMaapp CCaallccuullaattiioonnss oonn GGRRAASSSS DDaattaa:: rr..mmaappccaallcc PPrroo--
       ggrraamm TTuuttoorriiaall, by Marji Larson, Michael Shapiro and  Scott
       Tweddale, U.S. Army Construction Engineering Research Lab-
       oratory (December 1991)


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


       _b_l_e_n_d_._s_h_,   _g_._r_e_g_i_o_n_,  _r_._c_o_l_o_r_s_,  _r_._c_o_m_b_i_n_e_,  _r_._f_i_l_l_n_u_l_l_s_,
       _r_._i_n_f_e_r_, _r_._m_a_s_k_, _r_._w_e_i_g_h_t

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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0					     r.mapcalc(1)
