Core Classes

The core module contains the fundamental classes for color manipulation in chromo-map.

Color Class

class chromo_map.Color(clr, alpha=None)[source]

Bases: object

A class for representing colors.

You can pass in a color as a tuple of RGB or RGBA values in which the values are between 0 and 1, a hex string with or without an alpha value, or an RGB or RGBA string in the form ‘rgb(r, g, b)’ or ‘rgba(r, g, b, a)’. The alpha value is optional in all cases.

You can also pass in another Color object to create a copy of it with an optional new alpha value.

The class has properties that return the color in various formats including tuples, hex strings, RGB strings, and RGBA strings.

You can also interpolate between two colors by passing in another color and a factor between 0 and 1.

Examples

Simple red color:

from chromo_map import Color
Color('red')

Simple red color with alpha:

from chromo_map import Color
Color('red', 0.5)

Green with hex string:

from chromo_map import Color
Color('#007f00')

Blue with RGB string:

from chromo_map import Color
Color('rgb(0, 0, 255)')

Blue with RGBA string and overidden alpha:

from chromo_map import Color
Color('rgba(0, 0, 255, 0.5)', 0.75)
__eq__(other)[source]

Check if two colors are equal.

Only checks the result of the tuple property.

Parameters:

other (Color) – The other color to compare to.

Returns:

Whether the colors are equal.

Return type:

bool

__hash__ = None
__init__(clr, alpha=None)[source]
__or__(other)[source]

Interpolate between two colors assuming a factor of 0.5.

Parameters:

other (Color) – The other color to interpolate with.

Returns:

The interpolated color.

Return type:

Color

Examples

Interpolate between red and blue:

from chromo_map import Color
red = Color('red')
blue = Color('blue')
red | blue
__repr__()[source]

Return a rich colored representation of the color.

Return type:

str

adjust_brightness(factor)[source]

Adjust the brightness (value) of the color by the specified factor.

Parameters:

factor (float) – The factor to multiply the brightness by. Values > 1 increase brightness, values < 1 decrease brightness.

Returns:

A new color with the adjusted brightness.

Return type:

Color

Examples

Increase brightness by 20%:

from chromo_map import Color
red = Color('red')
bright = red.adjust_brightness(1.2)
bright
adjust_hue(degrees)[source]

Adjust the hue of the color by the specified degrees.

Parameters:

degrees (float) – The number of degrees to adjust the hue by.

Returns:

A new color with the adjusted hue.

Return type:

Color

Examples

Adjust hue by 120 degrees:

from chromo_map import Color
red = Color('red')
green = red.adjust_hue(120)
green
adjust_lightness(factor)[source]

Adjust the lightness (HSL) of the color by the specified factor.

Parameters:

factor (float) – The factor to multiply the lightness by. Values > 1 increase lightness, values < 1 decrease lightness.

Returns:

A new color with the adjusted lightness.

Return type:

Color

Examples

Decrease lightness by 20%:

from chromo_map import Color
red = Color('red')
dark = red.adjust_lightness(0.8)
dark
adjust_saturation(factor)[source]

Adjust the saturation of the color by the specified factor.

Parameters:

factor (float) – The factor to multiply the saturation by. Values > 1 increase saturation, values < 1 decrease saturation.

Returns:

A new color with the adjusted saturation.

Return type:

Color

Examples

Increase saturation by 50%:

from chromo_map import Color
red = Color('red')
saturated = red.adjust_saturation(1.5)
saturated
analogous(angle=30)[source]

Get analogous colors (adjacent on the color wheel).

Parameters:

angle (float, default 30) – The angle in degrees for the analogous colors.

Returns:

A tuple of two analogous colors.

Return type:

Tuple[Color, Color]

Examples

Get analogous colors of red:

from chromo_map import Color
red = Color('red')
analog1, analog2 = red.analogous()
print(f"Analogous 1: {analog1.hex}")
print(f"Analogous 2: {analog2.hex}")
Analogous 1: #ff8000
Analogous 2: #ff0080
complementary()[source]

Get the complementary color (opposite on the color wheel).

Returns:

The complementary color.

Return type:

Color

Examples

Get the complement of red:

from chromo_map import Color
red = Color('red')
cyan = red.complementary()
cyan
contrast_ratio(other)[source]

Calculate the contrast ratio between this color and another.

Uses the WCAG 2.1 formula for contrast ratio.

Parameters:

other (Color) – The other color to compare against.

Returns:

The contrast ratio (1:1 to 21:1).

Return type:

float

Examples

Calculate contrast ratio between black and white:

from chromo_map import Color
black = Color('black')
white = Color('white')
black.contrast_ratio(white)
21.0
find_accessible_version(target_color, level='AA', adjust_lightness=True)[source]

Find an accessible version of this color against a target.

Parameters:
  • target_color (Color or str) – The color to ensure accessibility against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

Returns:

An accessible version of this color.

Return type:

Color

Examples

Find accessible version of gray against white:

from chromo_map import Color
gray = Color('#888888')
accessible = gray.find_accessible_version('white')
print(f"Accessible: {accessible.hex}")
Accessible: #595959
property hex

Return the color as a hex string.

Returns:

The color as a hex string.

Return type:

str

Examples

Get the color as a hex string:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.hex
'#ffa500'
property hexa

Return the color as a hex string with an alpha value.

Returns:

The color as a hex string with an alpha value.

Return type:

str

Examples

Get the color as a hex string with an alpha value:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.hexa
'#ffa50080'
property hexatup

Return the color as a tuple of hex values.

Returns:

The color as a tuple of RGBA values between 0 and 255.

Return type:

Tuple[int, int, int, int]

Examples

Get the color as a tuple of hex values:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.hexatup
(255, 165, 0, 127)
property hextup

Return the color as a tuple of hex values.

Returns:

The color as a tuple of RGB values between 0 and 255.

Return type:

Tuple[int, int, int]

Examples

Get the color as a tuple of hex values:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.hextup
(255, 165, 0)
property hsl

Return the color as HSL values.

Returns:

The color as a tuple of HSL values (hue: 0-360, saturation: 0-1, lightness: 0-1).

Return type:

Tuple[float, float, float]

Examples

Get the color as HSL values:

from chromo_map import Color
red = Color('red')
red.hsl
(0.0, 1.0, 0.5)
property hsv

Return the color as HSV values.

Returns:

The color as a tuple of HSV values (hue: 0-360, saturation: 0-1, value: 0-1).

Return type:

Tuple[float, float, float]

Examples

Get the color as HSV values:

from chromo_map import Color
red = Color('red')
red.hsv
(0.0, 1.0, 1.0)
interpolate(other, factor)[source]

Interpolate between two colors.

Parameters:
  • other (Color) – The other color to interpolate with.

  • factor (float) – The interpolation factor between 0 and 1.

Returns:

The interpolated color.

Return type:

Color

Examples

Interpolate between red and blue:

from chromo_map import Color
red = Color('red')
blue = Color('blue')

red.interpolate(blue, 0.5)
is_accessible(other, level='AA')[source]

Check if this color has sufficient contrast with another for accessibility.

Parameters:
  • other (Color) – The other color to compare against.

  • level (str, default 'AA') – The WCAG level to check against (‘AA’ or ‘AAA’).

Returns:

True if the contrast ratio meets the specified level.

Return type:

bool

Examples

Check if black text on white background is accessible:

from chromo_map import Color
black = Color('black')
white = Color('white')
black.is_accessible(white)
True
property luminance

Return the relative luminance of the color.

Uses the WCAG 2.1 formula for relative luminance.

Returns:

The relative luminance value (0-1).

Return type:

float

Examples

Get the luminance of a color:

from chromo_map import Color
white = Color('white')
black = Color('black')
print(f"White luminance: {white.luminance:.3f}")
print(f"Black luminance: {black.luminance:.3f}")
White luminance: 1.000
Black luminance: 0.000

Maximize contrast against target using binary search.

Parameters:
  • target_color (Color or str) – The color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • precision (float, default 0.001) – The precision for binary search convergence.

Returns:

The color with maximized contrast.

Return type:

Color

Examples

Maximize contrast with binary search:

from chromo_map import Color
gray = Color('#888888')
optimized = gray.maximize_contrast_binary_search('white')
print(f"Optimized: {optimized.hex}")
Optimized: #0d0d0d
maximize_contrast_iterative(target_color, level='AA', adjust_lightness=True, step_size=0.1, max_attempts=50)[source]

Maximize contrast against target using iterative approach.

Parameters:
  • target_color (Color or str) – The color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • step_size (float, default 0.1) – The step size for adjustments.

  • max_attempts (int, default 50) – Maximum number of adjustment attempts.

Returns:

The color with maximized contrast.

Return type:

Color

Examples

Maximize contrast iteratively:

from chromo_map import Color
gray = Color('#888888')
optimized = gray.maximize_contrast_iterative('white')
print(f"Optimized: {optimized.hex}")
Optimized: #000000
maximize_contrast_optimization(target_color, level='AA', method='golden_section')[source]

Maximize contrast against target using mathematical optimization.

Parameters:
  • target_color (Color or str) – The color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • method (str, default 'golden_section') – The optimization method to use (‘golden_section’ or ‘gradient_descent’).

Returns:

The color with maximized contrast.

Return type:

Color

Examples

Maximize contrast with optimization:

from chromo_map import Color
gray = Color('#888888')
optimized = gray.maximize_contrast_optimization('white')
print(f"Optimized: {optimized.hex}")
Optimized: #0d0d0d
property rgb

Return the color as an RGB string.

Returns:

The color as an RGB string.

Return type:

str

Examples

Get the color as an RGB string:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.rgb
'rgb(255, 165, 0)'
property rgba

Return the color as an RGBA string.

Returns:

The color as an RGBA string.

Return type:

str

Examples

Get the color as an RGBA string:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.rgba
'rgba(255, 165, 0, 0.5)'
property rgbatup

Return the color as a tuple of RGBA values.

Returns:

The color as a tuple of RGB values between 0 and 255 and an alpha value between 0 and 1.

Return type:

Tuple[int, int, int, float]

Examples

Get the color as a tuple of RGBA values:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.rgbatup
(255, 165, 0, 0.5)
property rgbtup

Return the color as a tuple of RGB values.

Returns:

The color as a tuple of RGB values between 0 and 255.

Return type:

Tuple[int, int, int]

Examples

Get the color as a tuple of hex values:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.rgbtup
(255, 165, 0)
set_hsv(h=None, s=None, v=None)[source]

Set specific HSV values while keeping others unchanged.

Parameters:
  • h (float, optional) – The hue value (0-360). If None, keeps current hue.

  • s (float, optional) – The saturation value (0-1). If None, keeps current saturation.

  • v (float, optional) – The value/brightness (0-1). If None, keeps current value.

Returns:

A new color with the specified HSV values.

Return type:

Color

Examples

Set hue to 240 (blue):

from chromo_map import Color
red = Color('red')
blue = red.set_hsv(h=240)
blue
triadic()[source]

Get the triadic colors (120 degrees apart on the color wheel).

Returns:

A tuple of two triadic colors.

Return type:

Tuple[Color, Color]

Examples

Get the triadic colors of red:

from chromo_map import Color
red = Color('red')
triad1, triad2 = red.triadic()
print(f"Triad 1: {triad1.hex}")
print(f"Triad 2: {triad2.hex}")
Triad 1: #00ff00
Triad 2: #0000ff
property tup

Return the color as a tuple.

Returns:

The color as a tuple of RGBA values between 0 and 1.

Return type:

Tuple[float, float, float, float]

Examples

Get the color as a tuple:

from chromo_map import Color
orange = Color('orange', 0.5)
orange.tup
(1.0, 0.6470588235294118, 0.0, 0.5)
with_alpha(alpha)[source]

Return a new Color with the specified alpha value.

Parameters:

alpha (float) – The alpha value between 0 and 1.

Returns:

A new Color with the specified alpha value.

Return type:

Color

Examples

Create a red color with 50% transparency:

from chromo_map import Color
red = Color('red')
red_transparent = red.with_alpha(0.5)

The Color class is the fundamental building block for color operations. It provides:

  • Multiple input formats (hex, RGB, RGBA, named colors)

  • Color space conversions (RGB, HSV, HSL)

  • Color manipulation methods (adjust hue, saturation, brightness)

  • Accessibility methods (contrast ratio, WCAG compliance)

  • Rich display representations for Jupyter notebooks

Example Usage:

from chromo_map import Color

# Create colors in different formats
red = Color('red')
blue = Color('#0066cc')
green = Color('rgb(0, 255, 0)')

# Access color properties
print(f"Red HSV: {red.hsv}")
print(f"Blue hex: {blue.hex}")

# Color manipulation
darker_red = red.adjust_brightness(-0.2)
complementary = red.complementary()

Gradient Class

class chromo_map.Gradient(colors, name=None, alpha=None)[source]

Bases: LinearSegmentedColormap

A color gradient class that extends matplotlib’s LinearSegmentedColormap.

This class provides functionality for creating and manipulating color gradients, including interpolation, resizing, and accessibility adjustments.

Parameters:
  • colors (various) – Input colors in various formats (list, Gradient, colormap, etc.)

  • name (str, optional) – Name of the gradient

  • alpha (float, optional) – Alpha transparency value

Examples

Create a gradient from a list of colors:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
gradient
RGB
RGB colormap
under
bad
over
__add__(other)[source]

Add two gradients together.

__eq__(other)[source]

Check if two gradients are equal based on their colors.

__getattr__(name)[source]

Get attributes from underlying colors.

__getitem__(key)[source]

Get colors from the gradient by index or fraction.

__init__(colors, name=None, alpha=None)[source]

Initialize a Gradient object.

__iter__()[source]

Iterate over the colors in the gradient.

__len__()[source]

Return the number of colors in the gradient.

__mul__(other)[source]

Multiply gradient by an integer.

__or__(other)[source]

Blend two gradients together.

__repr__()[source]

Return a rich colored representation of the gradient.

Return type:

str

__rmul__(other)[source]

Reverse multiplication.

__truediv__(other)[source]

Divide gradient by a number.

adjust_brightness(factor)[source]

Adjust the brightness of all colors in the gradient.

Parameters:

factor (float) – The factor to multiply brightness by.

Returns:

A new gradient with adjusted brightness.

Return type:

Gradient

Examples

Increase brightness by 20%:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
bright = gradient.adjust_brightness(1.2)
bright
RGB_bright1.2
RGB_bright1.2 colormap
under
bad
over
adjust_hue(degrees)[source]

Adjust the hue of all colors in the gradient.

Parameters:

degrees (float) – The number of degrees to adjust the hue by.

Returns:

A new gradient with adjusted hue.

Return type:

Gradient

Examples

Adjust hue by 60 degrees:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
shifted = gradient.adjust_hue(60)
shifted
RGB_hue+60
RGB_hue+60 colormap
under
bad
over
adjust_lightness(factor)[source]

Adjust the lightness of all colors in the gradient.

Parameters:

factor (float) – The factor to multiply lightness by.

Returns:

A new gradient with adjusted lightness.

Return type:

Gradient

Examples

Decrease lightness by 30%:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
dark = gradient.adjust_lightness(0.7)
dark
RGB_light0.7
RGB_light0.7 colormap
under
bad
over
adjust_saturation(factor)[source]

Adjust the saturation of all colors in the gradient.

Parameters:

factor (float) – The factor to multiply saturation by.

Returns:

A new gradient with adjusted saturation.

Return type:

Gradient

Examples

Decrease saturation by 50%:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
desaturated = gradient.adjust_saturation(0.5)
desaturated
RGB_sat0.5
RGB_sat0.5 colormap
under
bad
over
analyze_contrast(background_color)[source]

Analyze contrast ratios of all colors against a background.

Parameters:

background_color (Color or str) – The background color to analyze against.

Returns:

Dictionary containing contrast analysis results.

Return type:

Dict[str, Any]

Examples

Analyze contrast against white background:

from chromo_map import Gradient
colors = ['#000000', '#808080', '#ffffff']
gradient = Gradient(colors, name='Grayscale')
analysis = gradient.analyze_contrast('white')
print(f"Average contrast: {analysis['average_contrast']:.2f}")
Average contrast: 8.65
complementary()[source]

Get the complementary gradient (all colors shifted 180 degrees).

Returns:

A new gradient with complementary colors.

Return type:

Gradient

Examples

Get complementary gradient:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
complement = gradient.complementary()
complement
RGB_complementary
RGB_complementary colormap
under
bad
over
find_accessible_version(background_color, level='AA')[source]

Find accessible version of all colors in the gradient.

Parameters:
  • background_color (Color or str) – The background color to ensure accessibility against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

Returns:

A new gradient with accessible colors.

Return type:

Gradient

Examples

Find accessible version of gradient:

from chromo_map import Gradient
colors = ['#ffcccc', '#ccffcc', '#ccccff']
gradient = Gradient(colors, name='Pastels')
accessible = gradient.find_accessible_version('white')
accessible
Pastels_accessible
Pastels_accessible colormap
under
bad
over
make_accessible(background_color, level='AA')[source]

Make all colors in the gradient accessible against a background color.

Parameters:
  • background_color (Color or str) – The background color to ensure accessibility against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

Returns:

A new gradient with accessible colors.

Return type:

Gradient

Examples

Make gradient accessible against white background:

from chromo_map import Gradient
colors = ['#ffcccc', '#ccffcc', '#ccccff']
gradient = Gradient(colors, name='Pastels')
accessible = gradient.make_accessible('white')
accessible
Pastels_accessible
Pastels_accessible colormap
under
bad
over

Maximize contrast of all colors using binary search.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • precision (float, default 0.001) – The precision for binary search convergence.

Returns:

A new gradient with maximized contrast colors.

Return type:

Gradient

Examples

Maximize contrast with binary search:

from chromo_map import Gradient
colors = ['#ff6666', '#66ff66', '#6666ff']
gradient = Gradient(colors, name='Light')
optimized = gradient.maximize_contrast_binary_search('white')
optimized
Light_max_contrast_binary
Light_max_contrast_binary colormap
under
bad
over
maximize_contrast_iterative(background_color, level='AA', adjust_lightness=True, step_size=0.1, max_attempts=50)[source]

Maximize contrast of all colors using iterative approach.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • step_size (float, default 0.1) – The step size for adjustments.

  • max_attempts (int, default 50) – Maximum number of adjustment attempts.

Returns:

A new gradient with maximized contrast colors.

Return type:

Gradient

Examples

Maximize contrast iteratively:

from chromo_map import Gradient
colors = ['#ff6666', '#66ff66', '#6666ff']
gradient = Gradient(colors, name='Light')
optimized = gradient.maximize_contrast_iterative('white')
optimized
Light_max_contrast_iterative
Light_max_contrast_iterative colormap
under
bad
over
maximize_contrast_optimization(background_color, level='AA', method='golden_section')[source]

Maximize contrast of all colors using mathematical optimization.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • method (str, default 'golden_section') – The optimization method to use (‘golden_section’ or ‘gradient_descent’).

Returns:

A new gradient with maximized contrast colors.

Return type:

Gradient

Examples

Maximize contrast with optimization:

from chromo_map import Gradient
colors = ['#ff6666', '#66ff66', '#6666ff']
gradient = Gradient(colors, name='Light')
optimized = gradient.maximize_contrast_optimization('white')
optimized
Light_max_contrast_optimization
Light_max_contrast_optimization colormap
under
bad
over
rename(new_name)[source]

Rename the gradient.

Parameters:

new_name (str) – The new name for the gradient.

Returns:

The gradient with the new name.

Return type:

Gradient

Examples

Rename the gradient:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='rGb')
gradient.rename('New Gradient')
New Gradient
New Gradient colormap
under
bad
over
resize(num)[source]

Resize the gradient to a new number of colors.

Parameters:

num (int) – The new number of colors.

Returns:

The new gradient with the new number of colors.

Return type:

Gradient

Examples

Resize the gradient to 32 colors:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='rGb')
gradient.resize(32)
rGb
rGb colormap
under
bad
over
reversed(name=None)[source]

Return a new gradient with the colors reversed.

Parameters:

name (str, optional) – The name of the new gradient.

Returns:

The new gradient with the colors reversed.

Return type:

Gradient

Examples

Create a reversed gradient:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='rGb')
gradient.reversed()
custom
custom colormap
under
bad
over
to_div(maxn=None, as_png=False)[source]

Convert the gradient to an HTML div.

Parameters:
  • maxn (int, optional) – The maximum number of colors to display.

  • as_png (bool, optional) – Whether to display the gradient as a PNG image.

Returns:

The gradient as an HTML div.

Return type:

HTML

Examples

Convert the gradient to an HTML div:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='rGb')
gradient.to_div(as_png=False)
rGb
to_drawing(width=500, height=50, filename=None)[source]

Convert the gradient to an SVG drawing.

to_matplotlib()[source]

Convert the gradient to a matplotlib figure.

to_png()[source]

Convert the gradient to a PNG image.

with_alpha(alpha)[source]

Return a new gradient with the specified alpha value.

Parameters:

alpha (float) – The alpha value (0-1)

Returns:

A new gradient with the specified alpha value

Return type:

Gradient

Examples

Create a gradient with 50% transparency:

from chromo_map import Gradient
colors = ['#ff0000', '#00ff00', '#0000ff']
gradient = Gradient(colors, name='RGB')
transparent = gradient.with_alpha(0.5)
transparent
RGB
RGB colormap
under
bad
over

The Gradient class represents sequences of colors with interpolation capabilities:

  • Create gradients from color lists, matplotlib colormaps, or palettes

  • Resample to different lengths

  • Apply transformations (reverse, adjust alpha)

  • Rich HTML representations

  • Integration with matplotlib and plotly

Example Usage:

from chromo_map import Gradient, Color

# Create gradients
grad1 = Gradient(['red', 'blue'], 10)
grad2 = Gradient.from_mpl('viridis', 20)

# Manipulate gradients
reversed_grad = grad1.reverse()
resampled = grad1.resample(5)

# Access colors
first_color = grad1[0]
middle_colors = grad1[2:8]

Swatch Class

class chromo_map.Swatch(gradients, maxn=32)[source]

Bases: object

A class for representing a collection of gradients.

__init__(gradients, maxn=32)[source]
__iter__()[source]

Iterate over gradients.

__len__()[source]

Return the number of gradients.

adjust_brightness(factor)[source]

Adjust the brightness of all gradients in the swatch.

Parameters:

factor (float) – The factor to multiply brightness by.

Returns:

A new swatch with adjusted brightness.

Return type:

Swatch

Examples

Increase brightness by 10%:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff0000', '#00ff00'], name='RedGreen')]
swatch = Swatch(gradients)
bright = swatch.adjust_brightness(1.1)
bright
RedGreen_bright1.1
adjust_hue(degrees)[source]

Adjust the hue of all gradients in the swatch.

Parameters:

degrees (float) – The number of degrees to adjust the hue by.

Returns:

A new swatch with adjusted hue.

Return type:

Swatch

Examples

Adjust hue by 90 degrees:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff0000', '#00ff00'], name='RedGreen')]
swatch = Swatch(gradients)
shifted = swatch.adjust_hue(90)
shifted
RedGreen_hue+90
adjust_lightness(factor)[source]

Adjust the lightness of all gradients in the swatch.

Parameters:

factor (float) – The factor to multiply lightness by.

Returns:

A new swatch with adjusted lightness.

Return type:

Swatch

Examples

Decrease lightness by 15%:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff0000', '#00ff00'], name='RedGreen')]
swatch = Swatch(gradients)
dark = swatch.adjust_lightness(0.85)
dark
RedGreen_light0.8
adjust_saturation(factor)[source]

Adjust the saturation of all gradients in the swatch.

Parameters:

factor (float) – The factor to multiply saturation by.

Returns:

A new swatch with adjusted saturation.

Return type:

Swatch

Examples

Decrease saturation by 25%:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff0000', '#00ff00'], name='RedGreen')]
swatch = Swatch(gradients)
desaturated = swatch.adjust_saturation(0.75)
desaturated
RedGreen_sat0.8
analyze_contrast(background_color)[source]

Analyze contrast ratios of all gradients against a background.

Parameters:

background_color (Color or str) – The background color to analyze against.

Returns:

Dictionary containing contrast analysis results for each gradient.

Return type:

Dict[str, Any]

Examples

Analyze contrast against white background:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#000000', '#808080'], name='Darks')]
swatch = Swatch(gradients)
analysis = swatch.analyze_contrast('white')
print(f"Gradients analyzed: {len(analysis['gradients'])}")
Gradients analyzed: 1
append(gradient)[source]

Append a new gradient to the swatch.

Parameters:

gradient (Gradient) – The gradient to append.

Return type:

None

Examples

Append a new gradient to the swatch:

from chromo_map import Swatch, Gradient
swatch = Swatch([])
swatch.append(Gradient(['#ff0000', '#00ff00', '#0000ff'], name='RGB'))
RGB
complementary()[source]

Get the complementary swatch (all gradients with complementary colors).

Returns:

A new swatch with complementary gradients.

Return type:

Swatch

Examples

Get complementary swatch:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff0000', '#00ff00'], name='RedGreen')]
swatch = Swatch(gradients)
complement = swatch.complementary()
complement
RedGreen_complementary
find_accessible_version(background_color, level='AA')[source]

Find accessible version of all gradients in the swatch.

Parameters:
  • background_color (Color or str) – The background color to ensure accessibility against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

Returns:

A new swatch with accessible gradients.

Return type:

Swatch

Examples

Find accessible version of swatch:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ffcccc', '#ccffcc'], name='Light')]
swatch = Swatch(gradients)
accessible = swatch.find_accessible_version('white')
accessible
Light_accessible
make_accessible(background_color, level='AA')[source]

Make all gradients in the swatch accessible against a background color.

Parameters:
  • background_color (Color or str) – The background color to ensure accessibility against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

Returns:

A new swatch with accessible gradients.

Return type:

Swatch

Examples

Make swatch accessible against white background:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ffcccc', '#ccffcc'], name='Pastels')]
swatch = Swatch(gradients)
accessible = swatch.make_accessible('white')
accessible
Pastels_accessible

Maximize contrast of all gradients using binary search.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • precision (float, default 0.001) – The precision for binary search convergence.

Returns:

A new swatch with maximized contrast gradients.

Return type:

Swatch

Examples

Maximize contrast with binary search:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff6666', '#66ff66'], name='Light')]
swatch = Swatch(gradients)
optimized = swatch.maximize_contrast_binary_search('white')
optimized
Light_max_contrast_binary
maximize_contrast_iterative(background_color, level='AA', adjust_lightness=True, step_size=0.1, max_attempts=50)[source]

Maximize contrast of all gradients using iterative approach.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • adjust_lightness (bool, default True) – Whether to adjust lightness (True) or brightness/value (False).

  • step_size (float, default 0.1) – The step size for adjustments.

  • max_attempts (int, default 50) – Maximum number of adjustment attempts.

Returns:

A new swatch with maximized contrast gradients.

Return type:

Swatch

Examples

Maximize contrast iteratively:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff6666', '#66ff66'], name='Light')]
swatch = Swatch(gradients)
optimized = swatch.maximize_contrast_iterative('white')
optimized
Light_max_contrast_iterative
maximize_contrast_optimization(background_color, level='AA', method='golden_section')[source]

Maximize contrast of all gradients using mathematical optimization.

Parameters:
  • background_color (Color or str) – The background color to maximize contrast against.

  • level (str, default 'AA') – The WCAG level to achieve (‘AA’ or ‘AAA’).

  • method (str, default 'golden_section') – The optimization method to use (‘golden_section’ or ‘gradient_descent’).

Returns:

A new swatch with maximized contrast gradients.

Return type:

Swatch

Examples

Maximize contrast with optimization:

from chromo_map import Swatch, Gradient
gradients = [Gradient(['#ff6666', '#66ff66'], name='Light')]
swatch = Swatch(gradients)
optimized = swatch.maximize_contrast_optimization('white')
optimized
Light_max_contrast_optimization
to_dict()[source]

Convert to a dictionary of gradient names to colors.

to_grid(as_png=False)[source]

Convert the swatch to an HTML grid.

with_max(maxn)[source]

Return a new Swatch with a different maximum number of gradients.

The Swatch class manages collections of gradients with grid-based visualization:

  • Organize multiple gradients

  • Grid-based display in Jupyter notebooks

  • Batch operations on gradient collections

  • Export capabilities

Example Usage:

from chromo_map import Swatch, Gradient

# Create swatch with multiple gradients
gradients = [
    Gradient(['red', 'white'], 10),
    Gradient(['blue', 'white'], 10),
    Gradient(['green', 'white'], 10)
]

swatch = Swatch(gradients, ncols=2)

# Display in Jupyter (shows as grid)
swatch

Class Hierarchy

digraph inheritanceeb69e892be { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Color" [URL="#chromo_map.Color",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A class for representing colors."]; "Colormap" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Baseclass for all scalar to RGBA mappings."]; "Gradient" [URL="#chromo_map.Gradient",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A color gradient class that extends matplotlib's LinearSegmentedColormap."]; "LinearSegmentedColormap" -> "Gradient" [arrowsize=0.5,style="setlinewidth(0.5)"]; "LinearSegmentedColormap" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Colormap objects based on lookup tables using linear segments."]; "Colormap" -> "LinearSegmentedColormap" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Swatch" [URL="#chromo_map.Swatch",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A class for representing a collection of gradients."]; }