d.rast.edit(1)		      Grass User's Manual		d.rast.edit(1)



NNAAMMEE
	dd..rraasstt..eeddiitt   -  Program allowing users to interactively edit the cell
       category values of raster map layers displayed on the graphics monitor.
       _(_G_R_A_S_S _D_i_s_p_l_a_y _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       dd..rraasstt..eeddiitt
       dd..rraasstt..eeddiitt hheellpp
       dd..rraasstt..eeddiitt

DDEESSCCRRIIPPTTIIOONN
       The  _d_._r_a_s_t_._e_d_i_t  program allows users to interactively edit cell cate-
       gory 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_._r_a_s_t_._e_d_i_t  does  not  modify the user's original raster map
       layer.

GGeeooggrraapphhiicc RReeggiioonn CCoonncceerrnnss
       _d_._r_a_s_t_._e_d_i_t 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 cur-
       rent view must be such that individual cell locations are easily  visi-
       ble  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.

MMoouussee MMeennuuss
       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 _M_a_i_n _M_e_n_u and the subsequent functions  or
       sub-menus are described below: 1. Edit
       iinnvvookkeess eeddiitt mmooddee, 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
       wwhhaatt''ss  hheerree.   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
       eeddiitt.  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  com-
       mand  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
       eexxiitt  eeddiitt  mmooddee.  Command is returned to the _M_a_i_n _M_e_n_u on the graphics
       monitor.  If cell value changes were made during edit mode,  they  will
       be saved upon exit.



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


       3. Zoom
       calls the _d_._z_o_o_m
	program,  to  allow  changing  the  view  of the raster layer.	ZZoooomm''ss
       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_._r_a_s_t_._a_r_r_o_w program is called, which draws arrows over	the  displayed
       cells to indicate the downslope direction of the cell.  After selecting
       the _a_r_r_o_w selection from the main menu, sub-menus will appear, allowing
       input  options  to be set for the _d_._r_a_s_t_._a_r_r_o_w program.	The first sub-
       menu selects the type of aspect data displayed.	(regular "GRASS"  for-
       mat,  as produced by _r_._s_l_o_p_e_._a_s_p_e_c_t ; a format prepared as input to the
       "AGNPS" program; and a format prepared for the "ANSWERS"  program.  The
       _d_._r_a_s_t_._a_r_r_o_w  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_._r_a_s_t_._a_r_r_o_w may be  set  via
       separate menus, or a choice for using default settings may be used.


       5. Number
       calls the _d_._r_a_s_t_._n_u_m program, which will print the cell category values
       over the displayed cells on the graphic monitor.


       6. Exit
       qquuiitt the _d_._r_a_s_t_._e_d_i_t 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_._r_a_s_t_._e_d_i_t  redisplays	the original raster map file on the monitor as
       it exits.


NNOOTTEESS
       _d_._r_a_s_t_._e_d_i_t 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 _r_e_d_r_a_w option  will  be
       able to remove traces of other frames;  otherwise, the graphics monitor
       will not be refreshed until after  _d_._r_a_s_t_._e_d_i_t  exits.	Further  note,
       however,  that  this  has only been tested on _S_U_N workstations, using a
       modified _S_U_N_V_I_E_W graphics monitor driver.


       The primary bane of the _d_._r_a_s_t_._e_d_i_t program involves large  map	layers
       (with  lots  of rows and columns) and/or slow computers, since the pro-
       gram 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_._z_o_o_m program, these values may change several times during the  edit-
       ing  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_._z_o_o_m 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_._l_e_g_e_n_d

       (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_._e_r_a_s_e
	or  _d_._m_o_n _s_e_l_e_c_t_=_m_o_n_i_t_o_r___n_a_m_e to bring it back into shape).  Beware of
       exiting the program by means other than using _e_x_i_t on the _M_a_i_n _M_e_n_u.




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

SSEEEE AALLSSOO
       _d_._e_r_a_s_e	_d_._f_r_a_m_e  _d_._m_o_n	_d_._r_a_s_t _d_._r_a_s_t_._a_r_r_o_w _d_._r_a_s_t_._n_u_m _d_._z_o_o_m _g_._r_e_g_i_o_n
       _r_._m_a_s_k _r_._s_l_o_p_e_._a_s_p_e_c_t

AAUUTTHHOORR
       Chris Rewerts, Agricultural Engineering, Purdue University

       _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_3 _$



GRASS 5.0							d.rast.edit(1)
