D
Documentation
v1.0.0
Features Overview
Colorium provides a comprehensive set of features for working with colors in Python. This section covers all the major features available in the library.
Feature Categories
| Category | Description |
|---|---|
| Color Spaces | 10+ color spaces with automatic conversion |
| Color Filters | Professional-grade filters and effects |
| Color Blending | Advanced color blending operations |
| Color Distance | Perceptual color difference calculations |
| Color Similarity | Similarity scoring based on human perception |
| Named Colors | 147 CSS named colors with case-insensitive lookup |
| Color Constants | Pre-defined color constants for common colors |
| Color Conversion | Seamless conversion between all formats |
| Color Manipulation | Complete color manipulation toolkit |
Color Spaces
Colorium supports 10+ color spaces with automatic conversion between them.
Supported Color Spaces
- RGB — Red, Green, Blue (standard display color space)
- HSL — Hue, Saturation, Lightness (intuitive color selection)
- HWB — Hue, Whiteness, Blackness (simpler color selection)
- CMYK — Cyan, Magenta, Yellow, Black (print color space)
- OKLCH — Lightness, Chroma, Hue (perceptually uniform)
- LAB — L*, a*, b* (perceptual color space)
- LCH — L*, C*, h (cylindrical LAB)
- Display P3 — Wide gamut color space
- NCOL — Natural Color notation
Example
1
2
3
4
5
6
7
8
9
from colorium import Color
color = Color(255, 0, 0)
# Convert between color spaces
print(color.to_hsl_string()) # hsl(0, 100%, 50%)
print(color.to_hwb_string()) # hwb(0, 0%, 0%)
print(color.to_cmyk_string()) # cmyk(0%, 100%, 100%, 0%)
print(color.to_oklch_string()) # oklch(62.8% 0.258 29.2)Color Filters
Apply professional-grade filters to transform colors.
Available Filters
| Filter | Description |
|---|---|
| Sepia | Warm sepia tone effect |
| Grayscale | Convert to black and white |
| Invert | Negative effect |
| Contrast | Adjust contrast |
| Brightness | Adjust brightness |
| Saturation | Adjust saturation |
| Hue Rotation | Rotate hue |
| Posterize | Reduce color levels |
| Temperature | Warm/cool adjustment |
| Vignette | Edge darkening |
Filter Presets
Instagram-style presets for quick effects:
- Clarendon
- Gingham
- Moon
- Lark
- Toaster
- Valencia
- Amaro
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from colorium import Color, SepiaFilter, FilterPresets
color = Color(200, 150, 100)
# Single filter
sepia = SepiaFilter(0.7)
result = sepia(color)
# Filter presets
clarendon = FilterPresets.clarendon()
result = clarendon(color)
# Chain filters
from colorium import CompositeFilter, BrightnessFilter, ContrastFilter
vintage = CompositeFilter([
SepiaFilter(0.5),
ContrastFilter(1.1),
BrightnessFilter(0.9)
])
result = vintage(color)Color Blending
Advanced color blending with customizable ratios.
Blend Methods
- Linear Blend — Standard blend with ratio
- Multi-Color Blend — Blend multiple colors
- Gradient Generation — Create smooth gradients
Example
1
2
3
4
5
6
7
8
9
10
11
12
from colorium import Color, RED, BLUE
# Simple blend
purple = RED.blend(BLUE, 0.5)
# Custom ratios
pink = RED.blend(WHITE, 0.7)
orange = RED.blend(YELLOW, 0.4)
# Create gradient
def create_gradient(start, end, steps=10):
return [start.blend(end, i/(steps-1)) for i in range(steps)]Color Distance
Calculate perceptual color differences using industry standards.
Distance Methods
| Method | Description |
|---|---|
| CIE76 | Simple Euclidean distance |
| CIE94 | Improved perceptual distance |
| CIEDE2000 | Industry standard (most accurate) |
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
from colorium import Color
color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)
# Calculate distance
cie76 = color1.delta_e(color2, "cie76")
cie94 = color1.delta_e(color2, "cie94")
cie2000 = color1.delta_e(color2, "cie2000")
print(f"CIE76: {cie76:.2f}")
print(f"CIE94: {cie94:.2f}")
print(f"CIE2000: {cie2000:.2f}")Color Similarity
Determine how similar two colors are based on human perception.
Features
- Similarity scoring from 0.0 to 1.0
- Customizable threshold
- Multiple distance algorithms
- Human-perception-based mapping
Example
1
2
3
4
5
6
7
8
9
10
11
12
from colorium import Color
color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)
# Calculate similarity
similarity = color1.similarity(color2)
print(f"Similarity: {similarity:.2f}")
# Check if similar
if color1.is_similar_to(color2, threshold=0.8):
print("Colors are very similar")Named Colors
Access all 147 CSS named colors with case-insensitive lookup.
Features
- All CSS Color Level 4 named colors
- Case-insensitive lookup
- Automatic color name detection
- 147 colors available
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from colorium import from_string
# Use named colors
red = from_string("red")
blue = from_string("blue")
crimson = from_string("crimson")
# Case insensitive
RED = from_string("RED")
ReD = from_string("ReD")
# Get color name
color = Color(255, 0, 0)
name = color.to_name() # "Red"Color Constants
Pre-defined color constants for common colors.
Categories
| Category | Examples |
|---|---|
| Basic Colors | RED, BLUE, GREEN, WHITE, BLACK |
| Extended Colors | CRIMSON, NAVY, OLIVE, TEAL |
| Semantic Colors | SUCCESS, ERROR, WARNING, INFO |
| Brand Colors | FACEBOOK_BLUE, TWITTER_BLUE, GOOGLE_RED |
Example
1
2
3
4
5
6
7
8
from colorium import RED, BLUE, SUCCESS, ERROR
# Use constants directly
primary = BLUE
status = SUCCESS if valid else ERROR
# Blend constants
purple = RED.blend(BLUE, 0.5)Color Conversion
Seamless conversion between all supported formats.
Supported Formats
- RGB strings
- Hex strings
- HSL strings
- HWB strings
- CMYK strings
- OKLCH strings
- LAB strings
- LCH strings
- P3 strings
- Named colors
Example
1
2
3
4
5
6
7
8
9
10
11
from colorium import from_string, from_hex, from_hsl
# From various formats
color1 = from_string("red")
color2 = from_hex("#FF0000")
color3 = from_hsl(0, 1.0, 0.5)
# To various formats
print(color1.to_rgb_string())
print(color1.to_hex_string())
print(color1.to_hsl_string())Color Manipulation
Complete toolkit for color manipulation.
Operations
| Operation | Description |
|---|---|
| Lighten | Increase lightness |
| Darken | Decrease lightness |
| Saturate | Increase saturation |
| Desaturate | Decrease saturation |
| Hue Rotate | Shift hue angle |
| Blend | Blend with another color |
| Clone | Create independent copy |
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
from colorium import Color
color = Color(100, 150, 200)
# Manipulate
color.lighter(0.2)
color.darker(0.1)
color.saturate(0.3)
color.desaturate(0.2)
# Clone
copy = color.clone()
copy.lighter(0.5)Modern Color Support
CSS Color Level 4 support for modern color standards.
Features
- OKLCH perceptually uniform color space
- CIE Lab* color space
- CIE LCH color space
- Display P3 wide gamut support
- Modern CSS color strings
Example
1
2
3
4
5
6
7
from colorium import from_oklch, from_lab, from_lch, from_p3
# Modern color spaces
oklch_color = from_oklch(0.5, 0.2, 180)
lab_color = from_lab(50, 20, -30)
lch_color = from_lch(50, 30, 180)
p3_color = from_p3(0.8, 0.3, 0.5)Zero Dependencies
Colorium is pure Python with no external dependencies.
Why Zero Dependencies
- Instant installation
- No version conflicts
- Portable and lightweight
- Easy to distribute
- Minimal footprint
Example
1
2
3
4
5
# Install Colorium
pip install colorium
# No other packages needed
# Ready to use immediatelyType Safety
Full Python type hints for better IDE support.
Features
- Complete type annotations
- IDE autocompletion
- Static type checking with mypy
- Better documentation
Example
1
2
3
4
5
6
7
8
9
10
from colorium import Color
def process_color(color: Color) -> Color:
"""Process a color and return a new color."""
result = color.clone()
result.lighter(0.2)
return result
# Type hints help IDEs
result = process_color(Color(255, 0, 0))Next Steps
- Color Filters — Detailed filter guide
- Color Blending — Advanced blending
- Color Distance — Color difference calculations
Previous: Core Concepts Next: Color Filters →
On this page
39 sections