r.colors(1grass)

✨ r.colors ✨

okay bestie, welcome to r.colors from the GRASS User's Manual — it's a section 1grass situation, iykyk 💅

---

🌈 NAME

r.colors — creates/modifies the color table associated with a raster map. that's it, that's the whole job, and she does it beautifully 😌

🎀 KEYWORDS

raster, color table

---

🦋 SYNOPSIS

r.colors
r.colors --help
r.colors [-rwldngae]  [map=name[,name,...]]   [file=name]
[color=style]   [raster=name]   [raster_3d=name]   [rules=name]
[offset=float]   [scale=float]   [--help]  [--verbose]  [--quiet]
[--ui]

---

⭐ Flags

grab your lil flag checklist bestie, we're going through all of them:

• -r — remove existing color table. say bye bye, it's giving deletion 🫶
• -w — only write new color table if it does not already exist. so polite of her, she checks first 💖
• -l — list available rules then exit. window shopping, no commitment ✨
• -d — list available rules with description then exit. also: if a color rule is given, only this rule is listed. so you can be like "okay just show me that one" 🎀
• -n — invert colors. flip the whole vibe upside down 🔄
• -g — logarithmic scaling
• -a — logarithmic-absolute scaling
• -e — histogram equalization
• --help — print usage summary
• --verbose — verbose module output (she will NOT stop talking and honestly? we love that) 💬
• --quiet — quiet module output (shhh 🤫)
• --ui — force launching GUI dialog

---

🍓 Parameters

• map=name[,name,...] — name of raster map(s). you can pass a whole lil squad of them, comma-separated 👑
• file=name — input file with one map name per line. listen, if you have a large amount of maps to specify, you can define the input map names in an input file instead. > this option is mutual exclusive to the map option — so it's map OR file, not both, no cap 🚫
• color=style — name of color table. here's the full lineup, and bestie every single one of these is iconic in her own way:

Options: aspect, aspectcolr, bcyr, bgyr, blues, byg, byr, celsius, corine, curvature, differences, elevation, etopo2, evi, fahrenheit, forest_cover, gdd, grass, greens, grey, grey.eq, grey.log, grey1.0, grey255, gyr, haxby, inferno, kelvin, magma, ndvi, ndwi, nlcd, oranges, plasma, population, population_dens, precipitation, precipitation_daily, precipitation_monthly, rainbow, ramp, random, reds, roygbiv, rstcurv, ryb, ryg, sepia, slope, soilmoisture, srtm, srtm_percent, srtm_plus, terrain, viridis, water, wave

and now the tea on each one 🫖:

• aspect — aspect oriented grey colors [range: map values]
• aspectcolr — aspect oriented rainbow colors [range: 0 to 360]
• bcyr — blue through cyan through yellow to red [range: map values]
• bgyr — blue through green through yellow to red [range: map values]
• blues — white to blue [range: map values]
• byg — blue through yellow to green [range: map values]
• byr — blue through yellow to red [range: map values]
• celsius — blue to red for degree Celsius temperature [range: -80 to 80]
• corine — EU Corine land cover colors [range: 111 to 995]
• curvature — for terrain curvatures (from v.surf.rst and r.slope.aspect) [range: map values]
• differences — differences oriented colors [range: map values]
• elevation — maps relative ranges of raster values to elevation color ramp [range: map values]
• etopo2 — colors for ETOPO2 worldwide bathymetry/topography [range: -11000 to 8850]
• evi — enhanced vegetative index colors [range: -1 to 1]
• fahrenheit — blue to red for Fahrenheit temperature [range: -112 to 176]
• forest_cover — percentage of forest cover [range: 0 to 100]
• gdd — accumulated growing degree days [range: 0 to 6000]
• grass — GRASS green (perceptually uniform) [range: map values]
• greens — white to green [range: map values]
• grey — grey scale [range: map values]
• grey.eq — histogram-equalized grey scale [range: map values]
• grey.log — histogram logarithmic transformed grey scale [range: map values]
• grey1.0 — grey scale for raster values between 0.0-1.0 [range: 0 to 1]
• grey255 — grey scale for raster values between 0-255 [range: 0 to 255]
• gyr — green through yellow to red [range: map values]
• haxby — relative colors for bathymetry or topography [range: map values]
• inferno — perceptually uniform sequential color table inferno [range: map values]
• kelvin — blue to red for temperature in Kelvin scale [range: 193.15 to 353.15]
• magma — perceptually uniform sequential color table magma [range: map values]
• ndvi — Normalized Difference Vegetation Index colors [range: -1 to 1]
• ndwi — Normalized Difference Water Index colors [range: -200 to 200]
• nlcd — US National Land Cover Dataset colors [range: 0 to 95]
• oranges — white to orange [range: map values]
• plasma — perceptually uniform sequential color table plasma [range: map values]
• population — color table covering human population classification breaks [range: 0 to 2e+09]
• population_dens — color table covering human population density classification breaks [range: 0 to 1e+09]
• precipitation — precipitation color table (0..2000mm) [range: 0 to 7000]
• precipitation_daily — precipitation color table (0..1000mm) [range: 0 to 10000]
• precipitation_monthly — precipitation color table (0..1000mm) [range: 0 to 1000]
• rainbow — rainbow color table [range: map values]
• ramp — color ramp [range: map values]
• random — random color table [range: map values]
• reds — white to red [range: map values]
• roygbiv — [range: map values]
• rstcurv — terrain curvature (from r.resamp.rst) [range: map values]
• ryb — red through yellow to blue [range: map values]
• ryg — red through yellow to green [range: map values]
• sepia — yellowish-brown through to white [range: map values]
• slope — r.slope.aspect-type slope colors for raster values 0-90 [range: 0 to 90]
• soilmoisture — soilmoisture color table (0.0-1.0) [range: 0 to 1]
• srtm — color palette for Shuttle Radar Topography Mission elevation [range: -11000 to 8850]
• srtm_percent — color palette for Shuttle Radar Topography Mission using relative elevation [range: map values]
• srtm_plus — color palette for Shuttle Radar Topography Mission elevation (with seafloor colors) [range: -11000 to 8850]
• terrain — global elevation color table covering -11000 to +8850m [range: -11000 to 8850]
• viridis — perceptually uniform sequential color table viridis [range: map values]
• water — water depth [range: map values]
• wave — color wave [range: map values]

• raster=name — raster map from which to copy color table 📋✨
• raster_3d=name — 3D raster map from which to copy color table (yes babe, 3D, she contains multitudes) 🧊
• rules=name — path to rules file. > use "-" to read rules from stdin 🫶
• offset=float — offset for color rule values. New value = (old value + offset) * scale. Default: 0
• scale=float — scale for color rule values. New value = (old value + offset) * scale. Default: 1

💖 DESCRIPTION 💖

okay bestie, so r.colors is the glow-up tool for your raster maps' color tables ✨ You can create a color table, or modify one, or do it for a whole lil squad of raster maps at once. The maps — either named on the command line with map, or handed over as a file using input with one map name per line — must exist in your current mapset search path, no exceptions, she's picky like that.

• The raster option lets you name a raster map and just... steal its color map wholesale. copy-paste energy 🫶
• The raster_3d option does the same thing but for a 3D raster map — dimension glow-up 💅

The -e flag equalizes the original raster's color table. It can save you from needing the grey.eq rule when you use it as -e color=grey. BUT — and this is the part nobody tells you — it will not give you a color table identical to color=grey.eq, because grey.eq scales the fraction by 256 to get a grey level, while -e uses that fraction to interpolate the original color table. If the original color table is a 0-255 grey scale, then -e is effectively scaling the fraction by 255. Different algorithms, different vibes, same goal. -e is designed to work with any color table — floating point and integer raster maps both, she doesn't discriminate 🔥

The -g flag divides the raster's grey value range into 100 logarithmically equal steps (where "step" means a rule with the same grey level at its start and end points). It can save you from needing the grey.log rule when you use it as -g color=grey. BUT again — this will not produce a color table identical to color=grey.log. Different algorithms, she's her own girl. Unlike color=grey.log, though, -g is designed to work with both floating point and integer rasters, with no performance drama even on huge datasets, whatever the original color table was. Two things to know though:

Logarithmic scaling does not work on negative values. And if the value range includes zero, there is no realistic solution. It's giving undefined, bestie, don't even try 😭

The -e and -g flags are not mutually exclusive — you can absolutely run both, they're besties too.

offset and scale modify color rules so they match a raster map's values, using this formula:

new_value = (old_value + offset) x scale

For example, if a raster map's units are Kelvin x 50, you can apply the celsius color rules with offset=273.15 and scale=50. math girlies rise up 🔥

If you pass the -w flag, the current color table file for the input map will not be overwritten. Meaning: the color table only gets created if the map doesn't already have one. If you don't pass -w, then the color table gets created if none exists, or modified if one does. It's the difference between "make it if it's missing" and "make it or fix it, idc" 💅

These color table types are pre-defined, and r.colors knows how to build them with zero extra input from you:

• aspect
• grey
• grey.eq — the histogram-equalized grey scale 📊
• byg — blue-yellow-green
• byr — blue-yellow-red
• gyr — green-yellow-red
• rainbow 🌈
• ramp
• ryg — red-yellow-green
• random
• wave

In case you provide several input raster maps, the range (min, max) of all of them gets used for color table creation. So the color table she makes will span from the smallest minimum to the largest maximum across every input raster map, and gets applied to all of them. group effort, periodt 🫶

In general, tables that associate colors with percentages — aspect, bcyr, byg, byr, elevation, grey, gyr, rainbow, ramp, ryb, ryg and wave — can be applied to literally any data. But the ones that use absolute values — aspectcolr, curvature, etopo2, evi, ndvi, population, slope, srtm, and terrain — only make sense for data with certain ranges. You can get a rough idea of whether a color table suits your data by reading the matching rules file at $GISBASE/etc/colors/<name>. For example, the slope rule is defined as:

0  255:255:255
2  255:255:0
5  0:255:0
10 0:255 255
15 0:0:255
30 255:0:255
50 255:0:0
90 0:0:0

That's designed for the slope map generated by r.slope.aspect, where the value is a slope angle between 0 and 90 degrees. 🏔️

Similarly, the aspectcolr rule:

0 white
1 yellow
90 green
180 cyan
270 red
360 yellow

is designed for the aspect maps produced by r.slope.aspect, where the value is a heading between 0 and 360 degrees.

The rules color table type tells r.colors to read color table specifications from standard input (stdin) and build the color table accordingly. DIY queen 👑

Using the rules color table type, there are two ways to build a color table: by category values, and by "percent" values.

To build a color table using category value indices, you figure out the range of category values in the raster map the color table will be used with, then associate specific category values with specific colors. Note that you do not have to assign a color for every valid category value, because r.colors will interpolate a color ramp to fill in wherever color specification rules were left out. The format looks like this:

category_value color_name
category_value color_name
.. ..
.. ..
category_value color_name
end

Each category value must be valid for the raster map, the category values must be in ascending order, and you can only use standard GRASS color names: aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta, orange, purple, red, violet, white, yellow. no inventing new colors, sorry babe 😭

Colors can also be given as color numbers, each in the range 0-255. The format for a category value color table specification using numbers instead of names is:

category_value red_number:green_number:blue_number
category_value red_number:green_number:blue_number
.. .. .. ..
.. .. .. ..
category_value red_number:green_number:blue_number
end

Specifying a color table by "percent" values lets you treat a color table as if it were numbered from 0 to 100. The format of a "percent" value color table specification is the same as for a category value specification, except the category values get replaced by "percent" values, each from 0-100, in ascending order:

percent_value% color_name
percent_value% color_name
.. ..
.. ..
percent_value% color_name
end

And using "percent" value specification rules, colors can also be given as color numbers, each in the range 0-255:

percent_value% red_number:green_number:blue_number
percent_value% red_number:green_number:blue_number
.. .. .. ..
.. .. .. ..
percent_value% red_number:green_number:blue_number
end

Bestie, you can even mix the two methods of color table specification. for example:

0 black
10% yellow
78 blue
100% 0:255:230
end

To set the NULL (no data) color, use the "nv" (null values) parameter:

0 black
10% yellow
nv white
end

To set the color used for undefined values (those beyond the range of the color rules), use the "default" parameter:

0 red
1 blue
default grey
end

---

📝 NOTES 📝

All color tables are stored in $GISBASE/etc/colors/. Further user-defined color tables can also be dropped in this directory so they're accessible from the color parameter — or you can keep them in a user defined directory instead. See also r.colors.out for printing color tables easily to the terminal 🖨️✨

The color table assigned to a raster map is stored in $GISDBASE/location/mapset/colr/. that's where she lives 🏠

---

🌸 EXAMPLES 🌸

The example below shows how you can specify colors for a three category map — red for category 1, green for category 2, and blue for category 3. Start by opening a text editor and creating this rules specification file (save it with the name rules.file):

1 red
2 green
3 blue
end

Then the color table can be assigned to map threecats with these GRASS commands (two ways are available, pick your fave):

# read input from stdin
cat rules.file | r.colors map=threecats rules=-
# read directly from file
r.colors map=threecats rules=rules.file

To create a natural looking lookup table (LUT) for true map layer elevation, use this rules specification file. It assigns light green shades to the lower elevations (first 20% of the LUT), then darker greens (next 15%, and next 20%) and light browns (next 20%) for middle elevations, darker browns (next 15%) for higher elevations, and finally yellow for the highest peaks (last 10% of the LUT). peak main character energy, honestly 👑

0% 0:230:0
20% 0:160:0
35% 50:130:0
55% 120:100:30
75% 120:130:40
90% 170:160:50
100% 255:255:100

To invert the current rules:

r.colors map=current_raster -n rast=current_raster

---

👀 SEE ALSO 👀

d.colortable, d.histogram, d.legend, r.colors.out, r.colors.stddev, r.support, r.univar, v.colors, v.colors.out, r3.colors, r3.colors.out

Also check out the wiki page Color tables (from the GRASS User Wiki) 🦋

And ColorBrewer — an online tool designed to help people select good color schemes for maps and other graphics. aesthetic queen behavior 🎨✨

---

🫶 AUTHORS 🫶

Michael Shapiro and David Johnson Support for 3D rasters by Soeren Gebbert

---

💻 SOURCE CODE 💻

Available at: r.colors source code (history)

Latest change: Thursday Oct 09 18:01:34 2025 in commit: c32823cbb080d14d419b2f734087c7ba396b3e2c

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

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

---

and that's a wrap bestie!! 💖 this whole page lives in GRASS 8.5.0 as r.colors(1grass), latest commit dropped Thursday Oct 09 18:01:34 2025 (commit c32823cbb080d14d419b2f734087c7ba396b3e2c), © 2003-2026 GRASS Development Team. go forth and color your maps, you're gonna slay 🎀🌈💅