Core Concepts

This section covers the foundational concepts of Colorium that you need to understand to work effectively with the library.

What is a Color?

In Colorium, a color is represented by the Color class. This class encapsulates all the information about a color and provides methods for manipulating it.

The Color Class

The Color class stores color data internally as RGB values (0-255) and provides automatic conversion to other color spaces on demand.

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

# Create a color
red = Color(255, 0, 0)

# Access RGB components
print(red.red)     # 255
print(red.green)   # 0
print(red.blue)    # 0

# Access derived properties
print(red.hue)          # 0
print(red.sat)          # 1.0
print(red.lightness)    # 0.5

Color Components

Every color has these fundamental components:

ComponentDescriptionRange
RedRed intensity0-255
GreenGreen intensity0-255
BlueBlue intensity0-255
OpacityAlpha/transparency0.0-1.0

Color Spaces

Colorium supports 10+ color spaces, each with its own characteristics and use cases.

RGB (Red, Green, Blue)

The most common color space, used in displays and digital imaging.

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

# RGB values range from 0 to 255
red = Color(255, 0, 0)        # Pure red
green = Color(0, 255, 0)      # Pure green
blue = Color(0, 0, 255)       # Pure blue

# Any color can be represented
color = Color(100, 150, 200)

HSL (Hue, Saturation, Lightness)

A cylindrical color space that's more intuitive for color selection.

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

# HSL values
# hue: 0-360 (color angle)
# saturation: 0-1 (color intensity)
# lightness: 0-1 (brightness)

red = from_hsl(0, 1.0, 0.5)        # Pure red
pastel = from_hsl(200, 0.3, 0.7)   # Pastel blue
dark = from_hsl(120, 0.8, 0.2)     # Dark green

HWB (Hue, Whiteness, Blackness)

An intuitive color space that's easier to understand than HSL.

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

# hwb values
# hue: 0-360
# whiteness: 0-1
# blackness: 0-1

pure = from_hwb(0, 0, 0)           # Pure red
pale = from_hwb(200, 0.5, 0)       # Pale blue
dark = from_hwb(120, 0, 0.5)       # Dark green

CMYK (Cyan, Magenta, Yellow, Black)

The subtractive color model used in printing.

1
2
3
4
5
from colorium import from_cmyk

# CMYK values range from 0 to 1
red = from_cmyk(0, 1.0, 1.0, 0)    # Red in print
black = from_cmyk(0, 0, 0, 1.0)    # Pure black

Modern Color Spaces

Colorium supports CSS Color Level 4 color spaces for modern applications.

OKLCH

A perceptually uniform color space designed for better color interpolation.

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

# OKLCH values
# l: lightness (0-1)
# c: chroma (0-0.4+)
# h: hue (0-360)

color = from_oklch(0.5, 0.2, 180)

CIE Lab*

A color space designed to approximate human vision.

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

# LAB values
# l: lightness (0-100)
# a: green-red axis (-128 to 128)
# b: blue-yellow axis (-128 to 128)

color = from_lab(50, 20, -30)

CIE LCH

A cylindrical representation of LAB.

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

# LCH values
# l: lightness (0-100)
# c: chroma (0-100+)
# h: hue (0-360)

color = from_lch(50, 30, 180)

Display P3

A wide gamut color space for modern displays.

1
2
3
4
from colorium import from_p3

# P3 values range from 0 to 1+
color = from_p3(0.8, 0.3, 0.5)

Creating Colors

There are multiple ways to create colors in Colorium.

From RGB Values

1
2
3
4
from colorium import Color

color = Color(100, 150, 200)
color = Color(255, 0, 0, 0.5)  # With opacity

From Color Spaces

1
2
3
4
5
from colorium import from_hsl, from_hwb, from_cmyk

color1 = from_hsl(200, 0.8, 0.5)
color2 = from_hwb(180, 0.2, 0.1)
color3 = from_cmyk(0.2, 0.8, 0.1, 0.3)

From Strings

1
2
3
4
5
6
from colorium import from_string, from_hex

color1 = from_string("red")          # Named color
color2 = from_string("#FF0000")      # Hex color
color3 = from_string("rgb(255,0,0)") # RGB string
color4 = from_string("hsl(0,100%,50%)") # HSL string

From Constants

1
2
3
4
from colorium import RED, BLUE, GREEN, WHITE, BLACK

primary = RED
secondary = BLUE

Color Properties

Once you have a color, you can access its properties.

RGB Properties

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

color = Color(100, 150, 200)

print(color.red)      # 100
print(color.green)    # 150
print(color.blue)     # 200
print(color.opacity)  # 1.0

# Modify properties
color.red = 255
color.green = 0
color.blue = 0

Derived Properties

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

color = Color(255, 0, 0)

print(color.hue)        # 0
print(color.sat)        # 1.0
print(color.lightness)  # 0.5
print(color.whiteness)  # 0.0
print(color.blackness)  # 0.0
print(color.cyan)       # 0.0
print(color.magenta)    # 1.0
print(color.yellow)     # 1.0
print(color.black)      # 0.0
print(color.ncol)       # R0

Color Conversion

Colorium automatically handles conversion between color spaces.

String Representations

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

color = Color(255, 0, 0)

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)

Dictionary Representations

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

color = Color(255, 0, 0)

rgb = color.to_rgb()      # {'r': 255, 'g': 0, 'b': 0, 'a': 1.0}
hsl = color.to_hsl()      # {'h': 0, 's': 1.0, 'l': 0.5, 'a': 1.0}
hwb = color.to_hwb()      # {'h': 0, 'w': 0.0, 'b': 0.0, 'a': 1.0}
cmyk = color.to_cmyk()    # {'c': 0.0, 'm': 1.0, 'y': 1.0, 'k': 0.0, 'a': 1.0}

Color Operations

Arithmetic Operations

Colors support basic arithmetic operations for convenience.

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

red = Color(255, 0, 0)
blue = Color(0, 0, 255)

# Addition (clamped to 0-255)
purple = red + blue  # Not implemented directly, use blend instead

# Comparison
print(red == Color(255, 0, 0))  # True
print(red != blue)              # True

Color Constants

Colorium provides many pre-defined color constants for convenience.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from colorium import (
    RED, BLUE, GREEN, YELLOW, CYAN, MAGENTA,
    WHITE, BLACK, GRAY,
    SUCCESS, ERROR, WARNING, INFO,
    FACEBOOK_BLUE, TWITTER_BLUE
)

# Use constants directly
primary = RED
secondary = BLUE
status = SUCCESS if valid else ERROR

# Constants are Color objects
print(primary.to_hex_string())  # #FF0000

Best Practices

1. Use Constants When Possible

1
2
3
4
5
6
7
from colorium import RED, BLUE

# Good
color = RED

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

2. Use Factory Functions for Clarity

1
2
3
4
5
6
7
from colorium import from_string, from_hsl

# Good
color = from_string("crimson")

# Also good
color = from_hsl(0, 1.0, 0.5)

3. Clone Colors Before Modifying

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

original = Color(255, 0, 0)

# Good - preserves original
modified = original.clone()
modified.lighter(0.3)

# Avoid - modifies original
original.lighter(0.3)

4. Use Type Hints

1
2
3
4
5
6
7
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

Next Steps

Now that you understand the core concepts, explore:

Previous: Usage Examples Next: Color Spaces →

On this page
33 sections