r.what(1grass)

💖 r.what — the GRASS User's Manual glow-up 💖

okay bestie, sit DOWN, because r.what is about to become your new favorite module. it's the one that goes "hey raster map, what's ur deal at this exact spot on the planet" and the map actually answers. it lives in the GRASS User's Manual, and its whole personality is raster, querying, position. 🦋

---

✨ NAME ✨

r.what — it queries raster maps on their category values and their category labels. that's the whole job. it asks, the raster answers, we move on. periodt. 💅

🏷️ KEYWORDS 🏷️

raster, querying, position — that's the vibe check, passed with flying colors. 🌈

📜 SYNOPSIS 📜

r.what
r.what --help
r.what [-nfricv] map=name[,name,...]  [coordinates=east,north]
[points=name]   [null_value=string]   [output=name]
[separator=character]  format=name  [cache=integer]   [--overwrite]
[--help]  [--verbose]  [--quiet]  [--ui]

look at her. look at the little flags up front, the parameters in brackets, the -- crew at the end. iconic behavior honestly. 🎀

🚩 Flags 🚩

• -n — output a header row. yes queen, give the columns names, we deserve to know what we're reading.
• -f — show the category labels of the grid cell(s). the human-readable glow-up of the raw number.
• -r — output color values as RRR:GGG:BBB. rgb girlies rise up. 🎨
• -i — output integer category values, not cell values. like, the category, not the number.
• -c — turn on cache reporting. she's telling you how the cache is doing, no secrets here.
• -v — show the category for the vector points map. cat values for the points, bestie.
• --overwrite — allow output files to overwrite existing files. careful, she WILL delete ur old file fr fr. 😭
• --help — print usage summary.
• --verbose — verbose module output. she talks more. we love that for her.
• --quiet — quiet module output. she talks less. also valid.
• --ui — force launching GUI dialog. for when u want buttons instead of typing. 🫶

🧚 Parameters 🧚

• map=name[,name,...] [required] — name of existing raster map(s) to query. yes u can pass a whole list, she's flexible like that. required, so don't ghost her.
• coordinates=east,north — coordinates for query. drop the exact spot(s) u want to interrogate.
• points=name — name of vector points map for query. can also be a data source for direct OGR access.
• null_value=string — string representing the NULL value. default: *. (yes, a literal asterisk, she said what she said.)
• output=name — name for output file. if u omit it, or pass -, it goes to stdout. classic.
• separator=character — field separator. special characters: pipe, comma, space, tab, newline. default: pipe. 🍓
• format=name [required] — output format. options: plain, json. default: plain.
  • plain: Plain text output
  • json: JSON (JavaScript Object Notation) — for when ur piping it into something that speaks JSON, iykyk.
• cache=integer — size of point cache. default: 500.

---

🌸 DESCRIPTION 🌸

okay so here's the tea. r.what outputs the category values and (optionally) the category labels associated with user-specified locations on raster input map(s). you pick the spots, she reads the maps at those spots. match made in heaven. 💖

Locations are specified as geographic x,y coordinate pairs — that's a pair of eastings and northings, for the cartography besties. and the user can also (optionally) associate a label with each location, so u can name ur little spots like the main character u are. 👑

The input coordinates can be entered directly on the command line via the coordinates parameter, or redirected via stdin from an input text file, a script, or piped from another program (like v.out.ascii — she's everywhere). Coordinates can ALSO be given as a vector points map (points). three whole ways in, she's not picky.

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. yes, she'll just ask u. conversation style. 🗣️

Each line of the input consists of an easting, a northing, and an optional label, which are separated by spaces. and in interactive mode, the word "end" must be typed after the last pair of input coordinates. type end. that's the signal. don't leave her hanging.

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. boom. that's the whole output pipeline.

---

💅 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). okay so line length is the ceiling, keep it cute and keep it short. ✨

g.region raster=landuse96_28m,aspect -p
r.what map=landuse96_28m,aspect coordinates=633614.08,224125.12,632972.36,225382.87 -f
633614.08|224125.12||2|Low Intensity Developed|209.5939|209 degrees ccw from east
632972.36|225382.87||15|Southern Yellow Pine|140.7571|140 degrees ccw from east

📍 Input coordinates given as a vector points map

Coordinates can be read from an existing vector points map by specifying the points option. Other features than points or centroids are ignored — she only wants the pointy ones, sorry. Example: query North Carolina county number for each community college:

g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges
145096.859150|154534.264884||39
616341.437150|146049.750884||51
...

📍 Input coordinates given as a vector points map with cats

Same deal — Coordinates can be read from an existing vector points map by specifying the points option. Other features than points or centroids are ignored. Using the v flag you can get also the cat for each feature. Example: query North Carolina county number for each community college:

g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges -v
1|145096.859150|154534.264884||39
2|616341.437150|146049.750884||51
...

📍 Input coordinates given as a vector points map, output into CSV file

Coordinates can be read from an existing vector points map by specifying the points option. Other features than points or centroids are ignored. The output is stored in a CSV file including a header row. Example: query North Carolina county number for each community college:

g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges \
       separator=comma output=result.csv -n
cat result.csv
easting,northing,site_name,boundary_county_500m
145096.859150,154534.264884,,39
616341.437150,146049.750884,,51
410595.719150,174301.828884,,71
...

📍 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 whitespace separated coordinates and optionally labels, the resulting raster map values are extracted:

cat input_coord.txt
633614.08 224125.12 site 1
632972.36 225382.87 site 2
r.what map=landuse96_28m,aspect < input_coord.txt
633614.08|224125.12|site 1|2|209.5939
632972.36|225382.87|site 2|15|140.7571

📍 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=landuse96_28m,aspect << EOF
633614.08 224125.12 site 1
632972.36 225382.87 site 2
EOF
633614.08|224125.12|site 1|2|209.5939
632972.36|225382.87|site 2|15|140.7571
echo "633614.08 224125.12" | r.what map=landuse96_28m,aspect
633614.08|224125.12||2|209.5939

📍 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. teamwork makes the dream work, fr fr. 🤝

v.out.ascii comm_colleges separator=space | r.what map=boundary_county_500m
145096.8591495|154534.26488388|1|39
616341.4371495|146049.75088388|2|51
410595.7191495|174301.82888388|3|71
...

🏷️ 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). yes bestie, labels are for the categorical girlies. 💅

r.what -f map=landuse96_28m,aspect << EOF
633614.08 224125.12 site 1
632972.36 225382.87 site 2
EOF
633614.08|224125.12|site 1|2|Low Intensity Developed|209.5939|209 degrees ccw from east
632972.36|225382.87|site 2|15|Southern Yellow Pine|140.7571|140 degrees ccw from east

---

⚠️ NOTE ⚠️

The maximum number of raster map layers that can be queried at one time is 400. four hundred. that's the limit. don't push her past 400, she's doing her best. 😭

📝 TODO 📝

• Fix 400 maps limit

yeah. it's on the list. she knows. we know. someday. 🙈

👀 SEE ALSO 👀

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

(the whole friend group, honestly. go say hi. 🫶)

👑 AUTHORS 👑

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory Vector point input added by Martin Landa, Czech Technical University in Prague, Czech Republic

legends. absolute icons. we stan. ✨

💻 SOURCE CODE 💻

Available at: r.what source code (history)

Latest change: Monday Dec 22 18:07:47 2025 in commit: cd86ea812e29ba28776cf5a102bf59288f49ce41

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

---

and that's the whole page bestie!! 🎀 this was r.what(1grass) from the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team, and the manual page itself is stamped GRASS 8.5.0 down at the bottom — go query something cute, ur raster maps believe in u. 💖🦋✨