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



NNAAMMEE
       rr..ccoommbbiinnee   -  Allows  category values from several raster
       map layers to be combined.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ccoommbbiinnee
       rr..ccoommbbiinnee < _i_n_p_u_t_f_i_l_e

DDEESSCCRRIIPPTTIIOONN
       _r_._c_o_m_b_i_n_e accepts commands that are similar to those  used
       for  boolean combinations (AND, OR, NOT) in order to over-
       lay user-selected  groups  of  categories  from	different
       raster	map  layers.   After  the  _r_._c_o_m_b_i_n_e  program  is
       started, the users are asked if they want the graphic out-
       put  to go to a color graphics monitor.	If a color graph-
       ics monitor is not used, the graphic output  is	displayed
       on the terminal screen.	This display is, of course, quite
       rough. It consists of numerals  representing  the  various
       categories  that  result from the _r_._c_o_m_b_i_n_e analysis. Fol-
       lowing this question, the user will see a [1]:.	 This  is
       the first prompt, and indicates that _r_._c_o_m_b_i_n_e is ready to
       receive input from the user.


       The following commands perform operations in _r_._c_o_m_b_i_n_e_:

	Command  |			|
	[Alias]  |	Followed by	|	       Such as
       __________|______________________|________________________
       NAME	 |  name for raster	|  sandstone
       [name]	 |  map output		|
       __________|______________________|________________________
       GROUP	 |  category values	|  1-40 (elevation.255)
       [group]	 |  and a raster map	|
       [grp]	 |			|
       __________|______________________|________________________
       AND	 |  expression describ- |  (grp 4 (soils))
       [and]	 |  ing a raster map	|  (grp 2 (owner))
       [&][&&amp;]   |	and categories	    |
       __________|______________________|________________________
       OR	 |  expression describ- |  (grp 4 (soils))
       [or]	 |  ing a raster map	|  (grp 2 (owner))
       [| ][| | ]|  and categories	|
       __________|______________________|________________________
       NOT	 |  expression describ- |  (grp 2 3 (roads))
       [not]	 |  ing a raster map	|
       [~]	 |  and categories	|
       __________|______________________|________________________
       OVER	 |  existing raster map |  sandstone yellow
       [over]	 |  and color		|
       [overlay] |			|
       __________|______________________|________________________
       COVER	 |  existing raster map |  sandstone
       [cover]	 |			|
       __________|______________________|________________________

       _r_._c_o_m_b_i_n_e uses the same colors for all the operating  com-
       mands.  This is the _r_._c_o_m_b_i_n_e color table:

       0 black	  4 blue     8 grey	      12 blue/grey
       1 red	  5 purple   9 red/grey       13 purple/grey
       2 yellow   6 green    10 yellow/grey   14 green/grey
       3 orange   7 white    11 orange/grey   15 dark grey

       The  user  may  enter  commands	either	line-by-line from
       within _r_._c_o_m_b_i_n_e, or by typing the commands  into  a  file
       which  is then read into r.combine using the UNIX redirec-
       tion symbol <. The command format is the same for the  two
       methods.  The line-by-line method, however, does not allow
       as much flexibility as does use of an  input  file.  If	a
       line containing a syntax error is entered on the _r_._c_o_m_b_i_n_e
       command line, it is cleared; the line  must  then  be  re-
       entered in its entirety.  Input files containing mistakes,
       however, can easily be modified (rather	than  recreated).
       An  input file is especially advantageous when a more com-
       plex series of statements is input to _r_._c_o_m_b_i_n_e.


       _r_._c_o_m_b_i_n_e uses two types of commands: those which  perform
       operations, and those which have some other function.


       _r_._c_o_m_b_i_n_e  can probably best be learned by following exam-
       ples, so pay special attention  to  those  included  below
       with the operating command descriptions. Notice two things
       in particular:

	      All parentheses must be closed.  A raster map layer
	      name  must  often  be  enclosed within parentheses;
	      each time one of the above commands is used, it and
	      its  appropriate	companions  must also be enclosed
	      within parentheses.

	      Certain spaces are important. Generally,	_r_._c_o_m_b_i_n_e
	      requires	at  least  one	space  before  an opening
	      parenthesis (except when it is the first	character
	      in  an expression).  _r_._c_o_m_b_i_n_e ignores extra spaces
	      and tab characters.


   OOPPEERRAATTIINNGG CCOOMMMMAANNDDSS
       Below is a summary of the syntax  of  the  operating  com-
       mands,  a  description of each command, and examples using
       the Spearfish sample data base.

       NAME
	      (NAME  new_map_name  (Expression))  Allows  graphic
	      output   to  be  saved  in  the  raster  map  layer
	      _n_e_w___m_a_p___n_a_m_e, so that it	is  available  for  addi-
	      tional  analysis or for future viewing. The results
	      of performing the expression in parentheses is then
	      placed  into  the  named	output	raster	map layer
	      (here, _n_e_w___m_a_p___n_a_m_e).  Note that	this  means  that
	      _r_._c_o_m_b_i_n_e may be used to create new raster map lay-
	      ers from existing  ones.	 _r_._c_o_m_b_i_n_e  automatically
	      creates  a  color table for the new raster map lay-
	      ers; however, the user should run the GRASS program
	      _r_._s_u_p_p_o_r_t  to fill in category assignments and his-
	      tory information if the new raster map layer is  to
	      be saved for future use in the mapset.


       example:
       ((NNAAMMEE ssaannddssttoonnee ((GGRROOUUPP 44 ((ggeeoollooggyy))))))
       The  above  command  will  result in the creation of a new
       raster map layer named _s_a_n_d_s_t_o_n_e, noting the locations  of
       cells  with  _g_e_o_l_o_g_y  category value 4.	You must then run
       the GRASS program _r_._s_u_p_p_o_r_t in order to	label  the  cate-
       gories present in the new raster map layer.


       Resultant categories:

       0  - black: other than sandstone
       1  - red:   sandstone




       GROUP
	      (GROUP category_values (existing raster map layer))
	      Selects out categories of the desired  values  from
	      the existing raster map layer which is indicated in
	      parentheses directly after the  category	grouping.
	      It  also works to select out just one category from
	      the map layer.  Any of the following are legal cat-
	      egory groupings:

	      2
	      1-18
	      1 2 5-7.



       example:
	((GGRROOUUPP 11--4400 ((eelleevvaattiioonn..225555))))
       Depicts	only  the area with elevation 1187 meters or less
       (i.e., _e_l_e_v_a_t_i_o_n map layer category values  1  through  40
       only).
       Resultant categories:

       0  - black: elevation > 1187 m
       1  - red  : elevation <= 1187 m



       example:
	((NNAAMMEE llooww..hhii ((GGRROOUUPP 11--4400 223388--225555 ((eelleevvaattiioonn..225555))))))
       Depicts	only  those  areas with elevations of either 1187
       meters or less, or in excess  of  1787  meters  (_e_l_e_v_a_t_i_o_n
       categories  1-40,  and  238-255).   The	graphic output is
       saved in the new raster map layer called _l_o_w_._h_i.
       Resultant categories:

       0  - black : elevation > 1187 m and < 1787 m
       1  - red   : elevation <= 1187 m and >= 1787 m




       AND
	      (AND (Expression A) (Expression  B))  Combines  two
	      map  layers and creates a new one; when BOTH of the
	      category values associated with the same given cell
	      location	in  the  two combined map layers are non-
	      zero, a category value of 1  is  assigned  to  that
	      cell  in the new map layer. If, however, eeiitthheerr map
	      layer assigns a category value of zero to the  same
	      given  cell location, the category value associated
	      with this cell's	location  in  the  resultant  map
	      layer also becomes zero.


       For example,

       raster map  1   2 2 0
		       2 1 0
		       0 0 0	     1 0 0  results
			      AND 1 1 0
       raster map  2   1 0 1	     0 0 0
		       1 1 0
		       1 1 0



       example:
	((AANNDD ((GGRROOUUPP 44 77--99 ((ggeeoollooggyy)))) ((GGRROOUUPP 22 ((oowwnneerr))))))
       Depicts	the occurrences of categories 4, 7, 8, and 9 from
       the map layer _g_e_o_l_o_g_y whenever they occur on U.S.   Forest
       Service	property.  Results  are displayed to the terminal
       screen.
       Resultant categories:

       0  - black : no data occurred any of the
		    raster map layers
       1  - red   : the AND condition is met



       Note that if neither map layer contained any areas of  "no
       data",  the  resultant raster map layer would include only
       1's.


       Example:
	((NNAAMMEE  ssaanndd  ((AANNDD  ((GGRROOUUPP  44  77--99  ((ggeeoollooggyy))))  ((GGRROOUUPP	22
       ((oowwnneerr))))))))
       Same  as  above,  except  the results are saved in the map
       layer _s_a_n_d.



       OR
	      (OR (Expression A) (Expression B)) Combines two map
	      layers  and  creates  a new one; when EITHER of the
	      category values associated with the same given cell
	      location	in  the  two  combined map layers is non-
	      zero, a category value of 1  is  assigned  to  that
	      cell  in	the new map layer.  If, however, bbootthh map
	      layers assign a category value of zero to the  same
	      given  cell  location,  the  category value of this
	      cell in the resultant map layer also becomes  zero.
	      Only  two  map  layers may be combined at one time.
	      For example:

	      raster map  1   2 2 0
			      2 1 0
			      0 0 0	     1 1 1  results
				   OR	  1 1 0
	      raster map  2   1 0 1	     1 1 0
			      1 1 0
			      1 1 0




       Example:
	((OORR ((GGRROOUUPP 44 77--99 ((ggeeoollooggyy)))) ((GGRROOUUPP 22 ((oowwnneerr))))))
       Depicts all occurrences of categories 4, 7, 8, and 9  from
       the  map  layer	_g_e_o_l_o_g_y  as  well as showing all the land
       which is U.S. Forest Service property.  Results	are  dis-
       played to the terminal screen.
       Resultant categories:

       0  - black: this area has neither the values of 4,
		   7, 8, or 9 nor is it on U.S. Forest Service
		   property
       1  - red  : this area meets one or the other of the
		   conditions noted above



       Note  that  no  distinction  is	made between those places
       where conditions are met in both map layers and where they
       are  met in only one. See the _r_._c_o_m_b_i_n_e command OVER if it
       is necessary to make that distinction.



       NOT
	      (NOT (Expression)) Negates _E_x_p_r_e_s_s_i_o_n in	order  to
	      define  a new map layer which contains the opposite
	      of what is defined by _E_x_p_r_e_s_s_i_o_n.  The  new  raster
	      map  layer will contain category values of either 0
	      or 1. 0 values would indicate that the  NOT  condi-
	      tions  were  not met.  Cell values of 1 would indi-
	      cate that the NOT conditions were met.  In order to
	      specify  the  map layer in which to save the output
	      from NOT, use the _r_._c_o_m_b_i_n_e command NAME.


       Example:
	((NNAAMMEE rrddss ((NNOOTT ((GGRROOUUPP 00 ((rrooaaddss))))))))
       Areas containing category zero in the existing  map  layer
       _r_o_a_d_s  indicate those locations within the data base where
       roads do not exist.  Negating that  expression  leaves  us
       with  all  other  areas	 - i.e., those locations at which
       roads do exist. Here, the graphic output is saved  in  the
       raster map layer named _r_d_s.
       Resultant categories:

       0  - black: no roads
       1  - red  : roads



       The same results could have been obtained with:
	((NNAAMMEE  rrddss  ((GGRROOUUPP  11--55 ((rrooaaddss)))))).  NOT is most useful in
       those cases where it is simpler to define something on the
       basis of what it is not than on the basis of what it is.



       OVER
	      (OVER   color   (Expression))   or   (OVER   exist-
	      ing_rastermap color (Expression)) Performs a _t_r_a_n_s_-
	      _p_a_r_e_n_t  overlay  operation.  This means that when a
	      map layer which depicts some  feature  in  blue  is
	      overlain	with  one which depicts a feature in yel-
	      low, the resulting raster map layer will show areas
	      of  overlap  in  green; areas in the two raster map
	      layer that do  not  overlap  other  areas  maintain
	      their original colors (i.e., yellow or blue).


       OVER  may  be  run  with  or without an existing map layer
       name.  If the user does not specify an existing raster map
       layer  name,  OVER  applies  the  color	specified  to the
       expression in parentheses and displays the results. If  an
       existing  raster map layer name is specified, OVER applies
       the color to the expression  (just  as  before)	and  then
       overlays  the  results  on  top of the existing raster map
       layer.  In order to make sense of the colors which result,
       use only those existing map layers created using OVER.


       OVER allows the user to specify just four colors:

	color value
	red	1
	yellow	2
	blue	4
	grey	8

       These  four colors are then combined to form other colors.
       The number of progressive overlays allowed is  limited  to
       four  (one for each of the basic colors above). The actual
       number of colors on the resultant raster map  layer,  how-
       ever, varies depending on the distribution of the features
       and on the interaction of the features from the	different
       map  layers  which are overlain. When two or more of these
       colors are overlain, new colors are created. The numerical
       values  associated  with the colors above are significant,
       in that	the  values  of  any  additional  colors  created
       reflect	the  sum of two or more of the four above.  These
       overlain color values appear on the resultant  overlay  as
       _c_e_l_l  (category)  values.  The user should know what these
       values represent in order to know what  category  informa-
       tion  is  to be associated with the new map layer (entered
       using the GRASS _r_._s_u_p_p_o_r_t command), and to know	the  sig-
       nificance  of  this  and subsequent analyses involving the
       new map layer.


       Any of these colors and category values	may  result  from
       OVER.  Note  that  this is the same as the _r_._c_o_m_b_i_n_e color
       table listed above.

       0 black	 4 blue    8 grey	   12 blue/grey
       1 red	 5 purple  9 red/grey	   13 purple/grey
       2 yellow  6 green   10 yellow/grey  14 green/grey
       3 orange  7 white   11 orange/grey  15 dark grey

       The syntax for OVER makes no provision for  a  new  raster
       map layer name. It is necessary to use the _r_._c_o_m_b_i_n_e oper-
       ator NAME to specify a new raster map layer name in  which
       to  save the graphic output generated by OVER. If the user
       runs OVER without specifying an output  raster  map  layer
       name,  output is displayed to the terminal.  However, this
       output is available for future use only	if  it	is  saved
       using the NAME command.


       example:
	((NNAAMMEE ppaarrkk..oorr..pprriivv ((OOVVEERR rreedd ((GGRROOUUPP 11 ((oowwnneerr))))))))
       The  new  raster  map  layer _p_a_r_k_._o_r_._p_r_i_v displays private
       land (i.e., category 1 of the raster map layer  _o_w_n_e_r)  in
       red,  and  displays  U.S.  Forest  Service land (i.e., "no
       data" areas within the _o_w_n_e_r map layer) as black.
       Resultant categories:

       0  - black: park
       1  - red  : private land



       example:
	((NNAAMMEE rrooaaddss..oorr..nnoott ((OOVVEERR  ppaarrkk..oorr..pprriivv	yyeellllooww	((GGRROOUUPP	00
       ((rrooaaddss))))))))
       Category 0 in the map layer _r_o_a_d_s is overlain in yellow on
       top of the _p_a_r_k_._o_r_._p_r_i_v map layer created above. The  out-
       put is placed in a new map layer named _r_o_a_d_s_._o_r_._n_o_t.
       Resultant categories in _r_o_a_d_s_._o_r_._n_o_t are:

       0  - black  : park; road
       1  - red    : private; road
       2  - yellow : park; no road
       3  - orange : private; no road



       example:
	((NNAAMMEE  llooww..eelleevv ((OOVVEERR ppaarrkk..oorr..pprriivv bblluuee ((GGRROOUUPP 11--1199 ((eellee--
       vvaattiioonn..225555))))))))
       The elevation categories of 1123 meters or less	from  the
       map  layer  _e_l_e_v_a_t_i_o_n_._2_5_5  are assigned the color blue and
       then overlain on _p_a_r_k_._o_r_._p_r_i_v (generated in  the  previous
       example).
       Resultant categories in the new map layer _l_o_w_._e_l_e_v are:

       0  - black  : park; > 1123 m
       1  - red    : private; > 1123m
       4  - blue   : park; <= 1123 m
       5  - purple : private; <= 1123m

       Note  how  category  5  is  the	sum of red (1) + blue (4)
       (i.e., the intersection of areas containing low elevations
       and private lands with roads).



       COVER
	      (COVER   existing_map   (Expression))  Performs  an
	      _o_p_a_q_u_e overlay operation. This means that where the
	      top  map layer contains "holes" (cell category val-
	      ues of 0), the bottom map layer will show  through.
	      Where  the  top map layer contains information on a
	      feature, it will	cover  (substitute  its  category
	      value  for) whatever is below it. The top map layer
	      is that which is defined by _E_x_p_r_e_s_s_i_o_n. The  bottom
	      map  layer  is  _e_x_i_s_t_i_n_g___m_a_p;  this  map layer must
	      already exist.


       The user does not specify colors with COVER.   COVER  uses
       the  default  color  table that is listed above with OVER.
       Colors are assigned starting with  the  lower  map  layer.
       The  category values are assigned the color from the table
       that corresponds with that value.  For example, 1 would be
       red;  2,  yellow; 3, orange, etc.  Moving to the upper map
       layer COVER starts wherever it left off	after  the  lower
       one.  If  the  highest value of the lower map layer was 5,
       then all non-zero (i.e., places where  a  feature  exists)
       cells  of  the upper map layer would be assigned the value
       of 6 (green). Note that if, in this case,  the  upper  map
       layer  did  not	have  any  cells  of value zero, then the
       entire resulting new map layer would be green.  The  upper
       map  layer  would have been assigned the value 6 and would
       have completely covered that which was below it.


       This is what happens:

       Expression	    1 1 1 0
	(top raster map)    1 1 0 0
			    0 0 0 0	 6 6 6 0   result
				      6 6 2 0
       oldmap		    2 5 0 0	 5 5 2 2
	(bottom raster map) 0 5 2 0
			    5 5 2 2

       As many map layers may be overlain as  is  desired.   How-
       ever, there is a practical limit on the number of map lay-
       ers that can be used while still generating sensible  out-
       put.  That number depends on the features involved in each
       map layer, and how many cells within the upper (overlying)
       map  layers contain category values of zero (holes through
       which underlying data can be seen).


       COVER has no provision for saving graphic output. Use  the
       _r_._c_o_m_b_i_n_e  command  NAME  to  save  output in a raster map
       layer.


       Example:
       ((NNAAMMEE lo.elev (COVER owner (GROUP 1-19 (elevation.255))))
       The categories that indicate elevation of 1123  meters  or
       less  are  placed  on top of the existing map layer _o_w_n_e_r.
       Output is saved in _l_o_._e_l_e_v.
       Resultant categories:

       1  - red    : private ownership; elev > 1123 m
       2  - yellow : park property; elev > 1123 m
       3  - orange : park or private; elev <= 1123 m



       Example:
       ((NNAAMMEE sand.lo (COVER lo.elev (GROUP 4 (geology))))
       Category 4 of _g_e_o_l_o_g_y (sandstone)  is  placed  on  top  of
       _l_o_._e_l_e_v,  the  raster  map  layer  created in the previous
       example.  The output is saved in _s_a_n_d_._l_o.
       Resultant categories:

       1  - red    : private ownership; elev > 1123 m;
		     no sandstone
       2  - yellow : park property; elev > 1123 m ;
		     no sandstone
       3  - orange : park or private; elev <= 1123 m;
		     no sandstone
       4  - blue   : park or private; any elev; sandstone



   AADDDDIITTIIOONNAALL CCOOMMMMAANNDDSS
       _r_._c_o_m_b_i_n_e also contains a number of commands which are not
       used  for  operations,  but serve a variety of other func-
       tions.  Additional commands:

       Command|        Alias	   |		    Followed By
       _______|____________________|______________________________
       QUIT   |  quit  q  exit	bye|
       CATS   |  categories  cats  |  existing raster map
       EXP    |  exp  expr	   |  number of an expression
       !       |		     |	 shell	command  e.g.  vi
       comb.1
       <      | 		   |  existing input file
       WINDOW |  window 	   |  existing raster map layer
       HISTORY|  history  hist	   |
       HELP   |  help		   |  combine command
       ERASE  |  erase		   |


       QUIT   Allows  the  user  to  exit  from  _r_._c_o_m_b_i_n_e  while
	      remaining within the GRASS session.



       CATS
	      CATS  raster  map  Gives user an on-line listing of
	      categories and labels for the map layer  specified.
	      For example: [1]:CCAATTSS oowwnneerr



       EXP
	      EXP  expression number During an _r_._c_o_m_b_i_n_e session,
	      each completed expression and command is assigned a
	      number.	This  number may be used to reference the
	      expression to which it is assigned; this means that
	      the  user  can substitute the _n_u_m_b_e_r of the expres-
	      sion for the expression itself.


       For example:
       [4]:((GGRROOUUPP 55 ((ggeeoollooggyy))))
       [5]:((NNAAMMEE lliimmeessttoonnee ((EEXXPP 44))))
       Use the UNIX history mechanism (explained below) to deter-
       mine  the  specific  numbers  associated  with  particular
       expressions in your current _r_._c_o_m_b_i_n_e session.

       !

	      !shell command Allows user to  temporarily  suspend
	      _r_._c_o_m_b_i_n_e and go run another command, as in the two
	      examples below:

	      !vi input
	      !g.list type=rast



       Unless otherwise specified by the user,	when  a  file  is
       created using a system editor (like _v_i) from within _r_._c_o_m_-
       _b_i_n_e_, this file will be placed in the user's mapset  under
       the  COMBINE  directory.   After the command is completed,
       control returns to _r_._c_o_m_b_i_n_e.



       <
	      < input filename Takes  input  from  the	specified
	      _f_i_l_e_n_a_m_e	containing  _r_._c_o_m_b_i_n_e commands. The user,
	      of course, must previously have  entered	the  com-
	      mands into this named input file. If no pathname is
	      given, the input file  is  assumed  to  be  in  the
	      user's  mapset  under  the  COMBINE directory.  For
	      example, the user would perform the following steps
	      to  redirect  input  from the file _c_o_m_b_._i_n into the
	      _r_._c_o_m_b_i_n_e program (while within _r_._c_o_m_b_i_n_e):


       First, the user would create the file:  !!vvii ccoommbb..iinn
       Second, the user would direct _r_._c_o_m_b_i_n_e to take its  input
       from the
	file:  << ccoommbb..iinn



       WINDOW
	      WINDOW  raster_map  Gives on-line geographic region
	      (window) information about  the  raster  map  layer
	      specified.



       HISTORY
	      Provides	a  listing  of	all  previously completed
	      expressions used within the current _r_._c_o_m_b_i_n_e  ses-
	      sion, and the numbers associated with the execution
	      of these commands.



       HELP
	      HELP command An on-line help facility for _r_._c_o_m_b_i_n_e
	      commands	only.  Type  in the name of the _r_._c_o_m_b_i_n_e
	      command for which help is needed, to see the  entry
	      for that command.



       ERASE  Will cause the color graphics monitor to clear.


NNOOTTEESS
       In  all of the above examples, only a single line of input
       was provided to _r_._c_o_m_b_i_n_e. However, since _r_._c_o_m_b_i_n_e conve-
       niently	ignores  extra spaces and tabs, it is possible to
       type input to _r_._c_o_m_b_i_n_e	in  the  manner  outlined  below.
       Users  may find this to more clearly exhibit the relation-
       ships involved and parentheses needed. This can	be  typed
       as  shown  below  either directly at the _r_._c_o_m_b_i_n_e command
       line, or redirected into _r_._c_o_m_b_i_n_e from an already  exist-
       ing file.


       example:

       (NAME good.place
	      (AND
		       (OR
			       (GROUP 1 2 5 (geology))
			       (GROUP 1-5 (elevation.255))
		       )
		       (NOT
			       (GROUP 1-4 (landuse))
		       )
	     )
       )

       Such  involved  input  to  _r_._c_o_m_b_i_n_e might conveniently be
       typed into an input file,  and  then  input  to	_r_._c_o_m_b_i_n_e
       using the UNIX redirection mechanism <<.

SSEEEE AALLSSOO
       _r_._i_n_f_e_r

       _r_._m_a_p_c_a_l_c

       _r_._w_e_i_g_h_t

AAUUTTHHOORRSS
       L. Van Warren, Michael Shapiro, James Westervelt,

       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.combine(1)
