Skip to content

Colormaps#

The cmap.Colormap type represents a colormap.

Also known as a LUT (look-up table), a colormap is a mapping from a scalar value to a color. Colormaps are used in a variety of contexts, including image processing, data visualization, and scientific visualization. The cmap library provides a number of built-in colormaps, including all of the colormaps in matplotlib, napari, vispy, and more.

from cmap import Colormap

# argument can be any "ColormapLike".  See rules below
cm = Colormap('viridis')

ColormapLike objects#

The following objects can be interpreted as a colormap, and used as the first argument to the cmap.Colormap constructor; cmap refers to these objects collectively as "ColormapLike". Briefly, valid arguments are of type:

str#

  • A string containing a recognized colormap name.

    • Colormap('viridis')
      bids:viridis colormap
    • Colormap('batlow')
      crameri:batlow colormap

    Matplotlib names ✅

    Any valid matplotlib colormap key that could be used in matplotlib.colormaps[...] is also a valid cmap colormap name.

  • A string containing a recognized colormap name suffixed with "_r" to reverse the colormap:

    • Colormap('viridis_r')
      bids:viridis colormap
    • Colormap('batlow_r')
      crameri:batlow colormap

Iterable[ColorLike | tuple]#

  • An Iterable of ColorLike objects:

    • Colormap(['blue', 'yellow', 'red'])
      custom colormap colormap
    • Colormap([(0, 0, 1.), "#FF0", "rgb(255, 0, 0)"])
      custom colormap colormap

    Note

    In the case of an iterable of colors, all colors are assumed to be equally spaced along the colormap.

  • An Iterable of ColorLike OR tuple[float, ColorLike] objects, where the float represents the position of the color along the colormap from 0-1 (aka the "color stop"):

    • Colormap([(0, 'blue'), (0.8, 'yellow'), (1, 'red')])
      custom colormap colormap

    If omitted, the first and last color stops are assumed to be at 0 and 1, respectively.

    • Colormap(['blue', (0.8, 'yellow'), 'red'])
      custom colormap colormap

    If the first or last color stop is not at 0 or 1, the first/last color is repeated at the 0th or 1 position, respectively.

    • Colormap([(0.4, 'blue'), (0.8, 'yellow'), 'red'])

      custom colormap colormap

      (same as ['blue', (0.4, 'blue'), (0.8, 'yellow'), 'red'])

    If internal stops are partially provided, the missing values are assumed to be equally spaced between any provided neighboring positions (or 0 and 1, if none are provided). They are NOT placed at their global index / (len(colors) - 1).

    • Colormap(['blue', 'green', (0.8, 'yellow'), 'red'])

      custom colormap colormap

      (same as ['blue', (0.4, 'green'), (0.8, 'yellow'), 'red'])

numpy.ndarray#

A numpy.ndarray, in one of the following formats:

  • an (N, 3) array of N RGB colors equally spaced along the colormap:

    Colormap(np.array([[0, 0, 1.], [1., 1., 0], [1., 0, 0]]))

    custom colormap colormap

  • an (N, 4) array of N RGBA colors equally spaced along the colormap:

    Colormap(np.array([[0, 0, 1., 1.], [1., 1., 0, 0.7], [1., 0, 0, 0.3]]))

    custom colormap colormap

  • an (N, 5) array of color stops, where the first column is the position of the color stop and the remaining 4 columns are the RGBA colors:

    Colormap(
    np.array([
        [0.0, 0.0, 0.0, 1.0, 1.0],
        [0.8, 1.0, 1.0, 0.0, 1.0],
        [1.0, 1.0, 0.0, 0.0, 1.0]
    ])
)

    custom colormap colormap

dict#

  • A {position -> color} dict of color stops, where the keys are the positions of the color stops and the values are the colors:

    • Colormap({0: 'blue', 0.5: 'yellow', 1: 'red'})
      custom colormap colormap

  • A matplotlib-style segmentdata dict, with keys "red", "green", "blue", and (optionally) "alpha" and values that are either:

    • an (N, 3) array-like [[x, y0, y1], ...] where x is the color stop position, and y0 and y1 are the values of the color on either side of the stop position.

      cdict = {'red':  [[0.0,  0.0, 0.0],
                [0.5,  1.0, 1.0],
                [1.0,  1.0, 1.0]],
        'green': [[0.0,  0.0, 0.0],
                [0.25, 0.0, 0.0],
                [0.75, 1.0, 1.0],
                [1.0,  1.0, 1.0]],
        'blue':  [[0.0,  0.0, 0.0],
                [0.5,  0.0, 0.0],
                [1.0,  1.0, 1.0]]}
Colormap(cdict)

      custom colormap colormap

    • a callable that accepts an array of 0-1 values and returns another array of 0-1 values:

      Colormap({"red": lambda x: x, "green": lambda x: x**2, "blue": lambda x: x**0.5})

      custom colormap colormap

Callable#

  • A single Callable, object which must accept an array of values and return an (N, 3) or (N, 4) array of colors
    • Colormap(lambda x: np.stack([x, np.sin(x*10), np.cos(x*10)], axis=1))
      custom colormap colormap

Usage#

Useful properties#

... TODO

Immutability#

All colormaps are immutable and cannot be modified after instantiation.

Usage with external visualization libraries#

A primary motivation of cmap is to make it easy to use colormaps in external visualization libraries. To that end, cmap.Colormap provides to_<libname>() methods for a number of libraries:

Tip

Some of these methods take additional arguments, see Colormap API for details.

  • matplotlib

    Colormap("viridis").to_mpl()  # or to_matplotlib()

    Returns an instance of matplotlib.colors.Colormap.

  • napari

    Colormap("viridis").to_napari()

    Returns an instance of napari.utils.colormaps.colormap.Colormap.

  • vispy

    Colormap("viridis").to_vispy()

    Returns an instance of vispy.color.colormap.Colormap.

  • pygfx

    Colormap("viridis").to_pygfx()

    Returns an instance of pygfx.Texture.

  • plotly

    Colormap("viridis").to_plotly()

    Returns a list of tuples, where each tuple is a color stop:

    [
    [0.0, 'rgb(68, 1, 84)'],
    [0.00392156862745098, 'rgb(68, 2, 86)'],
    [0.00784313725490196, 'rgb(69, 4, 87)'],
    [0.011764705882352941, 'rgb(69, 5, 89)'],
    ...

  • bokeh

    Colormap("viridis").to_bokeh()

    Returns an instance of bokeh.models.mappers.LinearColorMapper

  • altair

    Colormap("viridis").to_altair()

    Returns a list of hexadecimal color strings.

  • pyqtgraph

    Colormap("viridis").to_pyqtgraph()

    Returns an instance of pyqtgraph.ColorMap

Usage with pydantic#

Colormap can be used as a field type in pydantic. models.

from pydantic import BaseModel
from cmap import Colormap

class Foo(BaseModel):
    colormap: Colormap


foo = Foo(colormap='viridis')  # or any other ColormapLike
foo.colormap

Serialization in pydantic

Unfortunately, serialization with the json module is not easily pluggable, so if you want to serialize a pydantic model with a Colormap field to JSON, add the following encoder to your model:

class Foo(BaseModel):
    colormap: Colormap

    class Config:
        json_encoders = {Colormap: Colormap.as_dict}

#example
Foo(colormap=['red', 'green']).json()

results in

{"colormap":
    {"name": "custom colormap",
     "identifier": "custom_colormap",
      "category": null,
      "color_stops": [[0.0, [1.0, 0.0, 0.0, 1]], [1.0, [0.0, 0.5019607843137255, 0.0, 1]]]
    }
}

Serialization in psygnal.EventedModel

Colormap supports serialization in psygnal.EventedModel out of the box. The json_encoders = {Colormap: Colormap.as_dict} line in the Config class mentioned above is not necessary.

Rich repr#

If you use rich pretty printing, Colormap objects have a nice repr that shows the color in the terminal

from rich import pretty

pretty.install()

rich repr