# Usage¶

The following contains explanations on how the different colormaps and functions in CMasher can be used to aid the creation of cmashing plots.

## Accessing colormaps¶

All CMasher colormaps are available through matplotlib and CMasher upon importing the package, but CMasher also provides a few other ways of using the colormaps.

If one wishes to use a specific CMasher colormap without adding dependencies (useful for, e.g., handing in tutorial assignments; quickly sharing work/results with someone; etc.), then one can create a standalone Python module of the colormap with create_cmap_mod(). The created Python module can be placed in a local working directory, and can then be imported with import <cmap_name> (e.g., cmr.create_cmap_mod(‘rainforest’) to create a standalone module of rainforest; and import rainforest to register the colormap in matplotlib as 'cmr.rainforest'). Premade standalone versions of all colormaps in CMasher can be found in the cmasher/colormaps directory, with the name <cmap_name>/<cmap_name>.py.

Note

Standalone Python modules can only be made with create_cmap_mod() of colormaps that are registered in CMasher (see Custom colormaps). This is because these modules contain metadata that states where the colormap comes from, and there is no consistent way to obtain this metadata for colormaps not coming from CMasher.

Accessing the colormaps in other languages than Python would require reading in the <cmap_name>/<cmap_name>_8bit.txt or <cmap_name>/<cmap_name>_hex.txt text files in the cmasher/colormaps directory, which contain the 8-bit and HEX-code RGB values of every colormap, respectively, and registering them in the appropriate package in the language manually. These RGB values can also be obtained with the take_cmap_colors() function using N=None and providing the appropriate format string for the return_fmt argument.

For those that are interested, the viscm source files that were used for creating the colormaps can also be found in the cmasher/colormaps directory in the repo (the source files are not provided with the package distribution). Note that my modified version of viscm (available here) is required in order to properly view and edit the source file of a diverging colormap.

## Colormap overviews¶

To allow for colormaps to be more easily compared with each other, CMasher can create colormap overviews of a given collection of colormaps, like those shown on the Introduction; Sequential colormaps; and Diverging colormaps pages. This is done with the create_cmap_overview() function, which takes a list of colormaps, and creates an overview with their colored and grey-scaled versions, sorted on type and name (by default). Colormap overview figures are ideal for webpages or documents, as their horizontal resolution is always the same (i.e., 640px for SVG, or 1,600px for other formats). Adding or removing colormaps from the overview solely affects its vertical resolution, which is adjusted automatically such that each entry always has the same resolution.

The colormaps shown in an overview can be sorted/ordered in a number of different ways. By default, the colormaps are separated into their types (as determined by get_cmap_type()), and sorted on their name in alphabetical order (use sort=None to not sort the colormaps). However, one can specify their own categories for colormaps (that are used instead of the colormap types) by providing a dict of lists, where the keys are used as the categories. As colormaps with different lightness profiles can cause perception issues when displayed near each other, colormaps can also be sorted on their lightness profiles with sort=’lightness’ to avoid this problem. Keep in mind that sorting on lightness profiles is only useful if all colormaps within a category are of the same colormap type.

Note

Sorting colormaps on their lightness profiles is done roughly in the following order:

1. Sequential colormaps are split up into four groups based on their minimum and maximum lightness values. These groups are $$[0, {<}100]$$; $$[0, 100]$$; $$[0{<}, 100]$$; and $$[0{<}, {<}100]$$.
2. Starting (sequential) or central (diverging and cyclic) lightness value.
3. Difference between the minimum and maximum lightness values.
4. RMSE (root mean square error) of the derivative of the lightness profile.
5. Name.

Qualitative and miscellaneous colormaps are never sorted on their lightness profiles and solely use the last step.

Additionally, by using plot_profile=True, one can plot the lightness profile of all colormaps (except those that are classified as ‘qualitative’) on top of their grey-scaled versions, allowing for quick performance comparisons between colormaps. And, finally, one can set the title that is displayed at the top of the colormap overview with the title argument, which by default is set to “Colormap Overview”.

Below is a list of pages containing several colormap overview examples with their scripts.

## Colormap application overview¶

Whereas the colormap overviews introduced above are great for seeing how the colormaps compare to each other in terms of performance, they do not show how the colormap would look like when used in a realistic application. As CMasher has quite a few different colormaps, this could make it difficult to pick the right one. For that reason, below is an overview of all colormaps in CMasher (and the reversed versions of all sequential colormaps as well), using their sample images as usually shown on the individual colormap pages:

Fig. 3 Application overview plot of CMasher’s colormaps.

## Command-line interface (CLI)¶

Although CMasher is written in Python, some of its utility functions do not require the interpreter in order to be used properly. For that reason, CMasher provides a CLI that allows for these utility functions to be called directly from the command-line. This CLI can be accessed with the command cmr after installing CMasher. The table below shows which CLI commands are available and what utility function in CMasher they correspond to.

Command Function
bibtex get_bibtex()
cmcolors take_cmap_colors()
cmtype get_cmap_type()
mkcmod create_cmap_mod()
rgbtable take_cmap_colors() with N=None

Except for the mkcmod command, the commands print their results directly to the console using the formatting that was requested (if applicable). Depending on the operating system used, this output can easily be redirected to be saved to a file (e.g., cmr rgbtable rainforest > rainforest.txt to save the RGB values of rainforest in a .txt-file on UNIX-systems). All functionality that is usually available for the listed functions within the interpreter, are also available from the command-line.

Because it is not possible to import any packages that provide colormaps before using a CLI function, CMasher reads the CMR_CMAP_PKGS environment variable. If this variable exists, it should contain a collection of names of packages that must be imported before any CLI function is executed. By default, CMasher will attempt to import cmocean; colorcet; and palettable. Providing names of packages that are not installed will be ignored.

In addition to this environment variable, one can also provide the object path of a Colormap object using the format ‘a.b:c.d’ as the CMAP argument (except for the mkcmod command). Here, ‘a.b’ is the module to be imported and ‘c.d’ is the requested colormap object in this module (e.g., import a.b; cmap = a.b.c.d). For example, if one were to request the colormap type of the rainforest colormap, then one could do this with cmr cmtype cmasher:rainforest (or cmr cmtype cmasher.cm:rainforest).

## Custom colormaps¶

CMasher allows for custom colormaps to be imported with the import_cmaps() function (which is executed automatically on the cmasher/colormaps directory when CMasher is imported). This function takes the path to a colormap file named cm_<cmap_name> (or the path to a directory containing such files); creates a ListedColormap object using the data in the file; and registers it in matplotlib with the name 'cmr.<cmap_name>' (it will also be available in CMasher as cmr.cm.<cmap_name>). A colormap file can either be a JSCM-file as created by viscm or a text file that contains the (normalized) RGB values of the colormap (see the text files in the cmasher/colormaps directory for the structure of such files). If one wishes to register a colormap using (normalized) RGB values that are already in memory, the register_cmap() function can be used for this.

Note that colormaps imported/registered this way cannot be accessed through CMasher using cmr.<cmap_name>, unlike CMasher’s own colormaps, but solely using cmr.cm.<cmap_name> (access through matplotlib is the same as before). This is to keep official and unofficial colormaps separated in CMasher.

## Legend entries¶

In matplotlib, it is possible to assign labels to plots that use colormaps. However, in many of these cases, it will not create an entry in the legend, as colormaps do not have legend icons. As it can sometimes be desirable to add a colormap as an entry to the legend, for example when plotting a 2D histogram as background information in a figure, CMasher provides the set_cmap_legend_entry() function. This function can be used to set the label of any matplotlib plotting element (instances of the Artist class) that uses a colormap, and adds a miniature version of the colormap to the legend. The script and image below show an example of this:

# Import packages
import cmasher as cmr
import matplotlib.pyplot as plt
import numpy as np

# Create figure object
fig = plt.figure()

# Generate some data to plot
x = np.random.rand(1000000)
y = np.random.rand(1000000)
z = x**2+y**2

# Create hexbin plot using the rainforest colormap
plot = plt.hexbin(x, y, z, 50, cmap='cmr.rainforest')

cmr.set_cmap_legend_entry(plot, 'rainforest')

# Obtain axes object
ax = fig.axes[0]

# Set axes limits
ax.axis([0, 1, 0, 1])

# Turn off the X and Y axes
ax.set_axis_off()
ax.xaxis.set_visible(False)
ax.yaxis.set_visible(False)

# Create legend
ax.legend(loc='upper left')

# Show figure
plt.show()


Fig. 4 Hexbin plot using a colormap legend entry for the rainforest colormap.

## Sub-colormaps¶

Most sequential colormaps in CMasher span the entire lightness range from black to white, to maximize the perceptual range of the colormap. However, there are many cases in which this is not necessary or is even counter-productive (e.g., annotating colormaps; displaying smooth information like images; etc.). To aid with this, CMasher allows for sub-colormaps to be made of any colormap with the get_sub_cmap() function. Below is an example of a sub-colormap of rainforest using the central $$70\%$$, created with cmr.get_sub_cmap(‘cmr.rainforest’, 0.15, 0.85), compared to the original:

Fig. 5 The rainforest colormap.

Fig. 6 The sub-colormap made of rainforest, using its central $$70\%$$.

Note that get_sub_cmap() does not interpolate between colors, as this can create artifacts. In order to avoid creating colormaps that have too few different colors to look smooth, it is recommended to include at least 128 different colors. For CMasher colormaps, this means that one should aim to use at least $$50\%$$ of sequential colormaps (256 colors), or $$25\%$$ of diverging colormaps (511 colors).

## Taking colormap colors¶

Sometimes it is necessary to show a collection of different plots in the same figure. For example, several scatter plots that indicate sample populations; or a set of lines where each uses a different fitting algorithm; etc. In this case, it is often desirable to choose colors for these different plots that are distinguishable, but still follow some sort of relative ordering. As colormaps contain colors in an ordered structure, they are well suited for this.

CMasher allows one to take a given number of equally spaced colors from any colormap with the take_cmap_colors() function. These colors can then be used during plotting. The example below shows the script used to create a line plot with 5 colors taken from the rainforest colormap, and the resulting figure:

# Import packages
import cmasher as cmr
import matplotlib.pyplot as plt
import numpy as np

# Create figure object
fig = plt.figure()

# Take 5 colors from rainforest in [0.15, 0.85] range in HEX
colors = cmr.take_cmap_colors('cmr.rainforest', 5, cmap_range=(0.15, 0.85), return_fmt='hex')

# Create 5 line plots, each using a different color
for i, color in enumerate(colors):
x = 0.1*(i+1)*np.linspace(0, 1, 100)**2
plt.plot(x, color=color, label=color)

# Obtain axes object
ax = fig.axes[0]

# Turn off the X and Y axes
ax.xaxis.set_visible(False)
ax.yaxis.set_visible(False)

# Create legend
ax.legend(loc='upper left')

# Show figure
plt.show()


Fig. 7 Line plot using 5 different colors from the rainforest colormap.