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 exist-
       ing  raster  map layers, integer or floating point constants, and func-
       tions.

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 layers, integer or  floating  point  con-
       stants, 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  cre-
       ated 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 category 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
	    --------------------------------------------------------------
	    ^	       exponentiation		  Arithmetic  5
	    %	       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 oper-
       ators give a 1 result if the comparison is true, 0 otherwise.





RRAASSTTEERR MMAAPP LLAAYYEERR NNAAMMEESS
       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 _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 program is run non-interac-
       tively.	 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 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_._m_a_p_c_a_l_c.)



TTHHEE NNEEIIGGHHBBOORRHHOOOODD MMOODDIIFFIIEERR
       Maps and images are data base files stored in raster format, i.e., two-
       dimensional matrices of integer values.	In _r_._m_a_p_c_a_l_c, maps may be fol-
       lowed  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 col-
       umn to the left of the current 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 expression.  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
       category.

GGRREEYY SSCCAALLEE EEQQUUIIVVAALLEENNTTSS AANNDD CCOOLLOORR SSEEPPAARRAATTEESS
       It  is  often  helpful  to  manipulate the colors assigned to map cate-
       gories.	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 recogni-
       tion, 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 com-
       ponents 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 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 _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
       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
       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
       rand(a,b)      random value between a and 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



       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	float-
       ing  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 or logical  operation	should
	      result in NULL.

		   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-state-
       ment.


       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  cate-
       gory  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 locations that did not exist in the origi-
       nal  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 output.

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 expression;  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.	Other-
       wise, 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 necessary 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  for-
       mula 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 com-
       mand line, the program will not warn the user not to overwrite existing
       map layers.  Users should therefore 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 Labora-
       tory (March/1991).


       PPeerrffoorrmmiinngg MMaapp CCaallccuullaattiioonnss oonn GGRRAASSSS DDaattaa:: rr..mmaappccaallcc PPrrooggrraamm  TTuuttoorriiaall,
       by  Marji  Larson,  Michael  Shapiro and Scott Tweddale, U.S. Army Con-
       struction Engineering Research Laboratory (December 1991)


       Grey scale conversion is based on the C.I.E. x,y,z system where y  rep-
       resents	luminance.  See "Fundamentals of Digital 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_3_/_0_2_/_0_9 _1_2_:_0_7_:_2_3 _$



GRASS 5.0							  r.mapcalc(1)
