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
- __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:
Examples
Interpolate between red and blue:
from chromo_map import Color red = Color('red') blue = Color('blue') red | blue
- 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:
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:
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:
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:
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:
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:
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:
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:
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_binary_search(target_color, level='AA', adjust_lightness=True, precision=0.001)[source]
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:
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:
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:
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:
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).
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:
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
RGBbadover- 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:
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.2badover
- 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:
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+60badover
- 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:
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.7badover
- 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:
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.5badover
- 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:
Examples
Get complementary gradient:
from chromo_map import Gradient colors = ['#ff0000', '#00ff00', '#0000ff'] gradient = Gradient(colors, name='RGB') complement = gradient.complementary() complement
RGB_complementarybadover
- 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:
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_accessiblebadover
- 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:
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_accessiblebadover
- maximize_contrast_binary_search(background_color, level='AA', adjust_lightness=True, precision=0.001)[source]
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:
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_binarybadover
- 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:
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_iterativebadover
- 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:
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_optimizationbadover
- 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:
Examples
Rename the gradient:
from chromo_map import Gradient colors = ['#ff0000', '#00ff00', '#0000ff'] gradient = Gradient(colors, name='rGb') gradient.rename('New Gradient')
New Gradientbadover
- 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:
Examples
Resize the gradient to 32 colors:
from chromo_map import Gradient colors = ['#ff0000', '#00ff00', '#0000ff'] gradient = Gradient(colors, name='rGb') gradient.resize(32)
rGbbadover
- 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:
Examples
Create a reversed gradient:
from chromo_map import Gradient colors = ['#ff0000', '#00ff00', '#0000ff'] gradient = Gradient(colors, name='rGb') gradient.reversed()
custombadover
- 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
- 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:
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
RGBbadover
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.
- 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:
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:
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:
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:
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:
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:
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:
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_binary_search(background_color, level='AA', adjust_lightness=True, precision=0.001)[source]
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:
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:
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:
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
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