excolor.colortools

excolor.colortools.show_colors(c=None, names=None, title='', size=None, fmt='hex', verbose=True, ax=None)[source]

Displays a set of colors as a grid layout with color names.

This function creates a visualization of colors, either from a list, a single color, or a colormap. The colors are displayed in a grid with their hex values, and the text color is automatically chosen for readability based on the background color.

Parameters:

  • c (list of str or tuple, str or tuple, or matplotlib.colors.Colormap, optional) – Input colors to display. Can be: - A colormap name or instance - A single color str or rgb tuple - A list of colors str or rgb tuples If None, the matplotlib default color palettes will be shown.

  • names (list of str, optional) – List of color names. If not provided, the hex values will be used.

  • title (str, default='') – Title to display above the color grid

  • size (tuple of int, optional) – Size of the color grid (width, height)

  • fmt (str, default='hex') – Output format of color names (‘hex’, ‘rgb’, ‘hsv’, ‘hsl’)

  • verbose (bool, default=True) – If True, prints the list of colors to the console

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure is created.

Returns:

Displays the color visualization using matplotlib

Return type:

None

Examples

>>> show_colors(['#FF0000', '#00FF00', '#0000FF'])  # Display RGB colors
>>> show_colors('viridis')  # Display viridis colormap colors
>>> show_colors('viridis', size=(10, 5))  # Custom size
>>> show_colors(None)  # Display matplotlib default color palettes
excolor.colortools.list_colors()[source]

Displays a list of default colors as a grid layout with their names.

This function creates a visualization of colors, either from a dictionary, or from the default color palettes. The colors are displayed in a grid with their hex values, and the text color is automatically chosen for readability based on the background color.

Returns:

Displays the color visualization using matplotlib

Return type:

None

excolor.colortools.set_color_cycler(c, n=6, globally=False)[source]

Sets the color cycler for matplotlib.

This function configures the color cycling behavior for the current matplotlib axis using either a list of colors or a colormap. The colors will be used in sequence when plotting multiple lines or other elements.

Parameters:

  • c (list of str, str, or matplotlib.colors.Colormap) – Input colors to use in the cycler. Can be: - A list of color strings or rgb tuples - A colormap name or instance

  • n (int, default=6) – Number of colors to extract from the colormap if a colormap is provided. If a list of colors is provided, this parameter is ignored.

  • globally (bool, default=False) – If True, set the color cycler for all matplotlib axes in current python session. To reset to defaults use: plt.rcdefaults()

Returns:

This function does not return anything; it modifies the matplotlib state.

Return type:

None

Examples

>>> set_color_cycler(['red', 'green', 'blue'])  # Use specific colors
>>> set_color_cycler('viridis', n=5)  # Use 5 colors from viridis
>>> plt.plot(x1, y1)  # Will use first color
>>> plt.plot(x2, y2)  # Will use second color
excolor.colortools.lighten(c, factor=0.1, keep_alpha=False, mode='hls')[source]

Lightens color(s) or a colormap by increasing lightness.

This function takes colors or a colormap and returns lighter versions by increasing their lightness in HLS color space.

Parameters:

  • c (list of str or tuple, str or tuple, or matplotlib.colors.Colormap) – Input colors to display. Can be: - A colormap name or instance - A single color str or rgb tuple - A list of colors str or rgb tuples

  • factor (float, default=0.2) – Increment in lightness between 0 and 1:

  • keep_alpha (bool, default=False) – If True, keep the alpha channel

  • mode (str, default='hls') – If ‘hls’ or ‘hsl’, use HLS color space to lighten the colors If ‘hsv’, use HSV color space to lighten the colors

Returns:

Lightened version of the input color or colors. Returns same type as input.

Return type:

list of str or tuple, str or tuple, or matplotlib.colors.Colormap

Examples

>>> lighten('#FF0000', factor=0.5)  # Lighten red
>>> lighten(['#FF0000', '#00FF00'], factor=0.3)  # Lighten multiple colors
>>> lighten('viridis', factor=0.3)  # Lighten entire colormap
excolor.colortools.darken(c, factor=0.1, keep_alpha=False, mode='hls')[source]

Darkens color(s) or a colormap by decreasing lightness.

This function takes colors or a colormap and returns darker versions by decreasing their lightness in HLS color space.

Parameters:

  • c (list of str or tuple, str or tuple, or matplotlib.colors.Colormap) – Input colors to display. Can be: - A colormap name or instance - A single color str or rgb tuple - A list of colors str or rgb tuples

  • factor (float, default=0.2) – Decrement in lightness between 0 and 1:

  • keep_alpha (bool, default=False) – If True, keep the alpha channel

  • mode (str, default='hls') – If ‘hls’ or ‘hsl’, use HLS color space to darken the colors If ‘hsv’, use HSV color space to darken the colors

Returns:

Darkened version of the input color or colors. Returns same type as input.

Return type:

list of str or tuple, str or tuple, or matplotlib.colors.Colormap

Examples

>>> darken('#FF0000', factor=0.5)  # Darken red
>>> darken(['#FF0000', '#00FF00'], factor=0.3)  # Darken multiple colors
>>> darken('viridis', factor=0.3)  # Darken entire colormap
excolor.colortools.saturate(c, factor=0.1, keep_alpha=False, mode='hls')[source]

Saturates color(s) or a colormap by increasing saturation.

This function takes colors or a colormap and returns more saturated versions by increasing their saturation in HLS color space.

Parameters:

  • c (list of str or tuple, str or tuple, or matplotlib.colors.Colormap) – Input colors to display. Can be: - A colormap name or instance - A single color str or rgb tuple - A list of colors str or rgb tuples

  • factor (float, default=0.2) – Increment in saturation between 0 and 1:

  • keep_alpha (bool, default=False) – If True, keep the alpha channel

  • mode (str, default='hls') – If ‘hls’ or ‘hsl’, use HLS color space to saturate the colors If ‘hsv’, use HSV color space to saturate the colors

Returns:

Saturated version of the input color or colors. Returns same type as input.

Return type:

list of str or tuple, str or tuple, or matplotlib.colors.Colormap

Examples

>>> saturate('#FF0000', factor=0.5)  # Saturate red
>>> saturate(['#FF0000', '#00FF00'], factor=0.3)  # Saturate multiple colors
>>> saturate('viridis', factor=0.3)  # Saturate entire colormap
excolor.colortools.desaturate(c, factor=0.1, keep_alpha=False, mode='hls')[source]

Desaturates color(s) or a colormap by decreasing saturation.

This function takes colors or a colormap and returns less saturated versions by decreasing their saturation in HLS color space.

Parameters:

  • c (list of str or tuple, str or tuple, or matplotlib.colors.Colormap) – Input colors to display. Can be: - A colormap name or instance - A single color str or rgb tuple - A list of colors str or rgb tuples

  • factor (float, default=0.2) – Decrement in saturation between 0 and 1:

  • keep_alpha (bool, default=False) – If True, keep the alpha channel

  • mode (str, default='hls') – If ‘hls’ or ‘hsl’, use HLS color space to desaturate the colors If ‘hsv’, use HSV color space to desaturate the colors

Returns:

Desaturated version of the input color or colors. Returns same type as input.

Return type:

list of str or tuple, str or tuple, or matplotlib.colors.Colormap

Examples

>>> desaturate('#FF0000', factor=0.5)  # Desaturate red
>>> desaturate(['#FF0000', '#00FF00'], factor=0.3)  # Desaturate multiple colors
>>> desaturate('viridis', factor=0.3)  # Desaturate entire colormap