Utilities

colorir.utils.swatch(obj, colored_text=True, width=3, height=1, tabular=True, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Swatches a colorir object in the terminal.

Each swatch consists of a rectangle of a color followed by its value (and name if known).

Parameters:

  • obj – What will be represented in the terminal. Is either a single color, a list of colors, a Palette, a StackPalette or a subclass of Grad.

  • colored_text – Whether the text that follows the colored rectangles should also be colored.

  • width – The width (in space characters) of the colored rectangles.

  • height – The height (in number of lines) of the colored rectangles.

  • tabular – Whether the colored rectangle, color name and color value should be printed each in its separate column. Only used if obj is a Palette.

  • file – If None returns the swatch as a string. Otherwise, this argument must be a file object and is passed to print.

colorir.utils.show(obj, width=None, height=None, interactive=None, inline=True)

Shows a colorir object inlined on a Jupyter notebook or using tkinter.

Parameters:

  • inline – If running on a Jupyter notebook, whether to display the object inline. Requires Pillow to be installed.

  • obj –

  • width –

  • height –

  • interactive – Whether clicking of the screen will copy the color value to the clipboard and swatch the color on the terminal. Setting this parameter to False results is a dramatic speed-up. By default, is set to True for small objects (less than 100 colors) and False otherwise. Only has an effect if not running on a Jupyter notebook with inline == True.

colorir.utils.simplified_dist(color1, color2)

Calculates the perceived distance between two colors.

There are many methods to approach the similarity of colors mathematically. The algorithm implemented in this function [1] tries to provide balance between efficiency and accuracy by using a weighted euclidian distance formula in the RGB color space.

References

Parameters:

  • color1 (ColorBase | str | tuple) – First color point.

  • color2 (ColorBase | str | tuple) – Second color point.

colorir.utils.color_dist(color1, color2, method='CIE76')
colorir.utils.random_color(random_a=False, color_format=None)

Generates a new random color.

Parameters:

  • random_a – Whether to randomize the alpha attribute as well or just make it 1.

  • color_format (ColorFormat | None) – Specifies the format of the output color. Defaults to config.DEFAULT_COLOR_FORMAT.

Examples

>>> random_color()  
Hex('#304fcc')
colorir.utils.color_str(string, fg_color=None, bg_color=None)

Returns an ANSI-escaped [2] colored representation of string.

Examples

>>> print(color_str("It's Christmas!", "#ff0000", "#00ff00"))
Parameters:

  • string (str) – String that will be colored.

  • fg_color (ColorBase | str | tuple | None) – Color to be applied to the foreground of the text.

  • bg_color (ColorBase | str | tuple | None) – Color to be applied to the background of the text.

References

colorir.utils.hue_sort_key(hue_classes=None, gray_thresh=12.0, gray_start=True, alt_lum=False, invert_lum=False)

Returns a function that can be used as a key for python’s ‘sort’ and ‘sorted’ in order to sort color-like objects by their hue component.

Examples

>>> sorted(["0000ff", "ff0000",  "000000", "00ff00", "ffffff"], key=hue_sort_key())
['000000', 'ffffff', 'ff0000', '00ff00', '0000ff']
Parameters:

  • hue_classes – Number hue categories. Inside each hue category colors will be sorted by luminance rather than hue. When None, colors are sorted only according to their hue.

  • gray_thresh – Chroma threshold bellow which a color will be considered a shade of gray.

  • gray_start – Whether the colors considered shades of gray will be grouped at the start or end of the sorted iterable.

  • alt_lum – Whether to alternate luminance values with each hue class transition. Only has an effect if hue_classes > 1.

  • invert_lum – By default, sorting within hue classes happen from darker to lighter colors. This parameter allows inverting this patern, thus starting with light colors and going towards darker tones. Only has an effect if hue_classes > 1.

Notes

The refered hue and chroma components are those of HCLab.

colorir.utils.hue_sorted(colors, **kwargs)

Sort colors by their hue values. See hue_sort_key() for the arguments docs.

Returns:

A list of sorted colors.

Return type:

List[ColorBase | str | tuple]

colorir.utils.grayscale(obj)

Returns a grayscale representation of a colorir object

colorir.utils.inverse(obj)

Returns an RGB-inverted representation of a colorir object

colorir.utils.blend(color1, color2, perc=0.5, grad_class=<class 'colorir.gradient.Grad'>, **kwargs)