Skip to main content

Colorium

Python Version License Tests

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

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

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)

Source distribution for colorium 1.0.0
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)

Table of built distributions (wheels) for colorium 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page