r.combine

NAME

r.combine - Allows category values from several raster map layers to be combined.
(GRASS Raster Program)

SYNOPSIS

r.combine
r.combine < inputfile

DESCRIPTION

r.combine 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.combine program 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 representing the various categories that result from the r.combine analysis. Following this question, the user will see a [1]:. This is the first prompt, and indicates that r.combine is ready to receive input from the user.

The following commands perform operations in r.combine:

 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))
[&][&&]   |  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.combine uses the same colors for all the operating commands. This is the r.combine 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.combine, 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.combine 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 complex series of statements is input to r.combine.

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

r.combine 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.combine requires at least one space before an opening parenthesis (except when it is the first character in an expression). r.combine ignores extra spaces and tab characters.

OPERATING COMMANDS

Below is a summary of the syntax of the operating commands, 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 new_map_name, so that it is available 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, new_map_name). Note that this means that r.combine may be used to create new raster map layers from existing ones. r.combine automatically creates a color table for the new raster map layers; however, the user should run the GRASS program r.support 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:
(NAME sandstone (GROUP 4 (geology)))
The above command will result in the creation of a new raster map layer named sandstone, noting the locations of cells with geology category value 4. You must then run the GRASS program r.support 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 category 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:
(GROUP 1-40 (elevation.255))
Depicts only the area with elevation 1187 meters or less (i.e., elevation map layer category values 1 through 40 only).
Resultant categories:

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

example:
(NAME low.hi (GROUP 1-40 238-255 (elevation.255)))
Depicts only those areas with elevations of either 1187 meters or less, or in excess of 1787 meters (elevation categories 1-40, and 238-255). The graphic output is saved in the new raster map layer called low.hi.
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, either 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:
(AND (GROUP 4 7-9 (geology)) (GROUP 2 (owner)))
Depicts the occurrences of categories 4, 7, 8, and 9 from the map layer geology 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:
(NAME sand (AND (GROUP 4 7-9 (geology)) (GROUP 2 (owner))))
Same as above, except the results are saved in the map layer sand.

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, both 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:
(OR (GROUP 4 7-9 (geology)) (GROUP 2 (owner)))
Depicts all occurrences of categories 4, 7, 8, and 9 from the map layer geology 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.combine command OVER if it is necessary to make that distinction.

NOT
(NOT (Expression))

Negates Expression in order to define a new map layer which contains the opposite of what is defined by Expression. The new raster map layer will contain category values of either 0 or 1. 0 values would indicate that the NOT conditions 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.combine command NAME.

Example:
(NAME rds (NOT (GROUP 0 (roads))))
Areas containing category zero in the existing map layer roads 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 rds.
Resultant categories:

0  - black: no roads 
1  - red  : roads

The same results could have been obtained with: (NAME rds (GROUP 1-5 (roads))). 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 transparent 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 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 cell (category) 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.support command), and to know the significance 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.combine 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.combine 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:
(NAME park.or.priv (OVER red (GROUP 1 (owner))))
The new raster map layer park.or.priv displays private land (i.e., category 1 of the raster map layer owner) in red, and displays U.S. Forest Service land (i.e., "no data" areas within the owner map layer) as black.
Resultant categories:

0  - black: park 
1  - red  : private land

example:
(NAME roads.or.not (OVER park.or.priv yellow (GROUP 0 (roads))))
Category 0 in the map layer roads is overlain in yellow on top of the park.or.priv map layer created above. The output is placed in a new map layer named roads.or.not.
Resultant categories in roads.or.not are:

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

example:
(NAME low.elev (OVER park.or.priv blue (GROUP 1-19 (elevation.255))))
The elevation categories of 1123 meters or less from the map layer elevation.255 are assigned the color blue and then overlain on park.or.priv (generated in the previous example).
Resultant categories in the new map layer low.elev 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 opaque 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) whatever is below it. The top map layer is that which is defined by Expression. The bottom map layer is existing_map; 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. 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 (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.combine command NAME to save output in a raster map layer.

Example:
(NAME 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 owner. Output is saved in lo.elev.
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:
(NAME sand.lo (COVER lo.elev (GROUP 4 (geology))))
Category 4 of geology (sandstone) is placed on top of lo.elev, the raster map layer created in the previous example. The output is saved in sand.lo.
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

ADDITIONAL COMMANDS

r.combine also contains a number of commands which are not used for operations, but serve a variety of other functions. 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.combine 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]:CATS owner

EXP EXP expression number

During an r.combine 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 number of the expression for the expression itself.

For example:
[4]:(GROUP 5 (geology))
[5]:(NAME limestone (EXP 4))
Use the UNIX history mechanism (explained below) to determine the specific numbers associated with particular expressions in your current r.combine session.

! !shell command

Allows user to temporarily suspend r.combine 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 vi) from within r.combine, this file will be placed in the user's mapset under the COMBINE directory. After the command is completed, control returns to r.combine.

< < input filename

Takes input from the specified filename containing r.combine 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 comb.in into the r.combine program (while within r.combine):

First, the user would create the file: !vi comb.in
Second, the user would direct r.combine to take its input from the
file: < comb.in

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.combine session, and the numbers associated with the execution of these commands.

HELP HELP command

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

ERASE

Will cause the color graphics monitor to clear.

NOTES

In all of the above examples, only a single line of input was provided to r.combine. However, since r.combine conveniently ignores extra spaces and tabs, it is possible to type input to r.combine in the manner outlined below. Users may find this to more clearly exhibit the relationships involved and parentheses needed. This can be typed as shown below either directly at the r.combine command line, or redirected into r.combine 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.combine might conveniently be typed into an input file, and then input to r.combine using the UNIX redirection mechanism <.

AUTHORS

L. Van Warren, Michael Shapiro, James Westervelt,
U.S. Army Construction Engineering Research Laboratory

Last changed: $Date$