Python colorsys Module: Convert RGB, HSV, and HLS

This article provides an overview of Python's built-in colorsys module, detailing how it facilitates mathematical conversions between the RGB (Red, Green, Blue), HLS (Hue, Lightness, Saturation), and HSV (Hue, Saturation, Value) color spaces. You will learn the core functions available in the module, understand the expected value ranges for inputs and outputs, and see practical examples of converting colors between these representations.

Understanding the colorsys Module

The colorsys module is part of Python's standard library and provides bidirectional conversions between color systems. It operates strictly on mathematical color models and does not manage display outputs or graphical rendering.

A critical characteristic of the colorsys module is its coordinate scale: all color values are expressed as floating-point numbers between 0.0 and 1.0. Traditional integer ranges, such as 0–255 for RGB channels or 0–360° for Hue, must be scaled down before passing them into colorsys functions and scaled back up when processing the output.

Core Conversion Functions

The module provides four primary functions for handling RGB, HLS, and HSV color models:

(Note: The module also includes rgb_to_yiq and yiq_to_rgb for conversions involving the YIQ color space used in broadcast television).

Converting Between RGB and HSV

The HSV model defines colors in terms of Hue (the color type), Saturation (the intensity or purity), and Value (the brightness).

To convert standard 8-bit RGB values (0–255) to HSV:

import colorsys

# Standard 8-bit RGB values
r_255, g_255, b_255 = 255, 128, 0

# Normalize RGB values to the range [0.0, 1.0]
r = r_255 / 255.0
g = g_255 / 255.0
b = b_255 / 255.0

# Convert to HSV
h, s, v = colorsys.rgb_to_hsv(r, g, b)

# Scale Hue to degrees (0-360) and Saturation/Value to percentages (0-100)
hue = h * 360
saturation = s * 100
value = v * 100

print(f"HSV: ({hue:.1f}°, {saturation:.1f}%, {value:.1f}%)")
# Output: HSV: (30.1°, 100.0%, 100.0%)

To convert HSV back to standard 8-bit RGB:

# Convert normalized HSV back to normalized RGB
r_norm, g_norm, b_norm = colorsys.hsv_to_rgb(h, s, v)

# Rescale to 0-255 integer range
rgb_output = (int(round(r_norm * 255)), 
              int(round(g_norm * 255)), 
              int(round(b_norm * 255)))

print(f"RGB: {rgb_output}")
# Output: RGB: (255, 128, 0)

Converting Between RGB and HLS

The HLS model represents color through Hue, Lightness, and Saturation. Unlike HSV, where maximum Value produces the brightest pure color, maximum Lightness in HLS always results in pure white.

To convert standard 8-bit RGB values to HLS:

import colorsys

# Normalized RGB inputs
r, g, b = 0.2, 0.4, 0.8

# Convert to HLS (Hue, Lightness, Saturation)
h, l, s = colorsys.rgb_to_hls(r, g, b)

print(f"HLS normalized: H={h:.2f}, L={l:.2f}, S={s:.2f}")

# Convert back to RGB
r_out, g_out, b_out = colorsys.hls_to_rgb(h, l, s)
print(f"Restored RGB: ({r_out:.1f}, {g_out:.1f}, {b_out:.1f})")

Key Differences Between HLS and HSV in Practice

While both models use Hue to determine the base pigment on a color wheel, their handling of luminance differs: