Skip to content

r.category

Manages category values and labels associated with user-specified raster map layers.

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

Example:

r.category map=name output_format=plain

grass.script.run_command("r.category", map, cats=None, values=None, separator="tab", raster=None, rules=None, format=None, coefficients=None, output_format="plain", color_format="none", verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.category", map="name", output_format="plain")

Parameters

map=name [required]
    Name of raster map
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
rules=name
    File containing category label rules (or "-" to read from stdin)
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
output_format=name [required]
    Output format
    Allowed values: plain, json
    Default: plain
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
color_format=name
    Color format
    Color format for output values or none.
    Allowed values: 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)
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : str, required
    Name of raster map
    Used as: input, raster, name
cats : str | list[str], optional
    Category values
    Example: 1,3,7-9,13
    Used as: input, cats, range
values : float | list[float] | str, optional
    Comma separated value list
    Example: 1.4,3.8,13
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: tab
raster : str, optional
    Raster map from which to copy category table
    Used as: input, raster, name
rules : str, optional
    File containing category label rules (or "-" to read from stdin)
    Used as: input, file, name
format : str, optional
    Default label or format string for dynamic labeling
    Used when no explicit label exists for the category
coefficients : tuple[float, float, float, float] | list[float] | str, optional
    Dynamic label coefficients
    Two pairs of category multiplier and offsets, for $1 and $2
    Used as: mult1,offset1,mult2,offset2
output_format : str, required
    Output format
    Used as: name
    Allowed values: plain, json
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
    Default: plain
color_format : str, optional
    Color format
    Color format for output values or none.
    Used as: name
    Allowed values: none, rgb, hex, triplet, hsv
    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)
    Default: none
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.category prints the category values and labels for the raster map layer specified by map=name to standard output. You can also use it to set category labels for a raster map.

The user can specify all needed parameters on the command line, and run the program non-interactively. If the user does not specify any categories (e.g., using the optional cats=range[,range,...] argument), then all the category values and labels for the named raster map layer that occur in the map are printed. The entire map is read using r.describe, to determine which categories occur in the map. If a listing of categories is specified, then the labels for those categories only are printed. The cats may be specified as single category values, or as ranges of values. The user 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). If no field separator is specified by the user, a tab is used to separate these fields in the output, by default.

The output is sent 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 is specified using the separator parameter), then the label for the category.

NOTES

Any ASCII TAB characters which may be in the label are replaced by spaces.

The output from r.category can be redirected into a file, or piped into another program.

Input from a file

The rules option allows the user to assign category labels from values found in a file (without header). The label can refer to a single category, range of categories, floating point value, or a range of floating point values. The format is given as follows (when separator is set to colon; no white space must be used after the separator):

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 are not 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. Thus

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

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.

EXAMPLES

North Carolina sample dataset:

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.

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.

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.

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

generates the following JSON output:

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

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.

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)
Latest change: Thursday May 08 20:58:05 2025 in commit 4144ba8