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  dis-
       played 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 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 dis-
       played  in the active frame on the selected graphics moni-
       tor (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  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.

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 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
       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  win-
       dow.  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 direc-
       tion 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.  (reg-
       ular "GRASS" format, 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.  Other-
       wise, 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  redis-
       plays  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  worksta-
       tions, 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  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 cur-
       rent 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 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" com-
       mand 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  with-
       out 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 cat-
       egories	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)
