## 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 via coordinates paramater, or redirected via `stdin` from an input text file, script, or piped from another program (like v.out.ascii). Coordinates can be given also as a vector points map (points).

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 coordinates given as an option

The module's coordinates 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).

    g.region rast=soils,aspect
    r.what map=soils,aspect coordinates=635342.21,7654321.09,653324.88,7563412.42

    635342.21|7654321.09|45|21
    653324.88|7563412.42|44|20

### Input coordinates given as a vector points map

Coordinates can be read from exising vector points map by specifing points option. Other features then points or centroids are ignored.

    r.what map=soils,aspect points=bugsites

### 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 map=soils,aspect < input_coord.txt

    635342.21|7654321.09|site 1|45|21
    653324.88|7563412.42|site 2|44|20

### Input from standard input on the command line

Input coordinates may be given directly from standard input (`stdin`), for example (input data appears between the "`EOF`" markers):

    r.what map=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 map=soils,aspect

    635342.21|7654321.09|45|21

### Input coordinates piped from another program

The input coordinates may be "piped" from the standard output (`stdout`) of another program. In the next example, vector point coordinates are piped from the v.out.ascii module.

    v.out.ascii bugsites separator=space | r.what map=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 map=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.

## TODO

- Add file option

## SEE ALSO

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
Vector point input added by Martin Landa, Czech Technical University in Prague, Czech Republic

Last changed: $Date$