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



NNAAMMEE
       _d_._w_h_a_t_._r_a_s_t   - Allows the user to interactively query the
       category contents of multiple raster map layers	at  user-
       specified  locations within the current geographic region.
       _(_G_R_A_S_S _D_i_s_p_l_a_y _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       dd..wwhhaatt..rraasstt
       dd..wwhhaatt..rraasstt hheellpp
       dd..wwhhaatt..rraasstt [--11ttcc] [mmaapp==_n_a_m_e[,_n_a_m_e,...]]  [ffss==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _d_._w_h_a_t_._r_a_s_t outputs the category values and labels associ-
       ated  with  cell(s) at user-specified location(s) on user-
       named raster map layer(s).


       The program will query the contents of raster map layer(s)
       named  by  the  user on the command line. These map layers
       must exist in the user's current mapset search  path.   If
       the  user  does not name any raster map layers on the com-
       mand line, _d_._w_h_a_t_._r_a_s_t will query the category contents of
       whatever  raster  map  layer  is  already displayed in the
       active frame on the graphics monitor.


       The program activates the mouse, and expects the  user  to
       indicate  the cell location(s) to be queried by depressing
       a mouse button over desired location(s) within the current
       geographic  region  in  the  active  display  frame on the
       graphic monitor.

OOPPTTIIOONNSS
   FFllaaggss::
       --11     Identify and query just one  point  location.  Only
	      one  mouse  click  is executed. This option is pro-
	      vided for shell scripts and programs that  want  to
	      obtain only one point from the user.

       --tt     Provide  only terse output. This option is provided
	      to simplify the parsing of  output  by  other  pro-
	      grams.

       --cc     Print out column and row for entire map region.


   PPaarraammeetteerrss::
       mmaapp==_n_a_m_e
	      Name  of	existing  raster  map layer(s). Limit: 15
	      maps
	      Default:	Query  map  currently  displayed  in  the
	      active graphics frame.

       ffss==_n_a_m_e
	      Output  field  separator	to be used (in terse mode
	      only).
	      Default: ::



       _d_._w_h_a_t_._r_a_s_t output consists of the geographic  coordinates
       of  the	location pointed to, and, for each map layer, the
       map layer name, the category value, and category label  in
       the named raster map layers at this location.

EEXXAAMMPPLLEE
       It  is  helpful, but not necessary, to first display a map
       to be used for  reference  in  the  active  display  frame
       before  running	_d_._w_h_a_t_._r_a_s_t.  For example, the user might
       type the following series of commands and receive the out-
       put below.

       dd..rraasstt mmaapp==_s_o_i_l_s
	      To first display the _s_o_i_l_s map in the active frame.


       dd..wwhhaatt..rraasstt mmaapp==_s_o_i_l_s_,_a_s_p_e_c_t User then moves the mouse  to
       desired	location  on  the  displayed _s_o_i_l_s map layer, and
       presses the left mouse button to query the  category  con-
       tents  of  the  _s_o_i_l_s  and  _a_s_p_e_c_t maps at this geographic
       location.  The program then outputs the below  information
       to the user's terminal.

       617112(E) 3732014(N)
       soils in PERMANENT (44)Nunn clay loam, NdC
       aspect in PERMANENT (20)15 degrees north of west



       The  first  line  of output gives the easting (E) and nor-
       thing (N) coordinates of the geographic location at  which
       the user clicked the mouse.  The subsequent two lines give
       the map name and mapset, map category value (within paren-
       theses),  and  map  category  label  corresponding to this
       user-selected map location, for each of the  maps  queried
       by the user.


       The  query  may	be repeated as often as desired using the
       left mouse button.  The right button on the mouse is  used
       to quit the _d_._w_h_a_t_._r_a_s_t session.


       Users  can  set	the --tt flag to obtain a terse output from
       _d_._w_h_a_t_._r_a_s_t.  This is useful when the user  wishes  output
       to be parsed by another program (like _a_w_k). If the --tt flag
       is set, users can also select  the  field  separator  used
       (with  the  ffss==_n_a_m_e option), or elect to use the default ::
       field separator.  In this case, the command

       dd..wwhhaatt..rraasstt --tt mmaapp==_s_o_i_l_s_,_a_s_p_e_c_t

       produces output in the form shown below. The first line of
       output  gives  the easting, northing, and the mouse button
       return value (see  NOTES  below).   Each  subsequent  line
       gives the map name and its mapset, the category value, and
       category label of the point specified  on  the  user-named
       raster  map layers.  The default output field separator, a
       colon, is used since none was  specified  on  the  command
       line.

       617112:3732014:1
       soils@PERMANENT:44:Nunn clay loam, NdC
       aspect@PERMANENT:20:15 degrees north of west




       Users  can  also  use this program inside of shell scripts
       that require as input a map category  value  and  a  mouse
       button  depressed.   Users  can	choose	an  option to run
       _d_._w_h_a_t_._r_a_s_t only once, and return only  the  map  category
       value  found and the number of the mouse button depressed.

NNOOTTEESS
       Mouse button return values are as follows: 0 indicates  no
       button was pressed, 1 indicates that the left mouse button
       was pressed, 2 indicates the middle  button  was  pressed,
       and 3 indicates that the right mouse button was pressed.


       _d_._w_h_a_t_._r_a_s_t  will  always print its output to the terminal
       screen.	_d_._w_h_a_t_._r_a_s_t output can be redirected into a file;
       however,  if  it is, the output will go both to the screen
       and   to   the	 file.	   For	  example:    dd..wwhhaatt..rraasstt
       mmaapp==_s_o_i_l_s_,_a_s_p_e_c_t >> wwhhaatt..oouutt

       will  both  send _d_._w_h_a_t_._r_a_s_t output to the screen and cap-
       ture its output in the file named _w_h_a_t_._o_u_t.


       The maximum number  of  raster  map  layers  that  can  be
       queried at one time is 15.


       _d_._w_h_a_t_._v_e_c_t  allows  the  user  to interactively query the
       category contents of multiple vector map layers	at  user-
       specified locations.

SSEEEE AALLSSOO
       _d_._r_a_s_t

       _d_._w_h_a_t_._v_e_c_t

       _d_._w_h_e_r_e

       _g_._r_e_g_i_o_n

       _p_a_r_s_e_r

AAUUTTHHOORR
       Michael	 Shapiro,   U.S.  Army	Construction  Engineering
       Research Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_1_9 _0_9_:_1_2_:_5_8 _$



GRASS 5.0					   d.what.rast(1)
