Colorium

A comprehensive, pure Python color manipulation library with support for 10+ color spaces, filters, and color distance calculations.

Features

• 10+ Color Spaces: RGB, HSL, HWB, CMYK, NCOL, OKLCH, LAB, LCH, Display P3
• Color Filters: Sepia, Grayscale, Invert, Contrast, Brightness, Saturation, Hue Rotation, Posterize, Temperature, Vignette
• Filter Presets: Clarendon, Gingham, Moon, Lark, Toaster, Valencia, Amaro (Instagram-style)
• Color Distance: CIE76, CIE94, CIEDE2000 (industry standard)
• Color Similarity: Perceptual similarity scoring (0.0 to 1.0)
• Named Colors: All 147 CSS named colors with case-insensitive lookup
• Color Constants: RED, BLUE, GREEN, WHITE, BLACK, and 100+ more
• Multiple Formats: Hex, RGB, HSL, HWB, CMYK, NCOL, OKLCH, LAB, LCH, P3
• Zero Dependencies: Pure Python, no external libraries required

Installation

# Install from PyPI (when published)
pip install colorium

# Install in development mode
git clone https://github.com/inject3r/colorium.git
cd colorium
pip install -e ".[dev]"

Quick Start

from colorium import Color, from_string, RED, BLUE, WHITE, BLACK

# Create colors from various formats
red = Color(255, 0, 0)
blue = from_string("blue")
hex_color = from_string("#FF0000")
named = from_string("crimson")

# Use color constants
bg = WHITE
text = BLACK
primary = RED
secondary = BLUE

# Convert between color spaces
print(red.to_hsl_string())        # hsl(0, 100%, 50%)
print(red.to_hwb_string())        # hwb(0, 0%, 0%)
print(red.to_hex_string())        # #FF0000
print(red.to_cmyk_string())       # cmyk(0%, 100%, 100%, 0%)

# Get color values
hsl = red.to_hsl()                # {'h': 0, 's': 1.0, 'l': 0.5}
rgb = red.to_rgb()                # {'r': 255, 'g': 0, 'b': 0}

# Manipulate colors
red.lighter(0.3)                  # Make brighter
red.darker(0.2)                   # Make darker
red.saturate(0.5)                 # Increase saturation
red.desaturate(0.3)               # Decrease saturation

# Check if color is dark
if red.is_dark():
    print("Dark color!")

# Get color name
print(red.to_name())              # "Red"

# Blend colors
purple = RED.blend(BLUE, 0.5)    # Equal blend
pink = RED.blend(WHITE, 0.7)     # 70% white blend

Color Filters

from colorium import (
    Color,
    SepiaFilter,
    GrayscaleFilter,
    ContrastFilter,
    BrightnessFilter,
    FilterPresets
)

color = Color(200, 150, 100)

# Single filter
sepia = SepiaFilter(0.7)
result = sepia(color)

# Chain filters
from colorium import CompositeFilter
vintage = CompositeFilter([
    SepiaFilter(0.5),
    ContrastFilter(1.1),
    BrightnessFilter(0.9)
])
vintage_result = vintage(color)

# Use presets
clarendon = FilterPresets.clarendon()
clarendon_result = clarendon(color)

moon = FilterPresets.moon()      # Black and white
moon_result = moon(color)

Color Distance and Similarity

from colorium import Color

color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)

# Calculate color difference (Delta E)
distance = color1.delta_e(color2, "cie2000")
print(f"Delta E: {distance:.2f}")

# Get similarity score (0.0 to 1.0)
similarity = color1.similarity(color2)
print(f"Similarity: {similarity:.2f}")

# Check if colors are similar
if color1.is_similar_to(color2, threshold=0.8):
    print("Colors are very similar!")

# Different methods available
cie76 = color1.delta_e(color2, "cie76")
cie94 = color1.delta_e(color2, "cie94")
cie2000 = color1.delta_e(color2, "cie2000")

Modern Color Spaces (CSS Color Level 4)

from colorium import Color

# OKLCH - Perceptually uniform
color = Color.from_oklch(0.5, 0.2, 180)
print(color.to_oklch_string())   # oklch(50.0% 0.200 180.0)

# CIE L*a*b*
color = Color.from_lab(50, 20, -30)
print(color.to_lab_string())     # lab(50.0% 20.0 -30.0)

# CIE LCH
color = Color.from_lch(50, 30, 180)
print(color.to_lch_string())     # lch(50.0% 30.0 180.0)

# Display P3 Wide Gamut
color = Color.from_p3(0.8, 0.3, 0.5)
print(color.to_p3_string())      # color(display-p3 0.800 0.300 0.500)

Color Constants

from colorium import (
    RED, BLUE, GREEN, WHITE, BLACK,
    SUCCESS, ERROR, WARNING, INFO,
    FACEBOOK_BLUE, TWITTER_BLUE, YOUTUBE_RED,
    ORANGE, PURPLE, PINK, BROWN,
    LIGHT_BLUE, DARK_BLUE, NAVY, ROYAL_BLUE,
    LIGHT_GREEN, DARK_GREEN, FOREST_GREEN,
    TRANSPARENT
)

# Use constants directly
status = SUCCESS if valid else ERROR
bg = WHITE
text = BLACK

# Blend constants
purple = RED.blend(BLUE, 0.5)

# Use as defaults
def create_button(text: str, color: Color = PRIMARY):
    return {"text": text, "color": color}

API Reference

Color Class

Method	Description
Color(red, green, blue, opacity=1.0)	Create from RGB
to_rgb_string()	RGB string: rgb(255, 0, 0)
to_rgba_string()	RGBA string: rgba(255, 0, 0, 0.5)
to_hsl_string()	HSL string: hsl(0, 100%, 50%)
to_hwb_string()	HWB string: hwb(0, 0%, 0%)
to_cmyk_string()	CMYK string: cmyk(0%, 100%, 100%, 0%)
to_hex_string()	Hex string: #FF0000
to_oklch_string()	OKLCH string: oklch(50% 0.2 180)
to_lab_string()	LAB string: lab(50% 20 -30)
to_lch_string()	LCH string: lch(50% 30 180)
to_p3_string()	P3 string: color(display-p3 0.8 0.3 0.5)
to_name()	CSS color name: "Red"
to_rgb()	RGB dict: {'r': 255, 'g': 0, 'b': 0}
to_hsl()	HSL dict: {'h': 0, 's': 1.0, 'l': 0.5}
delta_e(other, method)	Color difference (CIE76, CIE94, CIEDE2000)
similarity(other, method)	Similarity score (0.0 to 1.0)
is_similar_to(other, threshold)	Check similarity
blend(other, ratio)	Blend two colors
is_dark(threshold=128)	Check if dark
saturate(amount)	Increase saturation
desaturate(amount)	Decrease saturation
lighter(amount)	Increase lightness
darker(amount)	Decrease lightness
clone()	Create a copy

Factory Functions

Function	Description
from_string(color_str)	Parse any color string
from_hex(hex_str)	Create from hex
from_rgb(r, g, b, opacity=1.0)	Create from RGB
from_hsl(h, s, l, opacity=1.0)	Create from HSL
from_hwb(h, w, b, opacity=1.0)	Create from HWB
from_cmyk(c, m, y, k, opacity=1.0)	Create from CMYK
from_oklch(l, c, h, opacity=1.0)	Create from OKLCH
from_lab(l, a, b, opacity=1.0)	Create from LAB
from_lch(l, c, h, opacity=1.0)	Create from LCH
from_p3(r, g, b, opacity=1.0)	Create from P3

Filters

Filter	Description
SepiaFilter(intensity=1.0)	Warm sepia tone
GrayscaleFilter(method="luminance")	Black and white
InvertFilter()	Negative effect
ContrastFilter(amount=1.2)	Contrast adjustment
BrightnessFilter(amount=1.2)	Brightness adjustment
SaturationFilter(amount=0.5)	Saturation adjustment
HueRotateFilter(degrees=90)	Hue rotation
PosterizeFilter(levels=4)	Color quantization
TemperatureFilter(kelvin=5500)	Warm/cool shift
VignetteFilter(intensity=0.5)	Edge darkening

Filter Presets

Preset	Description
FilterPresets.clarendon()	Increased contrast, brightness, saturation
FilterPresets.gingham()	Warm, soft vintage
FilterPresets.moon()	High-contrast black and white
FilterPresets.lark()	Cool, vibrant modern
FilterPresets.toaster()	Warm, retro vintage
FilterPresets.valencia()	Warm, soft vintage
FilterPresets.amaro()	Rich, warm, slightly dark

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=colorium

# Run specific test file
pytest tests/test_color.py

# Run specific test
pytest tests/test_color.py::TestColor::test_initialization

Code Style

The project uses:

• Black for code formatting
• Flake8 for linting
• Mypy for type checking

# Format code
black src/ tests/

# Run linter
flake8 src/ tests/

# Type check
mypy src/

License

MIT License - see LICENSE for details.

Author

Abolfazl Hosseini

• Email: tryuzr@gmail.com
• GitHub: @inject3r

Links

• Source Code
• Bug Tracker
• Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• CSS Color Module Level 4 specification
• CIE color science standards
• Natural Color System (NCS) for NCOL notation
• Instagram filter effects for inspiration