HSLuv: Human-friendly HSL Color Space

5.0.4 · active · verified Tue Apr 14

HSLuv is a Python implementation of a human-friendly HSL (Hue, Saturation, Lightness) color space, which is an alternative to standard HSL. It's built upon CIELUV, a perceptually uniform color space, extending it with a saturation component that allows spanning all available chroma as a percentage. The library, currently at version 5.0.4, provides functions for converting between HSLuv, HPLuv (pastel variant), RGB, and hexadecimal color representations. It maintains an active development status with periodic updates.

Warnings

breaking Version 5.x and later require Python 3.7 or newer. Python 2 users must install `hsluv==5.0.0` or earlier versions for compatibility.
Fix: Upgrade to Python 3.7+ or pin `hsluv` to a version compatible with Python 2 (e.g., `pip install hsluv==5.0.0`).
gotcha The library does not 'clamp' floating point errors, meaning output values for color components might be slightly outside their expected ranges (e.g., RGB values slightly less than 0 or greater than 1, or HSLuv components slightly out of range).
Fix: For display or strict validation, consider rounding the output values to a desired precision or clamping them to their expected ranges after conversion.
gotcha Ensure input types match function expectations. For example, `hsluv_to_rgb` expects hue (0-360), saturation (0-100), and lightness (0-100) as floats. `rgb_to_hsluv` expects R, G, B as floats between 0 and 1. Mis-matched types could lead to unexpected results or `TypeError`s.
Fix: Always refer to the function signatures and documentation to provide inputs in the correct format and range.

Install

pip install hsluv Install stable version

Imports

hsluv_to_hex
```
from hsluv import hsluv_to_hex
```
hex_to_hsluv
```
from hsluv import hex_to_hsluv
```
rgb_to_hsluv
```
from hsluv import rgb_to_hsluv
```
hsluv_to_rgb
```
from hsluv import hsluv_to_rgb
```
hpluv_to_hex
```
from hsluv import hpluv_to_hex
```
hex_to_hpluv
```
from hsluv import hex_to_hpluv
```

Quickstart

This quickstart demonstrates how to use the core conversion functions of the `hsluv` library to transform colors between HSLuv, hexadecimal, and RGB formats. HSLuv takes hue (0-360), saturation (0-100), and lightness (0-100). RGB input/output values are floats between 0 and 1.

from hsluv import hsluv_to_hex, hex_to_hsluv, rgb_to_hsluv, hsluv_to_rgb

# Convert HSLuv to Hex
hsluv_color = [240.0, 100.0, 50.0]  # Blue color (Hue, Saturation, Lightness)
hex_code = hsluv_to_hex(hsluv_color)
print(f"HSLuv {hsluv_color} -> Hex: {hex_code}")

# Convert Hex to HSLuv
parsed_hsluv = hex_to_hsluv("#0000FF") # Pure Blue
print(f"Hex #0000FF -> HSLuv: {parsed_hsluv}")

# Convert RGB to HSLuv (RGB values 0-1)
rgb_color = [0.0, 0.0, 1.0] # Pure Blue
converted_hsluv = rgb_to_hsluv(rgb_color)
print(f"RGB {rgb_color} -> HSLuv: {converted_hsluv}")

# Convert HSLuv to RGB (RGB values 0-1)
hsluv_to_rgb_example = [240.0, 100.0, 50.0] # Blue
converted_rgb = hsluv_to_rgb(hsluv_to_rgb_example)
print(f"HSLuv {hsluv_to_rgb_example} -> RGB: {converted_rgb}")

view raw JSON →