Getting Started with Colorium

Welcome to the getting started guide for Colorium. This section will help you set up Colorium and start working with colors in your Python projects.

What You'll Learn

  • How to install Colorium
  • How to create your first colors
  • Basic color operations
  • Where to go next

Prerequisites

Before you begin, make sure you have:

  • Python 3.8 or higher installed
  • A code editor or IDE
  • Basic knowledge of Python

Installation

Colorium is available on PyPI and can be installed with pip:

1
pip install colorium

For development with all optional tools:

1
pip install "colorium[dev]"

Your First Color

Creating colors with Colorium is simple and intuitive:

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, from_hex

# Create from RGB values
red = Color(255, 0, 0)
green = Color(0, 255, 0)
blue = Color(0, 0, 255)

# Create from hex strings
hex_color = from_hex("#FF0000")

# Create from named colors
crimson = from_string("crimson")
navy = from_string("navy")

# Create from HSL values
from colorium import from_hsl
golden = from_hsl(45, 1.0, 0.5)

# Create from modern color spaces
from colorium import from_oklch, from_lab, from_lch
oklch_color = from_oklch(0.5, 0.2, 180)
lab_color = from_lab(53, 80, 67)
lch_color = from_lch(53, 104, 40)

Basic Color Operations

Once you have a color, you can perform various operations:

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

# Create a color
color = Color(100, 150, 200)

# Convert to different formats
print(color.to_hex_string())      # #6496C8
print(color.to_rgb_string())      # rgb(100, 150, 200)
print(color.to_hsl_string())      # hsl(210, 48%, 59%)
print(color.to_cmyk_string())     # cmyk(50%, 25%, 0%, 22%)

# Get color properties
print(color.to_rgb())             # {'r': 100, 'g': 150, 'b': 200}
print(color.to_hsl())             # {'h': 210, 's': 0.48, 'l': 0.59}
print(color.to_name())            # LightSteelBlue

# Check if color is dark
if color.is_dark():
    print("This color is dark")
else:
    print("This color is light")

Color Manipulation

Colorium makes it easy to manipulate colors:

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

color = Color(100, 150, 200)

# Adjust lightness
color.lighter(0.2)   # Make brighter
color.darker(0.1)    # Make darker

# Adjust saturation
color.saturate(0.3)  # Increase saturation
color.desaturate(0.2) # Decrease saturation

# Blend colors
from colorium import RED, BLUE
purple = RED.blend(BLUE, 0.5)
pink = RED.blend(WHITE, 0.7)
orange = RED.blend(YELLOW, 0.4)

# Clone a color
original = Color(255, 0, 0)
copy = original.clone()
copy.lighter(0.5)    # Copy is modified, original stays the same

Using Color Constants

Colorium provides many pre-defined color constants:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from colorium import (
    RED, BLUE, GREEN, WHITE, BLACK,
    SUCCESS, ERROR, WARNING, INFO,
    FACEBOOK_BLUE, TWITTER_BLUE
)

# Use constants directly
bg = WHITE
text = BLACK
primary = BLUE
status = SUCCESS if valid else ERROR

# Blend constants
purple = RED.blend(BLUE, 0.5)

# Use as default arguments
def create_button(text: str, color: Color = PRIMARY):
    return {"text": text, "color": color}

Working with Color Filters

Apply professional-grade 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
from colorium import Color, SepiaFilter, GrayscaleFilter, FilterPresets

color = Color(200, 150, 100)

# Single filter
sepia = SepiaFilter(0.7)
result = sepia(color)

# Grayscale conversion
gray = GrayscaleFilter("luminance")
result = gray(color)

# Use Instagram-style 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 Distance and Similarity

Compare colors using perceptual metrics:

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

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

# Calculate color difference
cie76 = color1.delta_e(color2, "cie76")
cie94 = color1.delta_e(color2, "cie94")
cie2000 = color1.delta_e(color2, "cie2000")

# Calculate similarity (0.0 to 1.0)
similarity = color1.similarity(color2)

# Check if colors are similar
if color1.is_similar_to(color2, threshold=0.8):
    print("Colors are very similar")

Next Steps

Now that you've mastered the basics, explore the rest of the documentation:

Common Use Cases

1. Design System

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

# Create a design system palette
primary = Color(66, 133, 244)      # Google Blue
secondary = Color(234, 67, 53)     # Google Red
success = Color(52, 168, 83)       # Google Green
warning = Color(251, 188, 5)       # Google Yellow

# Generate shades
primary_dark = primary.clone().darker(0.3)
primary_light = primary.clone().lighter(0.3)

2. Data Visualization

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

# Create sequential palette
base = Color(0, 0, 255)
palette = []
for i in range(5):
    shade = base.clone().lighter(i * 0.2)
    palette.append(shade)

3. Theme Generation

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

# Generate complementary theme
primary = RED
secondary = primary.get_complementary()
accent = primary.blend(BLUE, 0.3)

# Generate analogous colors
from colorium import Palette
colors = Palette.analogous(primary, 5)

Troubleshooting

Common Issues

  1. ImportError: Make sure Colorium is installed: pip install colorium
  2. ValueError: Check that values are within valid ranges (RGB: 0-255, HSL: 0-1)
  3. TypeError: Ensure you're passing the correct types to functions

Getting Help

  • Check the API Reference for detailed method signatures
  • Search for similar issues on GitHub
  • Open a discussion for help and questions

Next Steps

Continue your journey with:

Next: Installation →

On this page
18 sections