Color Manipulation

Colorium provides a comprehensive set of methods for manipulating colors. This guide covers all operations you can perform on colors.

Basic Manipulation

Lightness Adjustment

Control the perceived brightness of a color.

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

color = Color(100, 150, 200)

# Make lighter
color.lighter(0.2)    # Increase lightness by 20%
print(color.to_hex_string())  # Brighter version

# Make darker
color.darker(0.1)     # Decrease lightness by 10%
print(color.to_hex_string())  # Darker version

# Chaining operations
color.lighter(0.3).darker(0.1)

Saturation Adjustment

Control the intensity or purity of a color.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from colorium import Color

color = Color(100, 150, 200)

# Increase saturation
color.saturate(0.3)   # More vivid
print(color.to_hex_string())

# Decrease saturation
color.desaturate(0.2) # More muted
print(color.to_hex_string())

# Full desaturation (grayscale)
color.desaturate(1.0)
print(color.to_hsl()['s'])  # 0.0

Hue Rotation

Shift colors around the color wheel.

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

color = Color(255, 0, 0)  # Red

# Rotate hue directly
color.hue = 180           # Becomes cyan
print(color.to_hex_string())  # #00FFFF

# Access hue value
print(color.hue)          # 180.0

Combined Operations

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

color = Color(100, 150, 200)

# Create a variant
variant = color.clone()
variant.lighter(0.2)
variant.saturate(0.3)
variant.hue = 200

print(f"Original: {color.to_hex_string()}")
print(f"Variant: {variant.to_hex_string()}")

Color Blending

Simple Blend

Blend two colors with a ratio.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from colorium import Color, RED, BLUE

# Equal blend (50/50)
purple = RED.blend(BLUE, 0.5)
print(purple.to_hex_string())  # #7F007F

# Different ratios
pink = RED.blend(WHITE, 0.7)   # 70% white
orange = RED.blend(YELLOW, 0.4) # 40% yellow

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

Multiple Color Blend

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

def multi_blend(colors, ratios):
    """Blend multiple colors with ratios"""
    if len(colors) != len(ratios):
        raise ValueError("Number of colors must match ratios")

    total_r = total_g = total_b = 0
    total_ratio = sum(ratios)

    for color, ratio in zip(colors, ratios):
        weight = ratio / total_ratio
        total_r += color.red * weight
        total_g += color.green * weight
        total_b += color.blue * weight

    return Color(int(total_r), int(total_g), int(total_b))

# Blend three colors
colors = [Color(255, 0, 0), Color(0, 255, 0), Color(0, 0, 255)]
ratios = [0.4, 0.3, 0.3]
result = multi_blend(colors, ratios)

Color Cloning

Create independent copies of colors.

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

original = Color(255, 0, 0)

# Clone the color
clone = original.clone()

# Modify clone independently
clone.lighter(0.3)

print(f"Original: {original.to_hex_string()}")  # #FF0000
print(f"Clone: {clone.to_hex_string()}")        # Brighter version

Color Inspection

Dark/Light Detection

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

color = Color(100, 150, 200)

# Check if dark (default threshold 128)
if color.is_dark():
    print("Dark color")
else:
    print("Light color")

# Custom threshold
if color.is_dark(threshold=150):
    print("Very dark color")

Color Name Detection

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

color = Color(255, 0, 0)
name = color.to_name()
print(name)  # Red

color2 = Color(100, 149, 237)
print(color2.to_name())  # CornflowerBlue

# Unknown colors return empty string
color3 = Color(123, 45, 67)
print(color3.to_name())  # ""

Color Value Extraction

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from colorium import Color

color = Color(100, 150, 200)

# Get RGB values
rgb = color.to_rgb()
print(f"R: {rgb['r']}, G: {rgb['g']}, B: {rgb['b']}")

# Get HSL values
hsl = color.to_hsl()
print(f"H: {hsl['h']}, S: {hsl['s']}, L: {hsl['l']}")

# Get CMYK values
cmyk = color.to_cmyk()
print(f"C: {cmyk['c']}, M: {cmyk['m']}, Y: {cmyk['y']}, K: {cmyk['k']}")

Color Properties

Working with Individual Components

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

color = Color(100, 150, 200)

# Modify RGB components
color.red = 255
color.green = 0
color.blue = 0

# Modify HSL components
color.hue = 180
color.sat = 0.8
color.lightness = 0.5

# Access all properties
print(f"RGB: ({color.red}, {color.green}, {color.blue})")
print(f"HSL: ({color.hue}, {color.sat}, {color.lightness})")
print(f"HWB: ({color.whiteness}, {color.blackness})")
print(f"CMYK: ({color.cyan}, {color.magenta}, {color.yellow}, {color.black})")

Component Range Validation

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

# Values are automatically clamped
color = Color(300, -10, 100)
print(color.red)   # 255
print(color.green) # 0

# Opacity is clamped to 0-1
color.opacity = 2.5
print(color.opacity)  # 1.0

Advanced Manipulation

Color Inversion

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

def invert_color(color):
    """Invert a color (negative)"""
    return Color(
        255 - color.red,
        255 - color.green,
        255 - color.blue,
        color.opacity
    )

color = Color(255, 0, 0)
inverted = invert_color(color)
print(inverted.to_hex_string())  # #00FFFF

Color Temperature Adjustment

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
from colorium import Color

def adjust_temperature(color, temperature):
    """
    Adjust color temperature
    temperature: -1.0 (cool) to 1.0 (warm)
    """
    result = color.clone()

    if temperature > 0:
        # Warm
        warm = Color(255, 200, 150)
        result = result.blend(warm, temperature)
    else:
        # Cool
        cool = Color(150, 200, 255)
        result = result.blend(cool, -temperature)

    return result

color = Color(200, 200, 200)
warm = adjust_temperature(color, 0.7)
cool = adjust_temperature(color, -0.7)

print(f"Original: {color.to_hex_string()}")
print(f"Warm: {warm.to_hex_string()}")
print(f"Cool: {cool.to_hex_string()}")

Color Contrast

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

def get_contrasting_color(color):
    """Get a contrasting color for text"""
    if color.is_dark():
        return Color(255, 255, 255)  # White
    else:
        return Color(0, 0, 0)        # Black

def get_complementary(color):
    """Get complementary color (180° rotation)"""
    hsl = color.to_hsl()
    from colorium import from_hsl
    return from_hsl((hsl['h'] + 180) % 360, hsl['s'], hsl['l'])

color = Color(100, 150, 200)
contrast = get_contrasting_color(color)
complement = get_complementary(color)

print(f"Original: {color.to_hex_string()}")
print(f"Contrast: {contrast.to_hex_string()}")
print(f"Complement: {complement.to_hex_string()}")

Common Manipulation Patterns

Creating Shades and Tints

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
29
30
31
from colorium import Color

def create_shades(base_color, count=5):
    """Create lighter shades of a color"""
    shades = []
    for i in range(count):
        amount = i / (count - 1)
        shade = base_color.clone()
        shade.lighter(amount * 0.5)
        shades.append(shade)
    return shades

def create_tones(base_color, count=5):
    """Create darker tones of a color"""
    tones = []
    for i in range(count):
        amount = i / (count - 1)
        tone = base_color.clone()
        tone.darker(amount * 0.5)
        tones.append(tone)
    return tones

color = Color(255, 0, 0)

print("Shades:")
for shade in create_shades(color, 5):
    print(f"  {shade.to_hex_string()}")

print("\nTones:")
for tone in create_tones(color, 5):
    print(f"  {tone.to_hex_string()}")

Color Animation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from colorium import Color

def animate_color(start, end, steps, callback):
    """Animate between two colors"""
    for i in range(steps):
        ratio = i / (steps - 1)
        current = start.blend(end, ratio)
        callback(current)

# Usage
def print_color(color):
    print(f"Frame: {color.to_hex_string()}")

start = Color(255, 0, 0)
end = Color(0, 0, 255)
animate_color(start, end, 5, print_color)

Performance Considerations

Clone vs New Color

1
2
3
4
5
6
7
from colorium import Color

# Good for copying
copy = original.clone()

# Also works but less clear
copy = Color(original.red, original.green, original.blue)

Avoiding Unnecessary Operations

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

color = Color(100, 150, 200)

# Good - modify directly
color.lighter(0.3)

# Avoid - creating new object unnecessarily
color = color.clone()
color.lighter(0.3)

Batch Operations

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

def batch_lighten(colors, amount):
    """Lighten multiple colors at once"""
    return [color.clone().lighter(amount) for color in colors]

colors = [Color(100, 150, 200), Color(255, 0, 0), Color(0, 255, 0)]
lightened = batch_lighten(colors, 0.2)

Next Steps

Previous: Color Creation Next: Color Conversion →

On this page
28 sections