Welcome to colorir’s documentation!
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.
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
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
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
To add colors to a palette use the
>>> 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
To access the colors in a palette we can use dot attribute syntax:
>>> palette.cyan # palette['cyan'] also works
We can make 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
>>> palette.cyan - HCLab(0, 25, 0) # Remove 25 HCLab saturation from cyan
color_class module for details on how to manipulate colors with arithmetics.
To interpolate colors we can use
>>> blend(palette.yellow, palette.magenta, 0.5) # Get color at 50% between yellow and magenta
>>> Grad([palette.yellow, palette.magenta], color_sys=CIELab).n_colors(5) # Interpolates 5 colors from yellow to magenta
To save a palette use
>>> 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 = 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
str, meaning that
no conversion is needed when passing them to other frameworks such as PyGame, Kivy and HTML embedding
templates like Jinja.