r.category(1)

📦

version 8.4.2 · 8 versions

r.category 💖 (the GRASS GIS one, bestie)

ok so real talk, this is the GRASS GIS User's Manual page for r.category — it's giving "I manage your raster categories and I do it flawlessly" energy. iykyk. ✨

KEYWORDS: raster, category 🎀

✨ SYNOPSIS ✨

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

🚩 Flags 🚩

--help — prints the usage summary, aka the vibe check for how to use this thing
--verbose — verbose module output, she's chatty 💬
--quiet — quiet module output, she's giving mysterious 🤫
--ui — forces the GUI dialog to launch, main character energy only 👑

🧚 Parameters 🧚

map=name [required] — name of the raster map. yes bestie it's required, you cannot skip it 😭
cats=range[,range,...] — the category values. Example: 1,3,7-9,13
values=float[,float,...] — a comma separated value list. Example: 1.4,3.8,13
separator=character — the field separator. special characters are: pipe, comma, space, tab, newline. Default: tab
raster=name — a raster map to copy the category table from 🫶
rules=name — file containing category label rules (or "-" to read from stdin, iconic)
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

🌸 DESCRIPTION 🌸

r.category prints the category values and labels for the raster map layer you name in map=name, straight to standard output. you can also use it to set category labels for a raster map. versatile queen 💅

you can put every parameter you need right on the command line and run the whole thing non-interactively, no back and forth required. if you don't specify any categories (like, say, by using the optional cats=range[,range,...] argument), then it prints all the category values and labels for that named raster map layer that actually occur in the map. the entire map gets read using r.describe to figure out which categories show up in it. but if you do hand it 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 can also (optionally) say you want a field separator other than a space or tab to split the category value from its matching category label in the output, using the separator=character|space|tab option (peep the example below). if you don't specify a field separator, a tab is used to separate those fields in the output, by default. no cap.

the output goes to standard output as one category per line: the category value first, then an ASCII TAB character (or whatever single character or space you picked with the separator parameter), then the label for the category. clean. ✨

📝 NOTES 📝

any ASCII TAB characters that might be hanging out in the label get replaced by spaces.

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

🍓 Input from a file 🍓

the rules option lets you assign category labels from values found in a file (with no header). 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, fr fr):

cat:Label
val1:val2:Label

if the filename is given as "-", the category labels are read from stdin 💀 (in a cool way)

💜 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.

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

$1 meter$?s

will become:

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

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 skip lines and then act surprised bestie 🙈

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

use ’single quotes’ when using a "$" on the command line to avoid unwanted shell substitution. protect yourself 💅

🦋 EXAMPLES 🦋

North Carolina sample dataset, the 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. she's thorough.

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 and slay.

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.

👑 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. both routes eat, honestly 🍓

🔥 SEE ALSO 🔥

UNIX Manual entries for awk and sort

d.what.rast, r.coin, r.describe, r.support

🎀 AUTHORS 🎀

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

⭐ SOURCE CODE ⭐

Available at: r.category source code (history)

Accessed: Saturday Jan 17 05:40:43 2026

and that's the whole page bestie — this ran on GRASS 8.4.2, it's the manual entry for r.category(1), and the source was last peeked at on Saturday Jan 17 05:40:43 2026. copyright lives with the © 2003-2025 GRASS Development Team in the GRASS GIS 8.4.2 Reference Manual. go forth and label your rasters, you absolute legend 🫶✨

📦 where this page comes from

fedora 44: grass 8.4.2-4.fc44 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms