Color and ColorMap

All handling of colors in Plums plot rely on the special Color container class to manipulate colors and a set of ColorMap classes to generate them.

The Color class

The way colors are handled in Plums plot depends on the high-level Colorspacious color handling library and the Color class is a simple container class which delegates all the heavy lifting to colorspacious.

It offers a typed handling of colors and introduces the concept of ctype which represents a color space in which a Color instances live, and thus indicates how its components should be interpreted.

Internally, the actual Color components are stored in the limited but highly common sRGB255 space.

class plums.plot.engine.Color(*components, ctype='sRGB255')

Bases: object

A class representing a color in various spaces with distance and arithmetic.

It is implemented in a immutable fashion, i.e:

• The components property is passive and always returns the Color in ctype space.

• The astype(ctype) method changes the configured ctype in a new, separate Color instance copy.

To sum-up, this means that the Color class acts like an “intelligent” container of some sort which always lives in the same color space (the one it was created in) and may spawn copies of itself in new color spaces.

See also

The current implementation is merely an oriented-object wrapper around the colorspacious library with a convenient “typed” container interface. For more information on the inner workings of color conversion and perceptual theory, please see the colorspacious documentation

Parameters

• *components (int, float) – The Color components in color space ctype.

• ctype (str) – Optional. Default to sRGB255. A color space string specifying in which space components lies.

property ctype

The color space the Color lives in (e.g. “sRGB255” or “JCh”).

See also

For more information on valid color spaces, please see the colorspacious documentation

Type

str

property components

The Color components in the color space specified by ctype.

Type

numpy.ndarray

property ndim

The number of dimension of the component ndarray.

Type

int

property shape

The shape of the component ndarray.

Type

int

astype(ctype)

Make a new Color instance in a new colors space.

The returned Color instance will share the same perceptual properties (e.g. the same “coordinates” of some sort) but the returned components will live in a new color space.

Note that this is a lazy copy operation and that the actual ctype conversion will only be performed during the first time the components attribute is accessed.

Parameters

ctype (str) – A color space string specifying in which space components lies.

Returns

The converted Color instance.

Return type

Color

Note

Nothing is done to take care of “out-of-bounds” values which may occur during conversion to avoid polluting eventual future conversion [2]_.

2

https://colorspacious.readthedocs.io/en/latest/tutorial.html#perceptual-transformations

Color Maps

A ColorMap performs a link between a set \(\mathcal{V} \subset \mathbb{R}\) of value and a set \(\mathcal{C}^S \subset S\) of colors (where \(S\) is a given color space).

Note that both sets might be infinite, in which case we construct a ContinuousColorMap, or finite, in which case we construct a DiscreteColorMap.

class plums.plot.engine.ColorMap(ctype='sRGB255', map_fn=None)

Bases: abc.ABC

An abstract base class for all ColorMap classes.

Subclass must implement the private _get_color() method which maps a given value to a Color instance.

Parameters

• ctype (str) – A valid Color return type in which colors returned by the color map will be.

• map_fn (Callable) – A function (ideally continuous and monotonically increasing) which take in a number and returns a number.

ctype

A valid Color return type in which colors returned by the color map will be.

Type

str

map_fn

A function (ideally continuous and monotonically increasing) which (ideally bijectivelly) maps input values to a working range.

Type

Callable

property range

The input range supported by the ColorMap.

Warning

The range returned corresponds to the input range mapped through map_fn

Type

tuple

get_color(value)

Get the Color corresponding to the value provided.

Note

The actual value used to get the corresponding Color is the value provided mapped through map_fn.

Parameters

value (float) – The value to get a Color for.

Returns

The corresponding Color.

Return type

Color

__call__(array, keep_colors=False)

Generalizes get_color() on ndarray inputs.

Note that because on the non-vectorized nature of color maps, this is not guaranteed to be a fast operation.

It is however included to allow for readable color mapping on arrays.

Parameters

• array (ndarray) – An array on which to apply the color map.

• keep_colors (bool) – Optional. Default to False. If True, returns an array of Color, otherwise, an ndarray of components is returned.

Returns

An array of Color or components corresponding to values in array.

Return type

ndarray

astype(ctype)

Make a new ColorMap instance in a new colors space.

The returned ColorMap instance will share the same perceptual properties (e.g. the same “coordinates” of some sort) but the returned components will live in a new color space.

Note that this is a lazy copy operation and that the actual ctype conversion will only be performed during the first time the get_color() attribute is called.

Parameters

ctype (str) – A color space string specifying in which space returned Color lie.

Returns

The converted ColorMap instance.

Return type

ColorMap

Note

Nothing is done to take care of “out-of-bounds” values which may occur during conversion to avoid polluting eventual future conversion [2]_.

2

https://colorspacious.readthedocs.io/en/latest/tutorial.html#perceptual-transformations

Constructor classes

Concrete color maps classes