cmaps - Provides easy access to the matplotlib’s colour maps

Purpose:

This module provides an easy-access, light-weight wrapper, around matplotlib’s colour maps, and can be used for retrieving and previewing named colour maps.

Platform:

Linux/Windows | Python 3.7+

Developer:

J Berendt

Email:

support@s3dev.uk

Comments:

n/a

Examples:

Retrieve 5 colours from the ‘viridis’ colour map in hex format and preview the colours:

>>> from utils4.cmaps import cmaps

>>> clrs = cmaps.get_cmap('viridis', 15, as_hex=True, preview=True)
>>> clrs

['#2d718e', '#297b8e', '#25858e', '#218f8d', '#1f998a',
 '#20a386', '#26ad81', '#34b679', '#46c06f', '#5cc863',
 '#73d056', '#8ed645', '#aadc32', '#c5e021', '#fde725']
_images/cmaps_viridis15.png

Fig. 1 Preview of the requested ‘viridis’ colour map of 15 colours

List named colours from the matplotlib colour palette:

>>> from utils4.cmaps import cmaps

>>> cmaps.get_named_colours()

{'aliceblue': '#F0F8FF',
 'antiquewhite': '#FAEBD7',
 'aqua': '#00FFFF',
 ...,
 'whitesmoke': '#F5F5F5',
 'yellow': '#FFFF00',
 'yellowgreen': '#9ACD32'}

List or retrieve colour map names:

>>> from utils4.cmaps import cmaps

>>> cmaps.view_cmaps(view_only=True)

['magma',
 'inferno',
 'plasma',
 ...,
 'tab20_r',
 'tab20b_r',
 'tab20c_r']
class cmaps._Preview(colours)[source]

Provide a preview for a given colourmap.

__init__(colours)[source]

_Preview class initialiser.

Parameters:

colours (Union[list, np.array]) – Iterable of colours for preview.

plot()[source]

Plot to show colours.

_build_dataset()[source]

Create a dataset to be plotted.

class cmaps.CMaps[source]

Provides an easy-access layer to matplotlib’s colour maps.

static get_cmap(map_name: str, n: int = 25, as_hex: bool = False, preview: bool = False) list | numpy.array[source]

Get a list of (n) RGBA or Hex colours from a specified map.

This colour wrapper is specialised to return (n) colours from a normalised colour map. Meaning, rather than returning the 5 lightest colours, or the 200 lightest to medium colours, the lightest colours are removed (as often they are difficult to see in a graph) and the darkest colour is added. The intent is to provide (n) ‘usable’ colours for graphing.

Parameters:
  • map_name (str) – Name of the matplotlib colourmap.

  • n (int, optional) – Number of colours to return. Must be >= 255. Defaults to 25.

  • as_hex (bool, optional) – Return the colours as a hex string. Defaults to False, which returns colours as RGBA.

  • preview (bool, optional) – Preview the colour map. Defaults to False.

Raises:

ValueError – If the value of n is not between 1 and 255.

Returns:

Iterable of (n) colours.

Return type:

Union[list, np.array]

static get_named_colours() dict[source]

Return a dictionary of CSS name and hex value.

Returns:

A dict of named colours as {name: hex_code} pairs.

Return type:

dict

static view_cmaps(view_only: bool = True) list | None[source]

Show the available colour map names.

Parameters:

view_only (bool, optional) – If True the list will be printed and None is returned. If False, the list is returned and nothing is printed. Defaults to True.

Returns:

A list of colour maps names if view-only is False, otherwise None.

Return type:

Union[list, None]