Colorium Documentation

Welcome to Colorium — the ultimate color toolkit for Python developers. Whether you're building design tools, data visualizations, or just need to work with colors programmatically, Colorium provides everything you need in a clean, intuitive API.

What is Colorium?

Colorium is a modern Python library designed for developers who need precise control over color manipulation. Built with a focus on simplicity and power, it transforms complex color operations into straightforward, readable code.

Core Philosophy

Simplicity without compromise. Colorium handles the complexity so you can focus on what matters — your application. Every feature is designed to be intuitive, well-documented, and accessible to developers of all skill levels.

Key Highlights

10+ Color Spaces — Work seamlessly across RGB, HSL, HWB, CMYK, OKLCH, LAB, LCH, and Display P3. Convert between any space with a single method call.
Rich Filter System — Apply professional-grade filters including sepia, grayscale, invert, contrast adjustment, brightness control, and saturation manipulation. Chain filters together for complex effects.
Perceptual Color Distance — Calculate accurate color differences using CIE76, CIE94, or the industry-standard CIEDE2000 algorithm. Determine color similarity with human-perception-based scoring.
147 Named Colors — Access all CSS named colors with case-insensitive lookup. Never memorize hex codes again.
CSS Color Level 4 Support — Stay ahead with modern color specifications including OKLCH, LAB, LCH, and Display P3 wide gamut support.
Zero External Dependencies — Pure Python implementation. No third-party libraries required. Install and run instantly.
Production Ready — Comprehensive test coverage, type hints, and battle-tested algorithms ensure reliability.

Why Colorium?

Challenge	Solution
Working with multiple color spaces	Unified Color class with automatic conversion between 10+ spaces
Complex color calculations	Simple methods like `.delta_e()` and `.similarity()` for perceptual comparisons
Finding the right filter	10+ built-in filters with easy composition
Remembering hex codes	147 named colors with case-insensitive lookup
External dependencies	Pure Python — zero dependencies
Modern color standards	CSS Color Level 4 support (OKLCH, LAB, LCH, P3)

Quick Start

from colorium import Color, from_string, RED, BLUE

# Create colors from any format
red = Color(255, 0, 0)
blue = from_string("blue")
crimson = from_string("crimson")

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

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

# Compare colors
distance = RED.delta_e(BLUE, "cie2000")
similarity = RED.similarity(BLUE)

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

Documentation Sections

Section	Description
Getting Started	Installation, quick start, and usage examples
Core Concepts	Color spaces, creation, manipulation, and conversion
Features	Filters, blending, distance, similarity, and named colors
Advanced	Custom color spaces, performance, integration, and contributing
API Reference	Complete API documentation for all classes and functions
Changelog	Version history and release notes

Who Is Colorium For?

Python Developers — Anyone building applications that need color handling
Data Scientists — Visualizing data with accurate color representation
Designers — Prototyping color palettes and schemes
UI/UX Engineers — Building design systems and theming engines
Researchers — Working with color perception and analysis

License

Colorium is open source software released under the MIT License. Use it freely in personal, commercial, and enterprise projects.

Version

Version: v1.0.0