`colorsys`

The Python colorsys module provides bidirectional conversion functions between the RGB color space used in computer displays and three alternative color coordinate systems: YIQ, HLS, and HSV. All coordinate values are floating-point numbers in the range 0.0 to 1.0, except in YIQ space where the I and Q components can be negative.

Here’s a quick conversion from RGB to HSV and back:

>>> import colorsys
>>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)
(0.5, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
(0.2, 0.4, 0.4)

Key Features

Converts between RGB and HSV (Hue, Saturation, Value)
Converts between RGB and HLS (Hue, Lightness, Saturation)
Converts between RGB and YIQ (Luminance and chrominance, used in NTSC video)
All conversions are bidirectional with a matching inverse function for each direction
Works entirely with floating-point values normalized to the 0.0 to 1.0 range

Frequently Used Classes and Functions

Object	Type	Description
`colorsys.rgb_to_hsv()`	Function	Converts an RGB color to HSV coordinates
`colorsys.hsv_to_rgb()`	Function	Converts an HSV color to RGB coordinates
`colorsys.rgb_to_hls()`	Function	Converts an RGB color to HLS coordinates
`colorsys.hls_to_rgb()`	Function	Converts an HLS color to RGB coordinates
`colorsys.rgb_to_yiq()`	Function	Converts an RGB color to YIQ coordinates
`colorsys.yiq_to_rgb()`	Function	Converts a YIQ color to RGB coordinates

Examples

Converting a web hex color to HSV. Web colors use the 0-255 range, so divide by 255 first:

>>> import colorsys
>>> r, g, b = 0x33 / 255, 0x66 / 255, 0x99 / 255
>>> colorsys.rgb_to_hsv(r, g, b)
(0.5833333333333334, 0.6666666666666666, 0.6)

Adjusting the lightness of a color using HLS, then converting back to RGB:

>>> import colorsys
>>> h, l, s = colorsys.rgb_to_hls(0.8, 0.4, 0.2)
>>> lighter = colorsys.hls_to_rgb(h, min(1.0, l + 0.2), s)
>>> lighter
(0.88, 0.6399999999999999, 0.5199999999999999)

Common Use Cases

The most common tasks for colorsys include:

Generating color palettes by stepping through hue values in HSV space
Adjusting brightness or saturation of colors without manual conversion math
Processing image pixels that require color space transformations
Comparing colors by perceptual attributes such as lightness or hue
Converting colors between formats for use with graphics or data visualization libraries

Real-World Example

A script can generate an evenly spaced rainbow palette by stepping through hue values in HSV space and converting each to RGB:

import colorsys

def make_palette(n, saturation=0.8, value=0.9):
    palette = []
    for i in range(n):
        hue = i / n
        r, g, b = colorsys.hsv_to_rgb(hue, saturation, value)
        palette.append((round(r * 255), round(g * 255), round(b * 255)))
    return palette

colors = make_palette(6)
for rgb in colors:
    print(rgb)

Run it:

$ python rainbow_palette.py
(230, 46, 46)
(230, 230, 46)
(46, 230, 46)
(46, 230, 230)
(46, 46, 230)
(230, 46, 230)

The function converts each hue fraction to an RGB tuple in the 0-255 range, producing a set of visually distinct colors spread evenly around the color wheel.

Tutorial

Image Processing With the Python Pillow Library

In this step-by-step tutorial, you'll learn how to use the Python Pillow library to deal with images and perform image processing. You'll also explore using NumPy for further processing, including to create animations.

intermediate data-science

For additional information on related topics, take a look at the following resources: