NAME

d.rast.edit - Program allowing users to interactively edit the cell category values of raster map layers displayed on the graphics monitor.
(GRASS Display Program)

SYNOPSIS

d.rast.edit
d.rast.edit help
d.rast.edit

DESCRIPTION

The d.rast.edit program allows users to interactively edit cell category values in a raster map layer displayed to the graphics monitor using a mouse cursor. This program determines the name of the raster map layer currently displayed in the active frame on the selected graphics monitor (if none, program will abort). The user is then prompted for the name of a new raster layer to be created in his mapset. d.rast.edit does not modify the user's original raster map layer.

Geographic Region Concerns

d.rast.edit reads the region definition for the raster map layer being edited from its cell header file. The new, edited copy of the raster layer will be created with the same resolution and region dimensions. If the current region resolution does not match the raster map layer's resolution, the program will abort. The north, south, east, and west geographic region settings of the current region can be set to any view, as long as they fall within the boundaries of the raster map layer described in its cell header. This is important, since the current view must be such that individual cell locations are easily visible and sufficiently large on the graphics monitor to be pointed at with the mouse cursor. Any mask in place will be ignored when writing the new raster map layer.

Mouse Menus

Cell editing is done using a mouse cursor to choose menu selections and indicate areas on the displayed raster map that are to be edited.

Selections available via the Main Menu and the subsequent functions or sub-menus are described below:

1. Edit
invokes edit mode, during which no graphic menus are used, so that none of the displayed map is hidden. At the start of the edit mode, a grid is drawn over displayed cells to help distinguish cell boundaries. Interaction with the program during edit mode is done by using the three mouse buttons as follows:
Left Button
what's here. Identify the category value of the cell under the mouse cursor when the button is pressed. The category value of this cell is printed in the text frame.

Middle Button
edit. The current category value of the cell under the mouse cursor is iterated and a prompt for a new cell value appears on the textual command frame. (Remember to move the mouse to the text frame). Enter a new cell category value which is within the range of current category values for the map layer. Note: the edited cell is displayed in the color of the newly-assigned category value, but is hatched with lines of the grid color to indicate it has been edited, since, if the value of the cell is polled (before leaving edit mode), the old category value will be reported.

Right Button
exit edit mode. Command is returned to the Main Menu on the graphics monitor. If cell value changes were made during edit mode, they will be saved upon exit.

2. Redraw
redisplays the raster map layer on the graphics monitor.

3. Zoom
calls the d.rast.zoom program, to allow changing the view of the raster layer. Zoom's instructions will appear on the text command window. Interaction is conducted using mouse keys.

4. Arrow
This function is available for users editing aspect maps. The d.rast.arrow program is called, which draws arrows over the displayed cells to indicate the downslope direction of the cell. After selecting the arrow selection from the main menu, sub-menus will appear, allowing input options to be set for the d.rast.arrow program. The first sub-menu selects the type of aspect data displayed. (regular "GRASS" format, as produced by r.slope.aspect ; a format prepared as input to the "AGNPS" program; and a format prepared for the "ANSWERS" program. The d.rast.arrow program can accept the name of a layer not drawn on the display for use as input, and an option is given to input the name of that layer, if desired. Otherwise, the currently displayed map layer will be used. Next, the color options of d.rast.arrow may be set via separate menus, or a choice for using default settings may be used.

5. Number
calls the d.rast.num program, which will print the cell category values over the displayed cells on the graphic monitor.

6. Exit
quit the d.rast.edit program. If edits have been made, the new raster map layer will be created. Support files are constructed. Category labels and color maps (if any) are copied from the original layer. d.rast.edit redisplays the original raster map file on the monitor as it exits.

NOTES

d.rast.edit will not create a new raster map layer if the user makes no cell edits while running the program.

Be careful not to cover the graphics monitor window with another frame during the editing process. In some cases, the redraw option will be able to remove traces of other frames; otherwise, the graphics monitor will not be refreshed until after d.rast.edit exits. Further note, however, that this has only been tested on SUN workstations, using a modified SUNVIEW graphics monitor driver.

The primary bane of the d.rast.edit program involves large map layers (with lots of rows and columns) and/or slow computers, since the program must read and write raster map layers row by row for the full size of the map layer as dictated by its region size and resolution. (The current region settings of north, south, east, and west will not limit the size of the edited copy of the map layer, since by use of the d.rast.zoom program, these values may change several times during the editing session). Their effects could be lessened if the program were to create a table of changes that it could incorporate into the new raster file on a forked process started when the user exits, or otherwise allow the user to issue a "save" command when he has made all desired edits to the raster file. Currently, for instance, if the user needs to use d.rast.zoom to access a different area of the map, he must wait for a read and write for each entrance and egress of the edit mode.

There is no "undo" command or way to exit edit mode without saving changes.

It would be nice to incorporate a scrollable version of d.legend (such that one could see a legend for files with many categories on a standard size sub-frame). It would be even nicer to be able to select the category values from a graphical legend when editing cell values (thereby saving a trip to the text frame to type in the new value).

Perhaps method(s) for multiple or mass cell edits would be useful. This could be done by providing modes in which the user may: 1) edit a block of cells to a given value by drawing a box; 2) be able to choose a given value which is automatically used as the new value on each cell chosen until a different value is desired.

There is no interrupt handling. This could leave files in .tmp or (rarely) result in half-baked raster files. The original file would survive unscathed by an interrupt at most any point in execution, but the graphics monitor may be left in an indeterminate state (try d.erase or d.mon select=monitor_name to bring it back into shape). Beware of exiting the program by means other than using exit on the Main Menu.

The program has no method to enter new values beyond the current range of categories, but additional programming could make it so.

SEE ALSO

d.erase d.frame d.mon d.rast
d.rast.arrow d.rast.num d.rast.zoom d.zoom
g.region r.mask r.slope.aspect

AUTHOR

Chris Rewerts, Agricultural Engineering, Purdue University