r.what.color

Queries colors for a raster map layer.

Command linePython (grass.script)

r.what.color [-i] input=name [value=float [,float,...]] [format=string] color_format=name [--verbose] [--quiet] [--qq] [--ui]

Example:

r.what.color input=name color_format=hex

grass.script.run_command("r.what.color", input, value=None, format="%d:%d:%d", color_format="hex", flags=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.what.color", input="name", color_format="hex")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of input raster map
value=float [,float,...]
    Values to query colors for
format=string
    Output format ('plain', 'json', or printf-style string)
    Output format printf-style is deprecated, use 'color_format' option instead.
    Default: %d:%d:%d
color_format=name [required]
    Color format
    Color format for output values. Applies only when format is set to 'plain' or 'json'.
    Allowed values: rgb, hex, hsv, triplet
    Default: hex
    rgb: output color in RGB format
    hex: output color in HEX format
    hsv: output color in HSV format (experimental)
    triplet: output color in colon-separated RGB format
-i
    Read values from stdin
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of input raster map
    Used as: input, raster, name
value : float | list[float] | str, optional
    Values to query colors for
format : str, optional
    Output format ('plain', 'json', or printf-style string)
    Output format printf-style is deprecated, use 'color_format' option instead.
    Default: %d:%d:%d
color_format : str, required
    Color format
    Color format for output values. Applies only when format is set to 'plain' or 'json'.
    Used as: name
    Allowed values: rgb, hex, hsv, triplet
    rgb: output color in RGB format
    hex: output color in HEX format
    hsv: output color in HSV format (experimental)
    triplet: output color in colon-separated RGB format
    Default: hex
flags : str, optional
    Allowed values: i
    i
        Read values from stdin
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.what.color outputs the color associated with user-specified category values in a raster input map.

Values may be specified either using the value= option, or by specifying the -i flag and passing the values on stdin, one per line.

For each specified value, an output will be generated consisting of the category value along with the color, e.g.:

r.what.color input=elevation.dem value=1500
1500: 223:127:31

# In plain format using the triplet color format:
r.what.color input=elevation.dem value=1500 format=plain color_format=triplet
1500: 223:127:31

# In JSON format using the triplet color format:
r.what.color input=elevation.dem value=1500 format=json color_format=triplet
[
    {
        "value": 1500,
        "color": "223:127:31"
    }
]

Similarly, other color_format options available with format=json and format=plain are hex, hsv, triplet, and rgb, with hex being the default color format.

If the input map is an integer (CELL) map, the category will be written as an integer (no decimal point), otherwise it will be written in floating point format (printf("%.15g") format).

If the lookup fails for a value, the color will be output as an asterisk (or as null in JSON), e.g.:

r.what.color input=elevation.dem value=9999
9999: *

# In plain format:
r.what.color input=elevation.dem value=9999 format=plain
9999: *

# In JSON format:
r.what.color input=elevation.dem value=9999 format=json
[
    {
        "value": 9999,
        "color": null
    }
]

If a value cannot be parsed, both the value and the color will be output as an asterisk (or as null in JSON), e.g.:

r.what.color input=elevation.dem value=bogus
*: *

# In plain format:
r.what.color input=elevation.dem value=bogus format=plain
*: *

# In JSON format:
r.what.color input=elevation.dem value=bogus format=json
[
    {
        "value": null,
        "color": null
    }
]

The format can be changed using the format= option. The value should be a printf()-style format string containing three conversion specifiers for the red, green and blue values respectively, e.g.:

r.what.color input=elevation.dem value=1500 format='%02x:%02x:%02x'
1500: df:7f:1f

If your system supports the %m\$ syntax, you can change the ordering of the components, e.g.:

r.what.color input=elevation.dem value=1500 format='%3$02x:%2$02x:%1$02x'
1500: 1f:7f:df

Common formats:

Tcl/Tk: format="#%02x%02x%02x"
WxPython: format='"#%02x%02x%02x"' or format='"(%d,%d,%d)"'

NOTE:

Please note that the printf()-style output format is deprecated and will be removed in a future release. Use the color_format option instead, together with format=plain or format=json.

Using r.what.color JSON output with python

Print color associated with user-specified category value in JSON format using Python:

import grass.script as gs

# Run the r.what.color command with rgb option for JSON output format
items = gs.parse_command(
    "r.what.color",
    input="elevation",
    value=[100, 135, 156],
    format="json",
    color_format="rgb",
)

for item in items:
    print(f"{item['value']}: {item['color']}")

100: rgb(255, 229, 0)
135: rgb(195, 127, 59)
156: rgb(23, 22, 21)

AUTHOR

Glynn Clements

SOURCE CODE

Available at: r.what.color source code (history)
Latest change: Wednesday Jun 04 20:44:43 2025 in commit 7cd2631