Color Class API

The Color class is the core of Colorium. This document provides complete API reference for all methods and properties.

Constructor

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

Creates a new Color instance with RGB values.

Parameters:

ParameterTypeRangeDescription
redint0-255Red component
greenint0-255Green component
blueint0-255Blue component
opacityfloat0-1Opacity (default: 1.0)

Example:

1
2
3
4
from colorium import Color

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

Properties

RGB Properties

1
2
3
4
color.red: int
color.green: int
color.blue: int
color.opacity: float

Get or set RGB components.

PropertyTypeRangeDescription
redint0-255Red component
greenint0-255Green component
blueint0-255Blue component
opacityfloat0-1Opacity

Example:

1
2
3
4
5
6
7
from colorium import Color

color = Color(100, 150, 200)
color.red = 255
color.green = 0
color.blue = 0
print(color.opacity)  # 1.0

HSL Properties

1
2
3
color.hue: float
color.sat: float
color.lightness: float

Get derived HSL values (read-only).

PropertyTypeRangeDescription
huefloat0-360Hue angle
satfloat0-1Saturation
lightnessfloat0-1Lightness

Example:

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

1
2
color.whiteness: float
color.blackness: float

Get derived HWB values (read-only).

PropertyTypeRangeDescription
whitenessfloat0-1Whiteness
blacknessfloat0-1Blackness

Example:

1
2
3
4
5
from colorium import Color

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

CMYK Properties

1
2
3
4
color.cyan: float
color.magenta: float
color.yellow: float
color.black: float

Get derived CMYK values (read-only).

PropertyTypeRangeDescription
cyanfloat0-1Cyan
magentafloat0-1Magenta
yellowfloat0-1Yellow
blackfloat0-1Black

Example:

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

NCOL Property

1
color.ncol: str

Get NCOL notation string (read-only).

Example:

1
2
3
4
5
6
7
from colorium import Color

color = Color(255, 0, 0)
print(color.ncol)  # R0

color = Color(0, 255, 0)
print(color.ncol)  # G0

String Methods

to_rgb_string

1
def to_rgb_string(self) -> str

Convert to CSS RGB string format.

Returns: rgb(255, 0, 0)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_rgb_string())  # rgb(255, 0, 0)

to_rgba_string

1
def to_rgba_string(self) -> str

Convert to CSS RGBA string format with opacity.

Returns: rgba(255, 0, 0, 1.00)

Example:

1
2
color = Color(255, 0, 0, 0.5)
print(color.to_rgba_string())  # rgba(255, 0, 0, 0.50)

to_hsl_string

1
def to_hsl_string(self) -> str

Convert to CSS HSL string format.

Returns: hsl(0, 100%, 50%)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_hsl_string())  # hsl(0, 100%, 50%)

to_hsla_string

1
def to_hsla_string(self) -> str

Convert to CSS HSLA string format with opacity.

Returns: hsla(0, 100%, 50%, 1.00)

Example:

1
2
color = Color(255, 0, 0, 0.5)
print(color.to_hsla_string())  # hsla(0, 100%, 50%, 0.50)

to_hwb_string

1
def to_hwb_string(self) -> str

Convert to CSS HWB string format.

Returns: hwb(0, 0%, 0%)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_hwb_string())  # hwb(0, 0%, 0%)

to_hwba_string

1
def to_hwba_string(self) -> str

Convert to CSS HWBA string format with opacity.

Returns: hwba(0, 0%, 0%, 1.00)

Example:

1
2
color = Color(255, 0, 0, 0.5)
print(color.to_hwba_string())  # hwba(0, 0%, 0%, 0.50)

to_cmyk_string

1
def to_cmyk_string(self) -> str

Convert to CMYK string format.

Returns: cmyk(0%, 100%, 100%, 0%)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_cmyk_string())  # cmyk(0%, 100%, 100%, 0%)

to_hex_string

1
def to_hex_string(self) -> str

Convert to hexadecimal color string.

Returns: #FF0000

Example:

1
2
color = Color(255, 0, 0)
print(color.to_hex_string())  # #FF0000

to_oklch_string

1
def to_oklch_string(self) -> str

Convert to OKLCH string format (CSS Color Level 4).

Returns: oklch(62.8% 0.258 29.2)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_oklch_string())  # oklch(62.8% 0.258 29.2)

to_lab_string

1
def to_lab_string(self) -> str

Convert to CIE Lab* string format (CSS Color Level 4).

Returns: lab(53.2% 80.1 67.2)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_lab_string())  # lab(53.2% 80.1 67.2)

to_lch_string

1
def to_lch_string(self) -> str

Convert to CIE LCH string format (CSS Color Level 4).

Returns: lch(53.2% 104.5 40.0)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_lch_string())  # lch(53.2% 104.5 40.0)

to_p3_string

1
def to_p3_string(self) -> str

Convert to Display P3 string format.

Returns: color(display-p3 0.823 0.033 0.017)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_p3_string())  # color(display-p3 0.823 0.033 0.017)

to_ncol_string

1
def to_ncol_string(self) -> str

Convert to NCOL notation string.

Returns: ncol(R0, 0%, 0%)

Example:

1
2
color = Color(255, 0, 0)
print(color.to_ncol_string())  # ncol(R0, 0%, 0%)

to_name

1
def to_name(self) -> str

Get CSS color name if this color matches a named color.

Returns: Color name or empty string

Example:

1
2
3
4
5
color = Color(255, 0, 0)
print(color.to_name())  # Red

color = Color(123, 45, 67)
print(color.to_name())  # ""

Dictionary Methods

to_rgb

1
def to_rgb(self) -> Dict[str, Any]

Get RGB values as a dictionary.

Returns:

1
2
3
4
5
6
{
    'r': 255,
    'g': 0,
    'b': 0,
    'a': 1.0
}

Example:

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

to_hsl

1
def to_hsl(self) -> Dict[str, float]

Get HSL values as a dictionary.

Returns:

1
2
3
4
5
6
{
    'h': 0,
    's': 1.0,
    'l': 0.5,
    'a': 1.0
}

Example:

1
2
3
4
5
6
color = Color(255, 0, 0)
hsl = color.to_hsl()
print(hsl['h'])  # 0
print(hsl['s'])  # 1.0
print(hsl['l'])  # 0.5
print(hsl['a'])  # 1.0

to_hwb

1
def to_hwb(self) -> Dict[str, float]

Get HWB values as a dictionary.

Returns:

1
2
3
4
5
6
{
    'h': 0,
    'w': 0.0,
    'b': 0.0,
    'a': 1.0
}

Example:

1
2
3
4
5
6
color = Color(255, 0, 0)
hwb = color.to_hwb()
print(hwb['h'])  # 0
print(hwb['w'])  # 0.0
print(hwb['b'])  # 0.0
print(hwb['a'])  # 1.0

to_cmyk

1
def to_cmyk(self) -> Dict[str, float]

Get CMYK values as a dictionary.

Returns:

1
2
3
4
5
6
7
{
    'c': 0.0,
    'm': 1.0,
    'y': 1.0,
    'k': 0.0,
    'a': 1.0
}

Example:

1
2
3
4
5
6
7
color = Color(255, 0, 0)
cmyk = color.to_cmyk()
print(cmyk['c'])  # 0.0
print(cmyk['m'])  # 1.0
print(cmyk['y'])  # 1.0
print(cmyk['k'])  # 0.0
print(cmyk['a'])  # 1.0

to_oklch

1
def to_oklch(self) -> Dict[str, float]

Get OKLCH values as a dictionary.

Returns:

1
2
3
4
5
{
    'l': 0.628,
    'c': 0.258,
    'h': 29.2
}

Example:

1
2
3
4
5
color = Color(255, 0, 0)
oklch = color.to_oklch()
print(oklch['l'])  # 0.628
print(oklch['c'])  # 0.258
print(oklch['h'])  # 29.2

to_lab

1
def to_lab(self) -> Dict[str, float]

Get CIE Lab* values as a dictionary.

Returns:

1
2
3
4
5
{
    'l': 53.24,
    'a': 80.09,
    'b': 67.20
}

Example:

1
2
3
4
5
color = Color(255, 0, 0)
lab = color.to_lab()
print(lab['l'])  # 53.24
print(lab['a'])  # 80.09
print(lab['b'])  # 67.20

to_lch

1
def to_lch(self) -> Dict[str, float]

Get CIE LCH values as a dictionary.

Returns:

1
2
3
4
5
{
    'l': 53.24,
    'c': 104.55,
    'h': 40.0
}

Example:

1
2
3
4
5
color = Color(255, 0, 0)
lch = color.to_lch()
print(lch['l'])  # 53.24
print(lch['c'])  # 104.55
print(lch['h'])  # 40.0

to_p3

1
def to_p3(self) -> Dict[str, float]

Get Display P3 values as a dictionary.

Returns:

1
2
3
4
5
{
    'r': 0.8226,
    'g': 0.0331,
    'b': 0.0171
}

Example:

1
2
3
4
5
color = Color(255, 0, 0)
p3 = color.to_p3()
print(p3['r'])  # 0.8226
print(p3['g'])  # 0.0331
print(p3['b'])  # 0.0171

to_ncol

1
def to_ncol(self) -> Dict[str, Any]

Get NCOL values as a dictionary.

Returns:

1
2
3
4
5
6
{
    'ncol': 'R0',
    'w': 0.0,
    'b': 0.0,
    'a': 1.0
}

Example:

1
2
3
4
5
6
color = Color(255, 0, 0)
ncol = color.to_ncol()
print(ncol['ncol'])  # R0
print(ncol['w'])     # 0.0
print(ncol['b'])     # 0.0
print(ncol['a'])     # 1.0

Manipulation Methods

lighter

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

Increase lightness by a given amount.

ParameterTypeRangeDescription
amountfloat0-1Amount to increase (default: 0.1)

Example:

1
2
3
color = Color(100, 150, 200)
color.lighter(0.2)
print(color.to_hex_string())  # Brighter version

darker

1
def darker(self, amount: float = 0.1) -> None

Decrease lightness by a given amount.

ParameterTypeRangeDescription
amountfloat0-1Amount to decrease (default: 0.1)

Example:

1
2
3
color = Color(100, 150, 200)
color.darker(0.2)
print(color.to_hex_string())  # Darker version

saturate

1
def saturate(self, amount: float = 0.1) -> None

Increase saturation by a given amount.

ParameterTypeRangeDescription
amountfloat0-1Amount to increase (default: 0.1)

Example:

1
2
3
color = Color(100, 150, 200)
color.saturate(0.3)
print(color.to_hex_string())  # More vivid

desaturate

1
def desaturate(self, amount: float = 0.1) -> None

Decrease saturation by a given amount.

ParameterTypeRangeDescription
amountfloat0-1Amount to decrease (default: 0.1)

Example:

1
2
3
color = Color(100, 150, 200)
color.desaturate(0.3)
print(color.to_hex_string())  # More muted

blend

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

Blend this color with another color.

ParameterTypeRangeDescription
otherColor-Other color to blend with
ratiofloat0-1Blend ratio (default: 0.5)

Returns: New Color object

Example:

1
2
3
4
color1 = Color(255, 0, 0)
color2 = Color(0, 0, 255)
result = color1.blend(color2, 0.5)
print(result.to_hex_string())  # #7F007F

clone

1
def clone(self) -> 'Color'

Create an independent copy of this color.

Returns: New Color object

Example:

1
2
3
4
5
original = Color(255, 0, 0)
copy = original.clone()
copy.lighter(0.5)
print(original.to_hex_string())  # #FF0000
print(copy.to_hex_string())      # Brighter version

is_dark

1
def is_dark(self, threshold: int = 128) -> bool

Check if color is dark based on perceived luminance.

ParameterTypeRangeDescription
thresholdint0-255Luminance threshold (default: 128)

Returns: True if dark, False otherwise

Example:

1
2
3
4
5
color = Color(0, 0, 0)
print(color.is_dark())  # True

color = Color(255, 255, 255)
print(color.is_dark())  # False

Distance Methods

delta_e

1
def delta_e(self, other: 'Color', method: str = "cie2000") -> float

Calculate color difference (Delta E) between two colors.

ParameterTypeDescription
otherColorOther color to compare
methodstrDistance algorithm (default: "cie2000")

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

Returns: Delta E value

Example:

1
2
3
4
5
6
color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)

cie76 = color1.delta_e(color2, "cie76")
cie94 = color1.delta_e(color2, "cie94")
cie2000 = color1.delta_e(color2, "cie2000")

similarity

1
def similarity(self, other: 'Color', method: str = "cie2000") -> float

Calculate perceptual similarity between two colors.

ParameterTypeDescription
otherColorOther color to compare
methodstrDistance algorithm (default: "cie2000")

Returns: Similarity score (0.0 to 1.0)

Example:

1
2
3
4
5
color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)

similarity = color1.similarity(color2)
print(similarity)  # 0.85

is_similar_to

1
def is_similar_to(self, other: 'Color', threshold: float = 0.8, method: str = "cie2000") -> bool

Check if two colors are similar.

ParameterTypeDescription
otherColorOther color to compare
thresholdfloatSimilarity threshold (default: 0.8)
methodstrDistance algorithm (default: "cie2000")

Returns: True if similar, False otherwise

Example:

1
2
3
4
5
color1 = Color(100, 150, 200)
color2 = Color(120, 130, 180)

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

Magic Methods

str

1
def __str__(self) -> str

Human-readable string representation.

Returns: RGB string like rgb(255, 0, 0)

Example:

1
2
color = Color(255, 0, 0)
print(str(color))  # rgb(255, 0, 0)

repr

1
def __repr__(self) -> str

Developer-friendly representation.

Returns: Constructor string

Example:

1
2
color = Color(255, 0, 0)
print(repr(color))  # Color(255, 0, 0, opacity=1.00)

eq

1
def __eq__(self, other: object) -> bool

Check if two colors are equal.

Returns: True if equal, False otherwise

Example:

1
2
3
4
5
6
color1 = Color(255, 0, 0)
color2 = Color(255, 0, 0)
color3 = Color(0, 255, 0)

print(color1 == color2)  # True
print(color1 == color3)  # False

Next Steps

Previous: API Reference Next: Color Functions →

On this page
49 sections