NAME

       r.what  - Queries raster map layers on their category values and category labels.

KEYWORDS

       raster, querying

SYNOPSIS

       r.what
       r.what help
       r.what     [-nfric]     input=string[,string,...]      [cache=integer]       [null=string]
       [fs=character]   [east_north=east,north[,east,north,...]]   [--verbose]  [--quiet]

   Flags:
       -n
           Output header row

       -f
           Show the category labels of the grid cell(s)

       -r
           Output color values as RRR:GGG:BBB

       -i
           Output integer category values, not cell values

       -c
           Turn on cache reporting

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=string[,string,...]
           Name of existing raster map(s) to query

       cache=integer
           Size of point cache
           Default: 500

       null=string
           Char string to represent no data cell
           Default: *

       fs=character
           Field separator
           Special characters: newline, space, comma, tab
           Default: |

       east_north=east,north[,east,north,...]
           Coordinates for query

DESCRIPTION

       r.what outputs the category values and (optionally) the category  labels  associated  with
       user-specified  locations  on  raster input map(s).  Locations are specified as geographic
       x,y  coordinate  pairs  (i.e.,  pair  of  eastings  and  northings);  the  user  can  also
       (optionally) associate a label with each location.

       The input coordinates can be entered directly on the command line, or redirected via stdin
       from an input text file, script, or piped from another program (like d.where).

       If none of the above input methods are used and  the  module  is  run  from  the  terminal
       prompt, the program will interactively query the user for point locations and labels.

       Each  line  of  the input consists of an easting, a northing, and an optional label, which
       are separated by spaces. In interactive mode, the word "end" must be typed after the  last
       pair of input coordinates.

       r.what  output  consists  of  the input geographic location and label, and, for each user-
       named raster map layer, the category value, and (if the -f label flag  is  specified)  the
       category label associated with the cell(s) at this geographic location.

EXAMPLES

   Input from stdin on the command line
       Input coordinates may be given directly from stdin, for example:
        (input data appears between the "EOF" markers)
       r.what input=soils,aspect << EOF
       635342.21 7654321.09 site 1
       653324.88 7563412.42 site 2
       EOF
       635342.21|7654321.09|site 1|45|21
       653324.88|7563412.42|site 2|44|20

       echo "635342.21 7654321.09" | r.what input=soils,aspect
       635342.21|7654321.09|45|21

   Input from a text file containing coordinates
       The  contents  of  an ASCII text file can be redirected to r.what as follows. If we have a
       file called input_coord.txt containing the coordinates and labels  given  in  the  example
       above:
       r.what input=soils,aspect < input_coord.txt
       635342.21|7654321.09|site 1|45|21
       653324.88|7563412.42|site 2|44|20

   Input coordinates given as a module option
       The  module's  east_north  parameter  can  be used to enter coordinate pairs directly. The
       maximum number of pairs will be limited by your system's maximum input line  length  (e.g.
       4096 characters).
       r.what input=soils,aspect east_north=635342.21,7654321.09,653324.88,7563412.42
       635342.21|7654321.09|45|21
       653324.88|7563412.42|44|20

   Input coordinates piped from another program
       The input coordinates may be "piped" from the stdout of another program.  For example:
       d.where | r.what input=soils,aspect
       635342.21|7654321.09|45|21
       653324.88|7563412.42|44|20
        In the next example, vector point coordinates are piped from the v.out.ascii module . The
       standard UNIX program "tr" is used to  convert  the  column  separators  in  v.out.ascii's
       output into spaces for r.what.
       v.out.ascii bugsites fs=' ' | r.what input=soils,aspect

   Output containing raster map category labels
       Here  we use the -f label flag to enable the output of category labels associated with the
       raster cell(s), as well as values. (categorical maps only)
       r.what -f input=soils,aspect << EOF
       635342.21 7654321.09 site 1
       653324.88 7563412.42 site 2
       EOF
       635342.21|7654321.09|site 1|45|NaC|21|30 degrees NW
       653324.88|7563412.42|site 2|44|NdC|20|15 degrees NW

NOTE

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

SEE ALSO

         d.where,  r.category,  r.report,  r.stats,  r.series,  r.univar,  v.what,   v.what.rast,
       v.what.vect

AUTHOR

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

       Last changed: $Date: 2010-09-16 00:25:59 -0700 (Thu, 16 Sep 2010) $

       Full index

       © 2003-2013 GRASS Development Team