Welcome to colorir’s documentation!

Contents

What is colorir?

colorir is a package used to create and manipulate palettes and colors. What makes colorir different from other similar packages like colour and palettable is that colorir focuses on personalization and interoperability: you can create your own color palettes and use them with any other python package such as matplotlib, tkinter or flask.

Main features

  • Create color schemes and save them to use in different projects

  • Interpolate colors in different formats (such as RGB, CIELab etc) to make gradients and color maps

  • Have access to a curated selection of unique color palettes and color names

  • Easily visualize swatches of colors in the terminal

Installation

Note

If you encounter permission errors when using colorir, please consider re-installing the package in user mode (by including the --user flag in the pip install command).

To install colorir with pip use following command:

$ python -m pip install colorir

Quick-Start

Create a palette with the additive elementary colors:

>>> palette = Palette(red="#ff0000",
...                   green="#00ff00",
...                   blue="#0000ff")

Following CSS color-naming conventions, our color names are all lowercase with no underscores, but you may name a color as you wish as long as it complies with python’s syntax for attribute names.

Let’s take a look at our palette in the terminal:

>>> palette  # Prints swatches representing the palette

    red #ff0000

    green #00ff00

    blue #0000ff

To add colors to a palette use the Palette.add() method:

>>> palette.add("cyan", "#00ffff")
>>> palette.add("yellow", HSL(60, 1, 0.5))  # We can pass colors in formats other than hex as well
>>> palette.add("magenta", CIELab(60, 98, -60))  # They will be internally converted to match the rest of the palette
>>> palette

    red #ff0000

    green #00ff00

    blue #0000ff

    cyan #00ffff

    yellow #ffff00

    magenta #ff00ff

To access the colors in a palette we can use dot attribute syntax:

>>> palette.cyan  # palette['cyan'] or palette[3] also works

    #00ffff

We can manipulate the properties of a color by adding and removing color components from other color systems:

>>> palette.cyan - CIELab(50, 0, 0)  # Remove 50 CIELab lightness from cyan

    #007477 

>>> palette.cyan * HCLab(1, 0.5, 1)  # Desaturate cyan by 50%

    #a5f3f2

Color arithmetic can also be done to all colors in a palette at once:

>>> palette * HCLab(1, 0.5, 1)

    red #c96047

    green #a0f08a

    blue #5437a2

    cyan #a5f3f2

    yellow #fffa9a

    magenta #cb6fc6

See the color_class module for details on how to manipulate colors with arithmetics.

To interpolate colors we can use blend():

>>> blend(palette.yellow, palette.magenta, 0.5)  # Get color at 50% between yellow and magenta

    #f9afbe

blend() is actually a wrapper around the Grad class, which supports interpolation in different color systems:

>>> Grad([palette.yellow, palette.magenta], color_sys=CIELab).n_colors(5)  # Interpolates 5 colors from yellow to magenta

    #ffff00

    #ffd471

    #ffa6a6

    #ff71d3

    #fe00fd

Naturally good-looking palettes can also be easily created with new_analogous() and new_complementary(). These methods return a StackPalette, which behaves a lot like a Palette except that it holds unnamed colors:

>>> spalette = StackPalette.new_analogous(4)
>>> spalette

    #ffd48d

    #dce083

    #afea95

    #7bf0b9

You can also convert a StackPalette to a Palette using the to_palette() method:

>>> palette2 = spalette.to_palette()

Both StackPalette and Palette objects can be indexed numerically, sliced and combined with the ‘&’ operator:

>>> palette[[0, -1]] & palette2[1:]

    red #ff0000

    magenta #fe00fd

    c2 #afea95

    c3 #7bf0b9

To save a palette use Palette.save():

>>> palette.save(name="elementary")  # Name palette 'elementary' and save it in the default palette directory

You can then later reload the palette in another script with Palette.load():

>>> palette = Palette.load("elementary")

When loading or creating a palette, a ColorFormat may be passed to the constructor to specify how we want its colors to be represented:

>>> c_format = ColorFormat(color_sys=HSL)
>>> css = Palette.load("css", color_format=c_format)
>>> css.red
HSL(0.0, 1.0, 0.5)  # Tuple HSL representation

Alternatively, we can temporarily change the default color format project-wide so that new palettes default to it:

>>> from colorir import config, PYGAME_COLOR_FORMAT
>>> config.DEFAULT_COLOR_FORMAT = PYGAME_COLOR_FORMAT  # Change default format to a pre-defined PyGame-compatible color format
>>> pygame_palette = Palette(red=(255, 0, 0), green="#00ff00")
>>> pygame_palette.red
RGB(255, 0, 0)
>>> pygame_palette.green
RGB(0, 255, 0)  # The green hex code is now converted to RGB format

It is worth noting that all color classes inherit either tuple or str, meaning that no conversion is needed when passing them to other frameworks such as PyGame, Kivy and HTML embedding templates like Jinja.

For more information, see the Examples and consult colorir’s API.