GRASS logo

NAME

r.colors.matplotlib - Convert or apply a Matplotlib color table to a GRASS raster map

KEYWORDS

raster, color table, matplotlib

SYNOPSIS

r.colors.matplotlib
r.colors.matplotlib --help
r.colors.matplotlib [-dngae] [map=name[,name,...]] [output=name] [color=string] [ncolors=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-d
Generate discrete color table
Generate discrete (interval) color table instead of a continuous one
-n
Reverse the order of colors (invert colors)
-g
Logarithmic scaling
-a
Logarithmic-absolute scaling
-e
Histogram equalization
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

map=name[,name,...]
Raster map(s) to apply color table to
output=name
Name for the new color table rules file
color=string
Name of color table
Available color tables depend on the Matplotlib version. Alternatively this can be file name of a file generated by Python viscm tool
ncolors=integer
Number of colors in the color table
Number of color intervals in a discrete color table with -d
Options: 2-
Default: 6

Table of contents

DESCRIPTION

The r.colors.matplotlib module converts Matplotlib color maps to GRASS color table format (rules) and assigns it to given raster map. The created color table is always relative (color rules with percent) When option map is specified r.colors.matplotlib assigns the color rules to the given raster map. The color tables is always stratched based on the range of values of the map

Depending on the use case, it may be advantageous to use the -d to discretize the color table into intervals.

Matplotlib gist_earth continuous Matplotlib gist_earth discrete

Continuous (default) and discrete (-d) color table

NOTES

This module depends on Matplotlib which needs to be installed on your computer. Use your Python package manager (e.g. pip) or distribution package manager to install it.

The selection of color tables depends on the Matplotlib version. Note that the perceptually uniform sequential color tables, namely viridis, inferno, plasma, and magma, are available in Matplotlib 1.5 and above. Color tables are called color maps (or colormaps) in Matplotlib and the best overview of available color maps in the colormaps_reference example in Matplotlib documentation.

EXAMPLES

Creating a color table as GRASS color rules

Convert summer color table to GRASS color table rules format. If we don't specify output file, it is printed to standard output. We set number of colors to 2 because that's enough for this given color table (it has one color at the beginning and one at the end and linear interpolation can be used for the values in between).
r.colors.matplotlib color=summer ncolors=2
0.000% 0:127:102
100.000% 255:255:102
In case we want to use discrete color table with intervals with given constant color, we use the -d flag and the number of colors is now the number of intervals, so we want to make it higher, 5 in this case.
r.colors.matplotlib color=summer ncolors=5 -d
0.000% 0:127:102
20.000% 0:127:102
20.000% 63:159:102
40.000% 63:159:102
40.000% 127:191:102
60.000% 127:191:102
60.000% 191:223:102
80.000% 191:223:102
80.000% 255:255:102
100.000% 255:255:102

Setting color table for a raster map

Now we set several different color tables for the elevation raster map from the North Carolina sample dataset. We use continuous and discrete color tables (gradients). The color tables ae stretched to fit the raster map range.
r.colors.matplotlib color=summer map=elevation
r.colors.matplotlib color=winter ncolors=8 map=elevation -d
r.colors.matplotlib color=autumn map=elevation
r.colors.matplotlib color=cubehelix ncolors=8 map=elevation -d
r.colors.matplotlib color=terrain map=elevation
We can display legend:
d.legend raster=elevation labelnum=10 at=5,50,7,10
Matplotlib summer Matplotlib winter discrete Matplotlib autumn Matplotlib cubehelix discrete Matplotlib terrain

summer, winter, autumn, cubehelix, and terrain color tables applied to elevation raster from the North Carolina sample dataset. winter and cubehelix are set to be discrete instead of continuous.

Setting color table for a vector map

First we create a text file with color rules:
r.colors.matplotlib color=summer output=mpl_summer.txt
Then we set color table for the vector to the rules stored in a file:
v.colors map=points rules=mpl_summer.txt
Color table for 3D raster map can be set in the same way.

Using color tables generated by the viscm tool

A viscm tool is a little tool for analyzing color tables and creating new color tables (color maps) for Matplotlib. The tool was used to create perceptually uniform color tables for Matplotlib (for example viridis). The new color table is stored into a file. In version 0.7, a temporary file named /tmp/new_cm.py which is a Python source code which creates a Colormap object. If this module gets a name of existing file instead of a color table name, it assumes that it this kind of file and reads object called test_cm as Matplotlib color table. The possible workflow follows. (Note that you need to install the viscm tool, e.g. using sudo pip install viscm on Linux.)

Start the tool, create and save a color table:

python -m viscm edit
Now store the color table in GRASS GIS format:
r.colors.matplotlib color=/tmp/new_cm.py rules=from_viscm.txt
Editing color table in viscm Reviewing color table properties in viscm

Editing color table in viscm (right): the yellow dot on the blue spline must stay in the colored area as the red line moves. Reviewing color table properties is done using several displays including color blindness simulations.

Applied color table form viscm

A color table from viscm applied to elevation raster from the North Carolina sample dataset.

The same works for any Python files which follow the same schema, so it works for example with files from the BIDS/colormap repository.

SEE ALSO

r.colors, v.colors, r3.colors, r.cpt2grass, r.colors.cubehelix

colormaps_reference example in Matplotlib documentation

AUTHORS

Vaclav Petras, NCSU OSGeoREL

Last changed: $Date: 2016-10-20 03:33:27 +0200 (Thu, 20 Oct 2016) $

SOURCE CODE

Available at: r.colors.matplotlib source code (history)


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

© 2003-2017 GRASS Development Team, GRASS GIS 7.2.3svn Reference Manual