.TH d.what.rast 1grass "" "GRASS 6.4.2" "Grass User's Manual"
.SH NAME
\fI\fBd.what.rast\fR\fR  - Allows the user to interactively query the category contents of multiple raster map layers at user specified locations within the current geographic region.
.SH KEYWORDS
display, raster
.SH SYNOPSIS
\fBd.what.rast\fR
.br
\fBd.what.rast help\fR
.br
\fBd.what.rast\fR [-\fB1tc\fR] \fBmap\fR=\fIname\fR[,\fIname\fR,...]  [\fBfs\fR=\fIcharacter\fR]   [--\fBverbose\fR]  [--\fBquiet\fR] 
.SS Flags:
.IP "\fB-1\fR" 4m
.br
Identify just one location
.IP "\fB-t\fR" 4m
.br
Terse output. For parsing by programs
.IP "\fB-c\fR" 4m
.br
Print out col/row for the entire map in grid resolution of the region
.IP "\fB--verbose\fR" 4m
.br
Verbose module output
.IP "\fB--quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBmap\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Name of existing raster map(s)
.IP "\fBfs\fR=\fIcharacter\fR" 4m
.br
Field separator (terse mode only)
.br
Default: \fI:\fR
.PP
.SH DESCRIPTION
\fId.what.rast\fR outputs the category values and labels
associated with cell(s) at user-specified location(s) on
user-named raster map layer(s).
.PP
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 command
line, \fId.what.rast\fR will query the category contents
of whatever raster map layer is already displayed in the
active frame on the graphics monitor.
.PP
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.
.SH EXAMPLE
It is helpful, but not necessary, to first display a map to
be used for reference in the active display frame before
running \fId.what.rast\fR.  For example, the user might
type the following series of commands and receive the
output below.
.PP
.IP "\fBd.rast map=\fR\fIsoils\fR" 4m
.PP
.br
To first display the \fIsoils\fR map in the active frame.
.PP
.PP
.IP "\fBd.what.rast map=\fR\fIsoils,aspect\fR" 4m
.PP
.br
User then moves the mouse to desired location on the
displayed \fIsoils\fR map layer, and presses the left
mouse button to query the category contents of the
\fIsoils\fR and \fIaspect\fR maps at this geographic
location.  The program then outputs the below information
to the user's terminal.
.PP
\fC
.DS
.br
617112(E) 3732014(N) 
.br
soils in PERMANENT (44)Nunn clay loam, NdC 
.br
aspect in PERMANENT (20)15 degrees north of west 
.br
.DE
\fR
.PP
The first line of output gives the easting (E) and northing (N) coordinates 
of the geographic location at which the user clicked the mouse. 
Subsequent lines give the selected map(s) name and mapset, map category value 
(within parentheses), and map category label corresponding to this 
user-selected map location. 
.PP
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 \fId.what.rast\fR session.
.PP
Users can set the \fB-t\fR flag to obtain a terse output
from \fId.what.rast\fR.  This is useful when the user
wishes output to be parsed by another program (like
\fIawk\fR). If the \fB-t\fR flag is set, users can also
select the field separator used (with the
\fBfs=\fR\fIname\fR option), or elect to use the
default \fB:\fR field separator.  In this case, the
command
.PP
.IP "\fBd.what.rast -t map=\fR\fIsoils,aspect\fR
.PP
.br
 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.
.PP
\fC
.DS
.br
617112:3732014:1 
.br
soils@PERMANENT:44:Nunn clay loam, NdC 
.br
aspect@PERMANENT:20:15 degrees north of west 
.br
.DE
\fR
.PP
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
\fId.what.rast\fR only once, and return only the map
category value found and the number of the mouse button
depressed.
.SH NOTES
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.
.PP
\fId.what.rast\fR will always print its output to the
terminal screen.  \fId.what.rast\fR 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:
.PP
.IP "\fBd.what.rast map=\fR\fIsoils,aspect\fR\fB > what.out\fR 
.PP
.br
will both send \fId.what.rast\fR output to the screen
and capture its output in the file named
\fIwhat.out\fR.
.PP
.PP
The maximum number of raster map layers that can be queried at one time is 15.
.PP
\fId.what.vect\fR
allows the user to interactively query the category
contents of multiple vector map layers at user-specified
locations.
.SH SEE ALSO
\fId.rast\fR
.br
\fId.what.vect\fR
.br
\fIg.region\fR
.br
.SH AUTHOR
Michael Shapiro, 
U.S. Army Construction Engineering 
Research Laboratory
.PP
\fILast changed: $Date: 2012-02-06 12:02:12 +0100 (Mon, 06 Feb 2012) $\fR
.PP
Full index
.PP
© 2003-2011 GRASS Development Team