Welcome to colorir’s documentation!

API

• API
  • Palette
  • Color Classes
  • Color Format
  • Gradient
  • Utilities
  • Config
• Examples
  • Custom palettes for plotting
  • Color Wheel with Kivy
  • Palette Picker with Plotly
  • Color Picker with Tkinter
• Built-in Palettes
  • Essentials
  • Birds of Brazil
  • Originals
  • Color Brewer
  • Carto
  • Matplotlib
  • Seaborn
  • Plotly
• Color Index
• Palette Picker

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'] also works

    #00ffff

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

    #007477

>>> palette.cyan - HCLab(0, 25, 0)  # Remove 25 HCLab saturation from cyan

    #a5f3f2

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

    #ff00ff

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.