Colormap Class

The Colormap class is the core of Palettize, representing a colormap defined by color stops with optional positions.

create_colormap()

The recommended way to create colormaps is using the create_colormap() factory function:

from palettize import create_colormap

# From a preset
cmap = create_colormap(preset="viridis")

# From custom colors
cmap = create_colormap(colors=["blue", "white", "red"])

Parameters

Parameter	Type	Default	Description
preset	str | None	None	Name of a preset palette
colors	list | None	None	List of colors
interpolation_space	str	"oklch"	Color space for interpolation
name	str | None	None	Display name for the colormap
cut_start	float	0.0	Start of sub-segment (0-1)
cut_end	float	1.0	End of sub-segment (0-1)

You must provide exactly one of preset or colors.

Color Input Formats

Colors can be specified in multiple formats:

# Named colors
create_colormap(colors=["red", "blue", "green"])

# Hex strings
create_colormap(colors=["#ff0000", "#00ff00", "#0000ff"])

# RGB tuples (0-255)
create_colormap(colors=[(255, 0, 0), (0, 255, 0), (0, 0, 255)])

# RGB tuples (0-1)
create_colormap(colors=[(1.0, 0.0, 0.0), (0.0, 1.0, 0.0)])

# Mixed formats
create_colormap(colors=["red", "#00ff00", (0, 0, 255)])

Colormap Class

For more control, you can use the Colormap class directly.

Class Methods

Colormap.from_preset()

from palettize import Colormap

cmap = Colormap.from_preset(
    preset_name="viridis",
    interpolation_space="oklch",
    cut_start=0.0,
    cut_end=1.0
)

Colormap.from_list()

from palettize import Colormap

cmap = Colormap.from_list(
    colors=["blue", "white", "red"],
    name="BWR",
    interpolation_space="oklch",
    cut_start=0.0,
    cut_end=1.0
)

Instance Methods

get_color()

Returns the interpolated color at a position (0-1) in the specified format.

cmap = create_colormap(preset="viridis")

# Hex string (default)
hex_color = cmap.get_color(0.5)  # "#21918d"

# RGB tuple (0-255)
rgb = cmap.get_color(0.5, output_format="rgb_tuple")  # (33, 145, 141)

# RGBA tuple (0-255)
rgba = cmap.get_color(0.5, output_format="rgba_tuple")  # (33, 145, 141, 255)

# RGB float (0-1) - useful for OpenGL, matplotlib
rgb_float = cmap.get_color(0.5, output_format="rgb_float")  # (0.129, 0.567, 0.551)

# HSL tuple and string
hsl = cmap.get_color(0.5, output_format="hsl_tuple")  # (177.9, 62.8, 34.8)
hsl_str = cmap.get_color(0.5, output_format="hsl_string")  # "hsl(178, 63%, 35%)"

# OKLCH string (modern CSS)
oklch = cmap.get_color(0.5, output_format="oklch_string")  # "oklch(59.5% 0.095 191.2)"

# Wide gamut (Display P3)
p3 = cmap.get_color(0.5, output_format="css_color", output_space="display-p3")
# "color(display-p3 0.2770 0.5585 0.5481)"

Parameter	Type	Default	Description
position	float		Position in colormap (0-1)
output_format	str	"hex"	Output format (see table below)
output_space	str	"srgb"	"srgb" or "display-p3". Affects rgb_*, rgba_*, and css_color. Hex is always sRGB

Output Formats

Format	Return Type	Example	Use Case
hex	str	"#21918d"	CSS, general purpose. Always sRGB
rgb_tuple	tuple[int, ...]	(33, 145, 141)	Image processing
rgba_tuple	tuple[int, ...]	(33, 145, 141, 255)	Image processing with alpha
rgb_float	tuple[float, ...]	(0.129, 0.567, 0.551)	OpenGL, matplotlib, scientific
rgba_float	tuple[float, ...]	(0.129, 0.567, 0.551, 1.0)	OpenGL with alpha
hsl_tuple	tuple[float, ...]	(177.9, 62.8, 34.8)	Color manipulation
hsl_string	str	"hsl(178, 63%, 35%)"	CSS HSL
oklch_string	str	"oklch(59.5% 0.095 191.2)"	Modern CSS, perceptual
css_color	str	"color(display-p3 ...)"	Wide gamut CSS

Wide Gamut Support

The output_space parameter enables wide gamut output for modern displays:

# Standard sRGB (default)
srgb_color = cmap.get_color(0.5)  # "#21918d"

# Display P3 (wider gamut)
p3_color = cmap.get_color(0.5, output_format="css_color", output_space="display-p3")
# "color(display-p3 0.2770 0.5585 0.5481)"

# RGB floats in P3 space
p3_rgb = cmap.get_color(0.5, output_format="rgb_float", output_space="display-p3")
# (0.277, 0.559, 0.548)

get_color_object()

Returns the interpolated color as a ColorAide Color object for advanced manipulation:

color_obj = cmap.get_color_object(0.5)

# Access color properties
print(color_obj.space())  # "oklch"
print(color_obj.coords())  # Color coordinates

# Convert to other spaces
srgb = color_obj.convert("srgb")
lab = color_obj.convert("lab")

apply_scaler()

Maps a data value to a color using a scaling function:

from palettize import create_colormap, get_scaler_by_name

cmap = create_colormap(colors=["blue", "white", "red"])
scaler = get_scaler_by_name("linear", domain_min=-100, domain_max=100)

# Get colors for data values
color_neg = cmap.apply_scaler(-50, scaler)   # Blue-ish
color_zero = cmap.apply_scaler(0, scaler)    # White
color_pos = cmap.apply_scaler(50, scaler)    # Red-ish

Parameter	Type	Default	Description
data_value	float		The data value to map
scaler	ScalingFunction		A scaling function
output_format	str	"hex"	Output format

Properties

Property	Type	Description
name	str | None	Colormap display name
stops	list[ColorStop]	List of color stops
interpolation_space	str	Color interpolation space
cut_start	float	Start of sub-segment (0-1)
cut_end	float	End of sub-segment (0-1)

Calling a colormap returns a hex string: cmap(0.5). len(cmap) is the number of stops.

Sampling

cmap.hex_colors(5)   # ['#440154', '#3b528b', '#21918d', '#5cc863', '#fde725']
cmap.rgb_colors(5)
cmap.rgba_colors(5)
cmap.hsl_colors(5)
cmap.colors(5, "rgb_float")

Transforms

Each method returns a new colormap. Cuts compose, and reversed() toggles an _r suffix on the name, as matplotlib does.

from palettize import Colormap

viridis = Colormap.from_preset("viridis")
viridis.reversed()
viridis.cut(0.2, 0.8)
viridis.resampled(11)     # refit to 11 evenly spaced stops
viridis.quantized(5)      # 5 hard-edged bands
viridis.blend(Colormap.from_preset("magma"), 0.5)
viridis + Colormap.from_preset("magma")   # concat

renamed("My Map") returns a copy with a new name. See the transforms guide.

Save and Load

viridis.reversed().save("my-map.json")
Colormap.load("my-map.json")

Files record schema version 1. A newer schema is refused. See colormap files.

ColorStop

A ColorStop represents a single color in the colormap with an optional position.

from palettize import ColorStop

# Position is optional (auto-calculated if not provided)
stop1 = ColorStop(color="red")
stop2 = ColorStop(color="blue", position=0.5)
stop3 = ColorStop(color="#00ff00", position=1.0)

Properties

Property	Type	Description
color	InputColor	Original color input
position	float | None	Position in colormap (0-1)
parsed_color	Color	Parsed ColorAide Color object

Using the Cut Feature

The cut_start and cut_end parameters let you use only a portion of a colormap:

# Use only the middle portion of viridis
cmap = create_colormap(
    preset="viridis",
    cut_start=0.2,  # Skip first 20%
    cut_end=0.8     # Skip last 20%
)

# Position 0 now maps to what was position 0.2
# Position 1 now maps to what was position 0.8
color_start = cmap.get_color(0)  # Color at original 0.2
color_end = cmap.get_color(1)    # Color at original 0.8

Interpolation Spaces

The interpolation_space parameter controls how colors are blended. Common options:

Space	Description
oklch	Perceptually uniform, good for most cases (default)
srgb	Standard RGB, may produce muddy transitions
lab	CIELAB, perceptually uniform
hsl	Hue-Saturation-Lightness
oklch	Improved perceptual uniformity

# Compare interpolation spaces
colors = ["blue", "yellow"]

cmap_srgb = create_colormap(colors=colors, interpolation_space="srgb")
cmap_oklch = create_colormap(colors=colors, interpolation_space="oklch")
cmap_lab = create_colormap(colors=colors, interpolation_space="lab")

# Get midpoint color in each space
print(cmap_srgb.get_color(0.5))   # Different results
print(cmap_oklch.get_color(0.5))
print(cmap_lab.get_color(0.5))

See the Color Interpolation guide for more details.