cmap.Colormap#

Map scalar values in X to an RGBA array.

This is the primary API for "using" a cmap.Colormap to map scalar values to colors.

The dtype of x matters. If x is an integer dtype, then it is interpreted as (fancy) indexing directly into the LUT. If x is a float, then it is assumed to be a normalized value in [0, 1] and will be mapped linearly to the nearest color in the LUT (use a higher N for finer sampling).

Parameters:

• x (float | array - like) –

  The scalar values to map to colors. If x is a float, a single color object will be returned. If x is an array-like, an array of RGBA colors will be returned with shape x.shape + (4,). See note above about the dtype of x.

• N (int, default: 256 ) –

  Number of samples in the LUT. This is used to determine the resolution of the mapping (by default, 256). Note that depending on the data being mapped, N can cause slight rounding errors in some cases. N of 256 is the default in matplotlib, so it is here as well, but note that N=255 (odd numbered) will result in an exact color match being returned for a value of 0.5 in a colormap with an odd number of colors.

• gamma (float, default: 1 ) –

  The gamma value to use when creating the LUT.

• bytes (bool, default: False ) –

  If False (default), the returned RGBA values will be floats in the interval [0, 1] otherwise they will be numpy.uint8\s in the interval [0, 255].

Returns:

• color ( Color | NDArray ) –

  If X is a float, a single RGBA color will be returned. If x is an array-like, an array of RGBA colors will be returned with shape x.shape + (4,)

Examples:

>>> from cmap import Colormap
>>> from tifffile import imread
>>> cmap = Colormap("viridis")
>>> data = imread('some_path.tif')
>>> data = data - data.min()  # normalize to 0-1
>>> data = data / data.max()  # normalize to 0-1
>>> colored_img = cmap(data)

Return a dictionary representation of the colormap.

The returned dictionary is suitable for serialization, or for passing to the Colormap constructor.

Return the global colormaps catalog.

Return a list of N color objects sampled evenly over the range of the LUT.

If N is an integer, it will return a list of N colors spanning the full range of the colormap. If N is an iterable, it will return a list of colors at the positions specified by the iterable.

Parameters:

• N (int | Iterable[float] | None, default: None ) –

  The number of colors to return, or an iterable of positions to sample. If not provided (the default), N will be set to the number of colors in the colormap.

Yields:

• color ( Color ) –

  Color objects.

Return a lookup table (LUT) for the colormap.

The returned LUT is a numpy array of RGBA values, with shape (N, 4), where N is the number of requested colors in the LUT. If with_over_under is True the returned shape will be (N + 3, 4), where index N is the under color, index N + 1 is the over color, and index N + 2 is the bad (NaN) color.

The LUT can be used to map scalar values (that have been normalized to 0-1) to colors, using fancy indexing or np.take.

The output of this function is used by the __call__ method, but may also be used directly by users.

LUTs of a particular size and gamma value are cached.

Parameters:

• N (int, default: 256 ) –

  The number of colors in the LUT.

• gamma (float, default: 1 ) –

  The gamma value to use for the LUT.

• with_over_under (bool, default: False ) –

  If True, the LUT will include the under, over, and bad colors as the last three colors in the LUT. If False, the LUT will only include the colors defined by the color_stops.

Return a new Colormap, with reversed colors.

Parameters:

• name (str | None, default: None ) –

  By default, the name of the new colormap will be the name of the original colormap with "_r" appended. If the original colormap name ends in "_r", the new colormap name will be the original name with "_r" removed. If the name argument is provided, it will be used as the name of the new colormap.

Return a new Colormap, with colors shifted by a scalar value.

This method shifts the stops in the colormap by a scalar value. It makes most sense for cyclic colormaps, but can be used with any colormap.

Parameters:

• shift (float, default: 0.5 ) –

  The amount to shift the colormap. Positive values shift the colormap towards the end, negative values shift the colormap towards the beginning.

• name (str, default: None ) –

  A new name for the colormap. If not provided, the name of the new colormap will be the name of the original colormap with "_shifted{shift}" appended.

• mode (('wrap', 'clip'), default: 'wrap' ) –

  The mode to use when shifting the colormap. Must be one of 'wrap' or 'clip'. If 'wrap', the colormap will be shifted and wrapped around the ends. If 'clip', the colormap will be shifted and the colors at the ends will be clipped and/or repeated as necessary.

Returns:

• Colormap –

  A new colormap with the colors shifted.

Return an altair colorscale with N color samples from the colormap.

Suitable for passing to the range parameter of altair.Scale. https://altair-viz.github.io/user_guide/customization.html#color-domain-and-range

Return a bokeh colorscale, with N color samples from the colormap.

https://docs.bokeh.org/en/latest/docs/reference/models/mappers.html

Parameters:

• N (int, default: 256 ) –

  Number of colors to sample from the colormap, by default 256.

Return a CSS representation of the colormap as a linear or radial gradient.

Parameters:

• max_stops (int, default: None ) –

  May be used to limit the number of color stops in the css.

• angle (int, default: 90 ) –

  Angle of the gradient in degrees. by default 90. (ignored for radial)

• radial (bool, default: False ) –

  If True, return a radial gradient, by default False.

• as_hex (bool, default: False ) –

  If True, return colors as hex strings, by default use rgba() strings.

Examples:

>>> from cmap import Colormap
>>> print(Colormap("brg").to_css())
background: rgb(0, 0, 255);
background: linear-gradient(
    90deg, rgb(0, 0, 255) 0%, rgb(255, 0, 0) 50%, rgb(0, 255, 0) 100%
);

Return a matplotlib colormap.

Return a napari colormap.

https://napari.org/stable/api/napari.utils.Colormap.html

Return a plotly colorscale.

Return a pygfx Texture.

Return a pyqtgraph.ColorMap.

Plot colormap using viscm. (Requires viscm to be installed.).

See https://github.com/matplotlib/viscm for details

Parameters:

• dpi (int, default: 100 ) –

  dpi for saved image. Defaults to 100.

• dest (str, default: None ) –

  If provided, the image will be saved to this path. Defaults to None.

Returns:

• fig ( matplotlib.figure.Figure ) –

  The figure object containing the plot.

Return a vispy colormap.

Return a copy of the colormap with new extreme values.

Return (N, 5) array, N rows of (position, r, g, b, a).

Get an item or slice of the color stops.

If key is an integer, return a single ColorStop tuple. If key is a slice, return a new ColorStops object. If key is a tuple, return a numpy array (standard numpy indexing).

Return a string representation of the ColorStops.

Parse any colorstops-like object into a ColorStops object.

Each item in colors can be a color, or a 2-tuple of (position, color), where position (the "stop" along a color gradient) is a float between 0 and 1. Where not provided, color positions will be evenly distributed between neighboring specified positions (if fill_mode is 'neighboring') or will be replaced with index / (len(colors)-1) (if fill_mode is 'fractional').

Colors can be expressed as anything that can be converted to a Color, including a string, or 3/4-sequence of RGB(A) values.

Parameters:

• colors (str | Iterable[Any]) –

  Colors and (optional) stop positions.

Returns:

• ColorStops –

  A sequence of color stops.

Return a new ColorStops object with reversed colors.

Return a new ColorStops object with all positions shifted by shift.

Parameters:

• shift (float) –

  The amount to shift the colormap. Positive values shift the colormap towards the end, negative values shift the colormap towards the beginning.

• mode (('wrap', 'clip'), default: 'wrap' ) –

  The mode to use when shifting the colormap. Must be one of 'wrap' or 'clip'. If 'wrap', the colormap will be shifted and wrapped around the ends. If 'clip', the colormap will be shifted and the colors at the ends will be clipped and/or repeated as necessary.

Return a CSS representation of the color stops.

Parameters:

• max_stops (int, default: None ) –

  May be used to limit the number of color stops in the css.

• angle (int, default: 90 ) –

  Angle of the gradient in degrees. by default 90. (ignored for radial)

• radial (bool, default: False ) –

  If True, return a radial gradient, by default False.

• as_hex (bool, default: False ) –

  If True, return colors as hex strings, by default use rgba() strings.

Create (N, 4) LUT of RGBA values from 0-1, interpolated between color stops.

Parameters:

• N (int, default: 256 ) –

  Number of colors to return.

• gamma (float, default: 1.0 ) –

  Gamma correction to apply to the colors.