API Reference

This section provides complete API documentation for all classes, functions, and methods in Colorium.

Overview

Module	Description
Color	Core Color class
Color Spaces	Space-specific functions
Filters	Filter classes and presets
Utilities	Utility functions
Constants	Named colors and constants

Color Class

Constructor

Color(red: int, green: int, blue: int, opacity: float = 1.0)

Creates a new Color instance.

Parameter	Type	Range	Description
red	int	0-255	Red component
green	int	0-255	Green component
blue	int	0-255	Blue component
opacity	float	0-1	Opacity (default: 1.0)

Example:

from colorium import Color

red = Color(255, 0, 0)
transparent_red = Color(255, 0, 0, 0.5)

Properties

RGB Properties

Property	Type	Description
red	int	Red component (0-255)
green	int	Green component (0-255)
blue	int	Blue component (0-255)
opacity	float	Opacity (0-1)

Example:

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

color.red = 255
color.green = 0
color.blue = 0

HSL Properties

Property	Type	Description
hue	float	Hue angle (0-360)
sat	float	Saturation (0-1)
lightness	float	Lightness (0-1)

Example:

from colorium import Color

color = Color(255, 0, 0)
print(color.hue)        # 0
print(color.sat)        # 1.0
print(color.lightness)  # 0.5

HWB Properties

Property	Type	Description
whiteness	float	Whiteness (0-1)
blackness	float	Blackness (0-1)

Example:

from colorium import Color

color = Color(255, 0, 0)
print(color.whiteness)  # 0.0
print(color.blackness)  # 0.0

CMYK Properties

Property	Type	Description
cyan	float	Cyan (0-1)
magenta	float	Magenta (0-1)
yellow	float	Yellow (0-1)
black	float	Black (0-1)

Example:

from colorium import Color

color = Color(255, 0, 0)
print(color.cyan)     # 0.0
print(color.magenta)  # 1.0
print(color.yellow)   # 1.0
print(color.black)    # 0.0

String Methods

Method	Returns	Example
`to_rgb_string()`	str	`rgb(255, 0, 0)`
`to_rgba_string()`	str	`rgba(255, 0, 0, 1.00)`
`to_hsl_string()`	str	`hsl(0, 100%, 50%)`
`to_hsla_string()`	str	`hsla(0, 100%, 50%, 1.00)`
`to_hwb_string()`	str	`hwb(0, 0%, 0%)`
`to_hwba_string()`	str	`hwba(0, 0%, 0%, 1.00)`
`to_cmyk_string()`	str	`cmyk(0%, 100%, 100%, 0%)`
`to_hex_string()`	str	`#FF0000`
`to_oklch_string()`	str	`oklch(62.8% 0.258 29.2)`
`to_lab_string()`	str	`lab(53.2% 80.1 67.2)`
`to_lch_string()`	str	`lch(53.2% 104.5 40.0)`
`to_p3_string()`	str	`color(display-p3 0.823 0.033 0.017)`
`to_ncol_string()`	str	`ncol(R0, 0%, 0%)`
`to_name()`	str	`Red`

Example:

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_name())          # Red

Dictionary Methods

Method	Returns	Keys
`to_rgb()`	Dict	r, g, b, a
`to_hsl()`	Dict	h, s, l, a
`to_hwb()`	Dict	h, w, b, a
`to_cmyk()`	Dict	c, m, y, k, a
`to_oklch()`	Dict	l, c, h
`to_lab()`	Dict	l, a, b
`to_lch()`	Dict	l, c, h
`to_p3()`	Dict	r, g, b
`to_ncol()`	Dict	ncol, w, b, a

Example:

from colorium import Color

color = Color(255, 0, 0)
rgb = color.to_rgb()
print(rgb['r'])  # 255
print(rgb['g'])  # 0
print(rgb['b'])  # 0
print(rgb['a'])  # 1.0

Manipulation Methods

Method	Description
`lighter(amount)`	Increase lightness
`darker(amount)`	Decrease lightness
`saturate(amount)`	Increase saturation
`desaturate(amount)`	Decrease saturation
`blend(other, ratio)`	Blend with another color
`clone()`	Create a copy
`is_dark(threshold)`	Check if color is dark

Example:

from colorium import Color

color = Color(100, 150, 200)

# Manipulate
color.lighter(0.2)
color.darker(0.1)
color.saturate(0.3)

# Clone
copy = color.clone()

# Check
print(color.is_dark())  # False

# Blend
other = Color(255, 0, 0)
blended = color.blend(other, 0.5)

Distance Methods

Method	Description
`delta_e(other, method)`	Calculate Delta E
`similarity(other, method)`	Calculate similarity
`is_similar_to(other, threshold, method)`	Check similarity

Methods: "cie76", "cie94", "cie2000"

Example:

from colorium import Color

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

distance = color1.delta_e(color2, "cie2000")
similarity = color1.similarity(color2)

if color1.is_similar_to(color2, threshold=0.8):
    print("Similar")

Factory Functions

From Strings

Function	Description
`from_string(color_str)`	Parse any color string
`from_hex(hex_str)`	Create from hex string

Supported formats: named colors, hex, RGB, HSL, HWB, CMYK, NCOL

Example:

from colorium import from_string, from_hex

red = from_string("red")
hex_color = from_hex("#FF0000")
hsl_color = from_string("hsl(0, 100%, 50%)")

From Color Spaces

Function	Description
`from_rgb(r, g, b, opacity)`	Create from RGB
`from_hsl(h, s, l, opacity)`	Create from HSL
`from_hwb(h, w, b, opacity)`	Create from HWB
`from_cmyk(c, m, y, k, opacity)`	Create from CMYK
`from_oklch(l, c, h, opacity)`	Create from OKLCH
`from_lab(l, a, b, opacity)`	Create from LAB
`from_lch(l, c, h, opacity)`	Create from LCH
`from_p3(r, g, b, opacity)`	Create from Display P3

Example:

from colorium import from_hsl, from_cmyk

hsl_color = from_hsl(200, 0.8, 0.5)
cmyk_color = from_cmyk(0, 1.0, 1.0, 0)

Color Filters

Filter Classes

Filter	Constructor	Description
`SepiaFilter`	`intensity=1.0`	Sepia effect
`GrayscaleFilter`	`method="luminance"`	Grayscale conversion
`InvertFilter`	None	Negative effect
`ContrastFilter`	`amount=1.2`	Contrast adjustment
`BrightnessFilter`	`amount=1.2`	Brightness adjustment
`SaturationFilter`	`amount=0.5`	Saturation adjustment
`HueRotateFilter`	`degrees=90`	Hue rotation
`PosterizeFilter`	`levels=4`	Posterize effect
`TemperatureFilter`	`kelvin=5500`	Temperature adjustment
`VignetteFilter`	`intensity=0.5`	Vignette effect

Example:

from colorium import SepiaFilter, InvertFilter, FilterPresets

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

# Preset
clarendon = FilterPresets.clarendon()
result = clarendon(color)

Filter Presets

Method	Description
`FilterPresets.clarendon()`	Vibrant punchy look
`FilterPresets.gingham()`	Warm soft vintage
`FilterPresets.moon()`	High-contrast black and white
`FilterPresets.lark()`	Cool vibrant modern
`FilterPresets.toaster()`	Warm retro vintage
`FilterPresets.valencia()`	Warm soft vintage
`FilterPresets.amaro()`	Rich warm slightly dark

Composite Filter

Method	Description
`CompositeFilter(filters, name)`	Chain multiple filters
`add_filter(filter)`	Add filter to chain

Example:

from colorium import CompositeFilter, SepiaFilter, ContrastFilter

vintage = CompositeFilter([
    SepiaFilter(0.5),
    ContrastFilter(1.1)
])
result = vintage(color)

Utility Functions

Function	Description
`is_hex(char)`	Check if character is valid hex
`clamp(value, min, max)`	Clamp value to range
`to_hex(value)`	Convert to hex string
`parse_percentage(value)`	Parse percentage string
`trim_string(value)`	Trim whitespace

Example:

from colorium.utils import clamp, to_hex

clamped = clamp(1.5, 0, 1)  # 1.0
hex_str = to_hex(255)       # FF

Constants

Color Constants

Constant	Value
`RED`	`Color(255, 0, 0)`
`GREEN`	`Color(0, 255, 0)`
`BLUE`	`Color(0, 0, 255)`
`WHITE`	`Color(255, 255, 255)`
`BLACK`	`Color(0, 0, 0)`
`GRAY`	`Color(128, 128, 128)`

Named Colors

List	Description
`COLOR_NAMES`	List of all 147 CSS named colors
`COLOR_HEXES`	Corresponding hex values
`NAMED_COLORS`	Case-insensitive mapping

Example:

from colorium import COLOR_NAMES, NAMED_COLORS

print(COLOR_NAMES[0])        # AliceBlue
print(NAMED_COLORS['red'])   # ff0000

Exceptions

Exception	Description
`ValueError`	Invalid color values
`TypeError`	Invalid color types
`AttributeError`	Invalid attribute access

Type Hints

All functions have complete type hints for better IDE support:

def lighter(self, amount: float = 0.1) -> None:
    pass

def blend(self, other: 'Color', ratio: float = 0.5) -> 'Color':
    pass

Next Steps

API Reference — Detailed Color class API
API Reference — All color functions
API Reference — Filter class API

Previous: Contributing Next: Color Class →