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 overlay user-selected groups of
       categories from different raster map layers.  After the _r_._c_o_m_b_i_n_e  pro-
       gram is started, the users are asked if they want the graphic output to
       go to a color graphics monitor.	If a color  graphics  monitor  is  not
       used,  the  graphic  output  is displayed on the terminal screen.  This
       display is, of course, quite rough. It consists of numerals  represent-
       ing  the  various  categories  that result from the _r_._c_o_m_b_i_n_e analysis.
       Following 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 commands.  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 redirection 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 contain-
       ing mistakes, however, can easily be modified (rather than  recreated).
       An  input file is especially advantageous when a more complex 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 examples, 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 commands, a descrip-
       tion 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 avail-
	      able  for additional 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  layers from existing ones.  _r_._c_o_m_b_i_n_e automatically creates
	      a color table for the new raster map layers; however,  the  user
	      should  run  the	GRASS  program	_r_._s_u_p_p_o_r_t  to fill in category
	      assignments and history 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 categories 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 cate-
	      gory  grouping.  It  also  works to select out just one category
	      from the map layer.  Any of the  following  are  legal  category
	      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 cate-
	      gory 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 cate-
	      gory 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 displayed 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  val-
	      ues  of either 0 or 1. 0 values would indicate that the NOT con-
	      ditions were not met.  Cell values of 1 would indicate 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.	Negat-
       ing that expression leaves us with all other areas  - i.e., those loca-
       tions 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  existing_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  yellow,  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, however, 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 over-
       lain, new colors are created. The numerical values associated with  the
       colors above are significant, in that the values of any additional col-
       ors 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 (cate-
       gory) values. The user should know what these values represent in order
       to  know what category information 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 operator 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., cat-
       egory 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 output 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 ((eelleevvaattiioonn..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	inter-
       section	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 values 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) what-
	      ever  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 start-
       ing  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.  However, there is  a
       practical  limit  on  the  number  of map layers that can be used while
       still generating sensible output.  That number depends on the  features
       involved  in each map layer, and how many cells within the upper (over-
       lying) 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 functions.  Additional com-
       mands:

       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  com-
	      pleted 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
	      expression for the expression itself.


       For example:
       [4]:((GGRROOUUPP 55 ((ggeeoollooggyy))))
       [5]:((NNAAMMEE lliimmeessttoonnee ((EEXXPP 44))))
       Use the UNIX history mechanism (explained below) to determine the  spe-
       cific  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  con-
	      taining _r_._c_o_m_b_i_n_e commands. The user, of course, must previously
	      have entered the commands 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 session, 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 conveniently ignores extra  spa-
       ces  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  rela-
       tionships  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 existing 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)
