Quick Start

This guide will help you build your first color application with Colorium in less than 5 minutes.

Your First Color

Create a new Python file called colors_demo.py:

1
2
3
4
5
6
7
8
9
10
from colorium import Color, from_string

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

print(red.to_hex_string())      # #FF0000
print(blue.to_hsl_string())     # hsl(240, 100%, 50%)
print(crimson.to_cmyk_string()) # cmyk(0%, 86%, 72%, 14%)

Interactive Color Playground

Try this interactive example to see Colorium in action:

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, from_string, RED, BLUE

# Create a base color
base = Color(100, 150, 200)
print(f"Base color: {base.to_hex_string()}")

# Manipulate the color
base.lighter(0.3)
print(f"Lighter: {base.to_hex_string()}")

base.darker(0.2)
print(f"Darker: {base.to_hex_string()}")

base.saturate(0.5)
print(f"Saturated: {base.to_hex_string()}")

# Get color name
print(f"Color name: {base.to_name()}")

# Check if dark
print(f"Is dark? {base.is_dark()}")

Expected output:

Base color: #6496C8 Lighter: #7FAAFF Darker: #4A7AC4 Saturated: #3B6FA0 Color name: LightSteelBlue Is dark? False

Color Conversion

Convert between different color spaces with ease:

1
2
3
4
5
6
7
8
9
10
11
from colorium import Color

color = Color(255, 0, 0)

# Convert to different formats
print(color.to_rgb_string())    # rgb(255, 0, 0)
print(color.to_hex_string())    # #FF0000
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)

Working with Named Colors

Colorium includes 147 CSS named colors:

1
2
3
4
5
6
7
8
9
10
11
12
from colorium import from_string

# Use any CSS named color
colors = [
    "red", "blue", "green", "yellow",
    "crimson", "navy", "olive", "teal",
    "coral", "indigo", "lavender", "plum"
]

for name in colors:
    color = from_string(name)
    print(f"{name:12} → {color.to_hex_string()}")

Color Blending

Create new colors by blending existing ones:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from colorium import RED, BLUE, GREEN, WHITE

# Basic blend
purple = RED.blend(BLUE, 0.5)
print(f"50% Red + 50% Blue = {purple.to_hex_string()}")

# Different ratios
pink = RED.blend(WHITE, 0.7)
print(f"30% Red + 70% White = {pink.to_hex_string()}")

yellow_green = GREEN.blend(YELLOW, 0.4)
print(f"60% Green + 40% Yellow = {yellow_green.to_hex_string()}")

# Custom blending with any colors
color1 = Color(255, 100, 50)
color2 = Color(50, 100, 255)
result = color1.blend(color2, 0.3)

Color Filters

Apply professional filters to your colors:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
from colorium import Color, SepiaFilter, GrayscaleFilter, FilterPresets

color = Color(200, 150, 100)

# Sepia effect
sepia = SepiaFilter(0.7)
sepia_result = sepia(color)
print(f"Sepia: {sepia_result.to_hex_string()}")

# Grayscale
gray = GrayscaleFilter("luminance")
gray_result = gray(color)
print(f"Grayscale: {gray_result.to_hex_string()}")

# Use presets
clarendon = FilterPresets.clarendon()
clarendon_result = clarendon(color)
print(f"Clarendon: {clarendon_result.to_hex_string()}")

# Chain filters together
from colorium import CompositeFilter, BrightnessFilter, ContrastFilter

vintage = CompositeFilter([
    SepiaFilter(0.5),
    ContrastFilter(1.1),
    BrightnessFilter(0.9)
])
vintage_result = vintage(color)

Color Distance and Similarity

Compare colors using perceptual algorithms:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from colorium import Color

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

# Calculate Delta E (color difference)
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}")

# Calculate similarity (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!")
else:
    print("Colors are quite different")

Modern Color Spaces

Work with CSS Color Level 4 color spaces:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from colorium import from_oklch, from_lab, from_lch

# OKLCH - Perceptually uniform
oklch_color = from_oklch(0.5, 0.2, 180)
print(f"OKLCH: {oklch_color.to_hex_string()}")

# CIE L*a*b*
lab_color = from_lab(50, 20, -30)
print(f"LAB: {lab_color.to_hex_string()}")

# CIE LCH
lch_color = from_lch(50, 30, 180)
print(f"LCH: {lch_color.to_hex_string()}")

# Display P3 Wide Gamut
from colorium import from_p3
p3_color = from_p3(0.8, 0.3, 0.5)
print(f"Display P3: {p3_color.to_p3_string()}")

Complete Example: Color Palette Generator

Here's a complete working example that generates a color palette:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from colorium import Color, from_string, RED, BLUE

def generate_palette(base_color, count=5):
    """Generate a monochromatic color palette"""
    palette = []
    for i in range(count):
        lightness = 0.2 + (i / (count - 1)) * 0.6
        color = base_color.clone()
        color.lightness = lightness
        palette.append(color)
    return palette

# Create a base color
base = RED

# Generate palette
palette = generate_palette(base, 5)

# Display the palette
for i, color in enumerate(palette):
    hex_str = color.to_hex_string()
    hsl = color.to_hsl()
    print(f"Shade {i+1}: {hex_str} | Lightness: {hsl['l']:.0%}")

Expected output:

Shade 1: #660000 | Lightness: 20% Shade 2: #B30000 | Lightness: 35% Shade 3: #FF0000 | Lightness: 50% Shade 4: #FF6666 | Lightness: 65% Shade 5: #FFB3B3 | Lightness: 80%

Next Steps

Now that you've seen Colorium in action, explore more:

Previous: Installation Next: Usage Examples →

On this page
10 sections