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
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
Metadata
Release files for colorium 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| colorium-1.0.0.tar.gz | 60.2 kB | Without provenance | Details for colorium-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| colorium-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for colorium-1.0.0-py3-none-any.whl |
Total release size: 105.8 kB
Release files / colorium-1.0.0.tar.gz
| Download URL | colorium-1.0.0.tar.gz |
|---|---|
| Size | 60.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c7d66343583a49bd0decd6a32da94ae0af668759026f0e37ea54b2a6d6e4b87
|
|
BLAKE2b-256 checksum How to use checksums |
d8e264751183b13da6c51b3e52c76ad8d563a5d9cd7f05514f312f74d063b177
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / colorium-1.0.0-py3-none-any.whl
| Download URL | colorium-1.0.0-py3-none-any.whl |
|---|---|
| Size | 45.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d38b3a0f66c280f0f9a8d518de0d9cfabbdf4c57a481d016bee81aec44b06a72
|
|
BLAKE2b-256 checksum How to use checksums |
dc75e692f82f4c248d358c8c67a26c3db8c9173e719a52eb879ffa770078a765
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for colorium 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.