.TH r.combine .nh .SH NAME \fIr.combine\fR \- Allows category values from several raster map layers to be combined. .br \fI(GRASS Raster Program)\fR .SH SYNOPSIS \fBr.combine\fR .br \fBr.combine < \fIinputfile\fR .SH DESCRIPTION .I 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 .I 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 .I r.combine analysis. Following this question, the user will see a [1]:. This is the first prompt, and indicates that \fIr.combine\fR is ready to receive input from the user. .PP The following commands perform operations in .I r.combine: .sp .25 .ne 29 .TS c|c|c c|c|c l|l|l. 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)) (grp 2 (owner)) [and] ing a raster map [&][&&] and categories _ OR expression describ- (grp 4 (soils)) (grp 2 (owner)) [or] ing a raster map [| ][| | ] 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] _ .TE .PP .I r.combine uses the same colors for all the operating commands. This is the .I r.combine color table: .RS .TS l l l l. 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 .TE .RE The user may enter commands either line-by-line from within .I 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 \fIr.combine\fR 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 \fIr.combine\fR. .I r.combine uses two types of commands: those which perform operations, and those which have some other function. .PP .I 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: .sp .25 1) 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. .sp .25 2) Certain spaces are important. Generally, .I r.combine requires at least one space before an opening parenthesis (except when it is the first character in an expression). .I r.combine ignores extra spaces and tab characters. .PP OPERATING COMMANDS .PP Below is a summary of the syntax of the operating commands, a description of each command, and examples using the Spearfish sample data base. .PP NAME .br (NAME new_map_name (Expression)) .br .in +.25i Allows graphic output to be saved in the raster map layer \fInew_map_name\fR, 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, \fInew_map_name\fR). Note that this means that \fIr.combine\fR may be used to create new raster map layers from existing ones. .I r.combine automatically creates a color table for the new raster map layers; however, the user should run the GRASS program \fIr.support\fR to fill in category assignments and history information if the new raster map layer is to be saved for future use in the mapset. .ti -.1i example: .sp .25 .B (NAME sandstone (GROUP 4 (geology))) .sp .25 The above command will result in the creation of a new raster map layer named \fIsandstone\fR, noting the locations of cells with \fIgeology\fR category value 4. You must then run the GRASS program \fIr.support\fR in order to label the categories present in the new raster map layer. .sp .25 Resultant categories: .in +.2i .br 0 \- black: other than sandstone .br 1 \- red: sandstone .in -.45i .PP GROUP .br (GROUP category_values (existing raster map layer)) .br .in +.25i 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: .sp .in +.25i .NF 2 1-18 1 2 5-7. .FI .in -.25i .ti -.1i example: .sp .25 .B (GROUP 1-40 (elevation.255)) .sp .25 Depicts only the area with elevation 1187 meters or less (i.e., \fIelevation\fR map layer category values 1 through 40 only). .sp .25 .NF Resultant categories: .in +.2i 0 \- black: elevation > 1187 m 1 \- red : elevation <\*= 1187 m .in -.2i .FI .sp 1 .ti -.1i example: .sp .25 .B (NAME low.hi (GROUP 1-40 238-255 (elevation.255))) .sp .25 Depicts only those areas with elevations of either 1187 meters or less, or in excess of 1787 meters (\fIelevation\fR categories 1-40, and 238-255). The graphic output is saved in the new raster map layer called \fIlow.hi\fR. .sp .25 .NF Resultant categories: .in +.2i 0 \- black : elevation > 1187 m and < 1787 m 1 \- red : elevation <\*= 1187 m and >\*= 1787 m .in -.2i .FI .in -.25i .PP AND .br (AND (Expression A) (Expression B)) .br .in +.25i 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, .B 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. .br For example, .ne 7 .NF 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 .FI .ti -.1i example: .sp .25 .B (AND (GROUP 4 7-9 (geology)) (GROUP 2 (owner))) .sp .25 Depicts the occurrences of categories 4, 7, 8, and 9 from the map layer \fIgeology\fR whenever they occur on U.S. Forest Service property. Results are displayed to the terminal screen. .sp .25 Resultant categories: .sp .25 .NF .in +.2i 0 \- black : no data occurred in one or the other of the raster map layers 1 \- red : the AND condition is met .in -.2i .FI .sp .25 Note that if neither map layer contained any areas of "no data", the resultant raster map layer would include only 1's. .sp 1 .ti -.1i Example: .B .sp .25 (NAME sand (AND (GROUP 4 7-9 (geology)) (GROUP 2 (owner)))) .sp .25 Same as above, except the results are saved in the map layer \fIsand\fR. .in -.25i .PP OR .br (OR (Expression A) (Expression B)) .br .in +.25i 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, .B 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: .NF 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 .FI .ti -.1i Example: .sp .25 .B (OR (GROUP 4 7-9 (geology)) (GROUP 2 (owner))) .sp .25 Depicts all occurrences of categories 4, 7, 8, and 9 from the map layer \fIgeology\fR as well as showing all the land which is U.S. Forest Service property. Results are displayed to the terminal screen. .br Resultant categories: .sp .25 .NF .in +.2i 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 .FI .in -.2i .sp .25 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 .I r.combine command OVER if it is necessary to make that distinction. .ti -.25i NOT (NOT (Expression)) .br Negates \fIExpression\fR in order to define a new map layer which contains the opposite of what is defined by \fIExpression\fR. 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 .I r.combine command NAME. .ti -.1i Example: .sp .25 .B (NAME rds (NOT (GROUP 0 (roads)))) .sp .25 Areas containing category zero in the existing map layer \fIroads\fR 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 \fIrds\fR. .sp .25 Resultant categories: .in +.2i .NF 0 \- black: no roads 1 \- red : roads .FI .in -.2i The same results could have been obtained with: .B (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. .PP .in -.25i OVER .br (OVER color (Expression)) or (OVER existing_rastermap color (Expression)) .br .in +.25i Performs a \fItransparent\fR 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: .sp .25 .NF .in +.2i .B color value red 1 yellow 2 blue 4 grey 8 .in -.2i .FI .sp .25 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 \fIcell\fR (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 .I 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 .I r.combine color table listed above. .TS l l l l. 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 .TE The syntax for OVER makes no provision for a new raster map layer name. It is necessary to use the .I 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. .ti -.1i example: .sp .25 .B (NAME park.or.priv (OVER red (GROUP 1 (owner)))) .sp .25 The new raster map layer \fIpark.or.priv\fR displays private land (i.e., category 1 of the raster map layer \fIowner\fR) in red, and displays U.S. Forest Service land (i.e., "no data" areas within the \fIowner\fR map layer) as black. .sp .25 Resultant categories: .sp .25 .in +.2i .NF 0 \- black: park 1 \- red : private land .FI .in -.2i .ti -.1i example: .sp .25 .B (NAME roads.or.not (OVER park.or.priv yellow (GROUP 0 (roads)))) .sp .25 Category 0 in the map layer \fIroads\fR is overlain in yellow on top of the \fIpark.or.priv\fR map layer created above. The output is placed in a new map layer named \fIroads.or.not\fR. .sp .25 Resultant categories in \fIroads.or.not\fR are: .sp .25 .in +.2i .NF 0 \- black : park; road 1 \- red : private; road 2 \- yellow : park; no road 3 \- orange : private; no road .FI .in -.2i .ti -.1i example: .sp .25 .B (NAME low.elev (OVER park.or.priv blue (GROUP 1-19 (elevation.255)))) .sp .25 The elevation categories of 1123 meters or less from the map layerr \fIelevation.255\fR are assigned the color blue and then overlain on \fIpark.or.priv\fR (generated in the previous example). .sp .25 Resultant categories in the new map layer \fIlow.elev\fR are: .sp .25 .in +.2i .NF 0 \- black : park; > 1123 m 1 \- red : private; > 1123m 4 \- blue : park; <\*= 1123 m 5 \- purple : private; <\*= 1123m .FI .in -.2i .sp .25 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). .in -.25i .PP .ti -.25i COVER .br (COVER existing_map (Expression)) .br Performs an \fIopaque\fR 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 \fIExpression\fR. The bottom map layer is \fIexisting_map\fR; this map layer must already exist. .PP 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: .NF 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 .FI 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 .I r.combine command NAME to save output in a raster map layer. .ti -.1i Example: .sp .25 .RS \fB(NAME lo.elev (COVER owner (GROUP 1-19 (elevation.255)))) \fR .sp .25 .RE The categories that indicate elevation of 1123 meters or less are placed on top of the existing map layer \fIowner\fR. Output is saved in \fIlo.elev\fR. .sp .25 Resultant categories: .in +.2i .NF 1 \- red : private ownership; elev > 1123 m 2 \- yellow : park property; elev > 1123 m 3 \- orange : park or private; elev <\*= 1123 m .in -.2i .ti -.1i .FI Example: .sp .25 .RS \fB(NAME sand.lo (COVER lo.elev (GROUP 4 (geology)))) \fR .RS .sp .25 Category 4 of \fIgeology\fR (sandstone) is placed on top of \fIlo.elev\fR, the raster map layer created in the previous example. The output is saved in \fIsand.lo\fR. .sp .25 .NF Resultant categories: .in +.2i 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 .FI .in -.25i ADDITIONAL COMMANDS .I r.combine also contains a number of commands which are not used for operations, but serve a variety of other functions. Additional commands: .TS c|c|c l|l|l. 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 for which help is needed ERASE erase .TE .ti -.25i QUIT .br Allows the user to exit from .I r.combine while remaining within the GRASS session. .ti -.25i CATS CATS raster map .br Gives user an on-line listing of categories and labels for the map layer specified. For example: .sp .25 .B [1]:CATS owner .ti -.25i EXP EXP expression number .br During an .I 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 \fInumber\fR of the expression for the expression itself. .sp .25 For example: .sp .25 .B [4]:(GROUP 5 (geology)) .br .B [5]:(NAME limestone (EXP 4)) .sp .25 Use the UNIX history mechanism (explained below) to determine the specific numbers associated with particular expressions in your current \fIr.combine\fR session. .ti -.25i ! !shell command .br Allows user to temporarily suspend .I r.combine and go run another command, as in the two examples below: .sp .25 .NF !vi input !g.list type\*=rast .FI .sp .25 Unless otherwise specified by the user, when a file is created using a system editor (like \fIvi\fR) from within .I r.combine, this file will be placed in the user's mapset under the COMBINE directory. After the command is completed, control returns to .I r.combine. .ti -.25i < < input filename .br Takes input from the specified \fIfilename\fR containing .I 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 \fIcomb.in\fR into the \fIr.combine\fR program (while within \fIr.combine\fR): .sp .25 First, the user would create the file: \fB !vi comb.in\fR .br Second, the user would direct \fIr.combine\fR to take its input from the file: \fB < comb.in\fR .ti -.25i WINDOW WINDOW raster_map .br Gives on-line geographic region (window) information about the raster map layer specified. .ti -.25i HISTORY .br Provides a listing of all previously completed expressions used within the current \fIr.combine\fR session, and the numbers associated with the execution of these commands. .ti -.25i HELP HELP command .br An on-line help facility for \fIr.combine\fR commands only. Type in the name of the \fIr.combine\fR command for which help is needed, to see the entry for that command. .ti -.25i ERASE .br Will cause the color graphics monitor to clear. .SH "NOTES" In all of the above examples, only a single line of input was provided to \fIr.combine\fR. However, since \fIr.combine\fR conveniently ignores extra spaces and tabs, it is possible to type input to \fIr.combine\fR 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 \fIr.combine\fR command line, or redirected into \fIr.combine\fR from an already existing file. .NF .ti -.1i example: .sp .25 (NAME good.place (AND (OR (GROUP 1 2 5 (geology)) (GROUP 1-5 (elevation.255)) ) (NOT (GROUP 1-4 (landuse)) ) ) ) .FI Such involved input to \fIr.combine\fR might conveniently be typed into an input file, and then input to \fIr.combine\fR using the UNIX redirection mechanism \fB<\fR . .SH "SEE ALSO" \fBGRASS Tutorial: r.combine\fR .br .I r.infer, .I r.mapcalc, .I r.weight .SH "AUTHORS" L. Van Warren, U.S. Army Construction Engineering Research Laboratory .br Michael Shapiro, U.S. Army Construction Engineering Research Laboratory .br James Westervelt, U.S. Army Construction Engineering Research Laboratory