cmasher 1.3.1

Scientific colormaps for making accessible, informative and 'cmashing' plots

CMasher: Scientific colormaps for making accessible, informative and cmashing plots

The CMasher package provides a collection of scientific colormaps to be used by different Python packages and projects, mainly in combination with matplotlib, showcased in the online documentation. The colormaps in CMasher are all designed to be perceptually uniform sequential using the viscm package; most of them are color-vision deficiency friendly; and they cover a wide range of different color combinations to accommodate for most applications. It offers several alternatives to commonly used colormaps, like chroma and rainforest for jet; sunburst for hot; neutral for binary; and fusion and redshift for coolwarm. If you cannot find your ideal colormap, then please open an issue, provide the colors and/or style you want, and I will try to create one to your liking! Let’s get rid of all bad colormaps in the world together!

If you use CMasher for your work, then please star the repo, such that I can keep track of how many users it has and more easily raise awareness of bad colormaps.

Colormap overview

Below is an overview of all the colormaps that are currently in CMasher (made with the cmr.create_cmap_overview() function). For more information, see the online documentation.

Installation & Use

How to install

CMasher can be easily installed by either cloning the repository and installing it manually:

$ git clone https://github.com/1313e/CMasher
$ cd CMasher
$ pip install .

or by installing it directly from PyPI with:

$ pip install cmasher

CMasher can now be imported as a package with import cmasher as cmr.

Example use

The colormaps shown above can be accessed by simply importing CMasher. This makes them available in the cmasher module, in addition to registering them in matplotlib’s cm module (with added 'cmr.' prefix to avoid name clashes). So, for example, if one were to use the rainforest colormap, this could be done with:

# Import CMasher to register colormaps
import cmasher as cmr

# Import packages for plotting
import matplotlib.pyplot as plt
import numpy as np

# Access rainforest colormap through CMasher or MPL
cmap = cmr.rainforest                   # CMasher
cmap = plt.get_cmap('cmr.rainforest')   # MPL

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

# Make scatter plot of data with colormap
plt.scatter(x, y, c=z, cmap=cmap, s=300)
plt.show()

Accessing the colormaps in other languages than Python would require reading in the <cmap_name>_8bit.txt text files in the cmasher/colormaps directory, which contain the 8-bit RGB values of every colormap, and registering them in the appropriate package in the language manually. 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.

Using custom colormaps

CMasher allows for custom colormaps to be imported with the cmr.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 matplotlib Colormap 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 cmr.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 unchanged). This is to keep official and unofficial colormaps separated in CMasher.