r.category(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 r.category — the manual, but make it make sense 💖

okay bestie, so r.category is from the GRASS User's Manual — it's the glow-up tool for your raster map's category values and labels. she's giving organization, she's giving aesthetic, she's giving "your legend could NEVER". let's get into it 🫶

✨ NAME ✨

r.category — manages category values and labels associated with user-specified raster map layers. basically she's the keeper of the vibes for your raster's little name tags 💅

🌸 KEYWORDS 🌸

raster, category — iykyk 👑

💫 SYNOPSIS 💫

r.category
r.category --help
r.category map=name  [cats=range[,range,...]]
[values=float[,float,...]]   [separator=character]   [raster=name]
[rules=name]   [format=string]   [label_format=string]
[coefficients=mult1,offset1,mult2,offset2]   [color_format=name]
[--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • --help — prints the usage summary, aka the cheat sheet, no cap
  • --verbose — verbose module output (she's chatty, we love her)
  • --quiet — quiet module output (she's giving stealth mode 🤫)
  • --ui — forces launching a GUI dialog, for when you want the pretty buttons

🌈 Parameters 🌈

  • map=name [required] — name of the raster map. this one is NOT optional bestie, she needs to know who she's working with 🗺️
  • cats=range[,range,...] — category values. example: 1,3,7-9,13
  • values=float[,float,...] — comma separated value list. example: 1.4,3.8,13
  • separator=character — field separator. special characters: pipe, comma, space, tab, newline. default: tab
  • raster=name — raster map from which to copy category table (borrowing her fit, respectfully)
  • rules=name — file containing category label rules (or "-" to read from stdin)
  • format=string — output format ('plain', 'json'). when the value is not 'plain' or 'json', the value is used as a default label or format string for dynamic labeling. this usage is deprecated and will be removed in a future release. use parameter 'label_format' instead. ⚠️
  • label_format=string — default label or format string for dynamic labeling. used when no explicit label exists for the category
  • coefficients=mult1,offset1,mult2,offset2 — dynamic label coefficients. two pairs of category multiplier and offsets, for $1 and $2
  • color_format=name — color format. color format for output values or none. options: none, rgb, hex, triplet, hsv. default: none
    • rgb: output color in RGB format
    • hex: output color in HEX format
    • triplet: output color in colon-separated RGB format
    • hsv: output color in HSV format (experimental — handle with care babes 🧪)

💅 DESCRIPTION 💅

okay so r.category prints the category values and labels for the raster map layer you specified with map=name straight to standard output. and yes, you can ALSO use it to set category labels for a raster map. she does both, she's versatile, main character energy fr fr ✨

you can specify all the needed parameters right there on the command line and run the program non-interactively — no hand-holding required. if you don't specify any categories (like, say, by using the optional cats=range[,range,...] argument), then she prints ALL the category values and labels for the named raster map layer that actually occur in the map. the entire map gets read using r.describe to figure out which categories occur in the map. if you do specify a listing of categories, then only the labels for those categories get printed. the cats can be single category values, or ranges of values. you may also (optionally) specify that a field separator other than a space or tab be used to separate the category value from its corresponding category label in the output, by using the separator=character|space|tab option (see example below). and if you don't specify a field separator at all? tab it is, by default. periodt 💁‍♀️

the output goes to standard output in the form of one category per line, with the category value first on the line, then an ASCII TAB character (or whatever single character or space you specified using the separator parameter), then the label for the category. clean, simple, iconic.

🌟 NOTES 🌟

any ASCII TAB characters that might be hiding in the label get replaced by spaces. no rogue tabs on her watch 🚫

the output from r.category can be redirected into a file, or piped into another program. go off, pipeline queen 🔥

📄 Input from a file

the rules option lets you assign category labels from values found in a file (no header, we don't do headers here). the label can refer to a single category, a range of categories, a floating point value, or a range of floating point values. the format goes like this (when separator is set to colon; no white space must be used after the separator, that's the rule bestie):

cat:Label
val1:val2:Label

if the filename is given as "-", the category labels are read from stdin 🫶

🔮 Default and dynamic category labels

default and dynamic category labels can be created for categories that aren't explicitly labeled. the coefficient line can be followed by explicit category labels which override the format label generation.

   0:no data
   2:   .
   5:   .               ## explicit category labels
   7:   .

explicit labels can be also of the form:

   5.5:5:9 label description
   or
   15:30  label description

in the format line:

  • $1 refers to the value num*5.0+1000 (ie, using the first 2 coefficients)
  • $2 refers to the value num*5.0+1005 (ie, using the last 2 coefficients)

$1.2 will print $1 with 2 decimal places. precision slay ✨

also, the form $?xxx$yyy$ translates into yyy if the category is 1, xxx otherwise. the $yyy$ is optional. thus:

$1 meter$?s

will become:

1 meter (for category 1)
2 meters (for category 2), etc.

like, grammar?? she has it 💅

format='Elevation: $1.2 to $2.2 feet'   ## Format Statement
coefficients="5.0,1000,5.0,1005"   ## Coefficients

the format and coefficients above would be used to generate the following statement in creation of the format appropriate category string for category "num":

sprintf(buff,"Elevation: %.2f to %.2f feet", num*5.0+1000, num*5.0*1005)
Note: while both the format and coefficient lines must be present, a blank line for the format string will effectively suppress automatic label generation. so don't leave her hanging with an empty format line and expect magic, bestie 😭

to use a "$" in the label without triggering the plural test, put "$$" in the format string. escaped, protected, untouchable 💖

use 'single quotes' when using a "$" on the command line to avoid unwanted shell substitution. protect your dollars, protect your peace 🌸

🦋 EXAMPLES 🦋

North Carolina sample dataset, because of course, we love a classic:

🏷️ Printing categories

r.category map=landclass96
1    developed
2    agriculture
3    herbaceous
4    shrubland
5    forest
6    water
7    sediment

prints the values and labels associated with all of the categories in the landclass96 raster map layer. the full roster, no skips 💜

r.category map=landclass96 cats=2,5-7
2    agriculture
5    forest
6    water
7    sediment

prints only the category values and labels for landclass96 map layer categories 2 and 5 through 7. selective ✨

r.category map=landclass96 cats=3,4 separator=comma
3,herbaceous
4,shrubland

prints the values and labels for landclass96 map layer categories 3 and 4, but uses "," (instead of a tab) as the character separating the category values from the category values in the output. comma era 🍓

r.category map=landclass96 cats=3,4 format=json

generates the following JSON output:

[
    {
        "category": 3,
        "label": "herbaceous"
    },
    {
        "category": 4,
        "label": "shrubland"
    }
]

structured, formatted, lowkey gorgeous 🌈

➕ Adding categories

example for defining new category labels, using a colon as separator:

r.category diseasemap separator=":" rules=- << EOF
1:potential absence
2:potential presence
EOF

this sets the category values 1 and 2 to respective text labels. alternatively, the rules can be stored in an ASCII text file and loaded via the rules parameter. whatever's easier for you babes 🎀

👀 SEE ALSO 👀

UNIX Manual entries for awk and sort — the OGs, we respect them 🫡

d.what.rast, r.coin, r.describe, r.support — the whole friend group, go say hi 💕

👑 AUTHORS 👑

  • Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
  • Hamish Bowman, University of Otago, New Zealand (label creation options)

legends, both of them, no notes 🌟

💻 SOURCE CODE 💻

Available at: r.category source code (history)

Latest change: Saturday Oct 11 04:38:40 2025 in commit: 3dd71f5fab83b72a2db2da959fe075c5b3b52200

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

okay and that's the whole page bestie!! 🩷 this was GRASS 8.5.0, page r.category(1grass), and yes she ATE. now go label your rasters, go pipe things into files, go be the main character of your own terminal. mwah 💋✨🦋

📦 where this page comes from