Python API Overview

Palettize can be used directly from Python scripts and notebooks in addition to the CLI.

Installation

pip install palettize

Quick Start

from palettize import create_colormap, get_scaler_by_name

# Create a colormap from a preset
cmap = create_colormap(preset="viridis", name="Viridis")

# Get a color at a specific position (0-1)
hex_color = cmap.get_color(0.5)  # "#21918d"
rgb = cmap.get_color(0.5, output_format="rgb_tuple")  # (33, 145, 141)

# Create from custom colors
cmap2 = create_colormap(
    colors=["#0000ff", "white", "#ff0000"],
    name="BlueWhiteRed"
)

# Use a scaler to map data values
scaler = get_scaler_by_name("linear", domain_min=0, domain_max=100)
color = cmap2.apply_scaler(50, scaler)  # Color at midpoint

Module Exports

The palettize package exports the following:

Core Colormap API

Export	Description
`Colormap`	Main colormap class
`ColorStop`	Individual color stop
`create_colormap()`	Factory function to create colormaps
`InputColor`	Type alias for accepted color formats
`parse_input_color()`	Parse various color formats

Scaling Functions

Export	Description
`get_scaler_by_name()`	Factory to create scalers by name
`get_linear_scaler()`	Linear scaling
`get_power_scaler()`	Power scaling
`get_sqrt_scaler()`	Square root scaling
`get_log_scaler()`	Logarithmic scaling
`get_symlog_scaler()`	Symmetric log scaling
`ScalingFunction`	Type alias for scaling functions

Presets

Export	Description
`list_available_presets()`	List all available preset names
`search_presets()`	Filter by name, category, or publisher
`get_preset_info()`	Metadata for one preset
`list_categories()`	Category names used by `search_presets`
`load_preset_data()`	Load raw preset data
`PresetInfo`	Metadata record returned by preset search

Exporters

Export	Description
`get_exporter()`	Get an exporter by identifier
`list_available_exporters()`	List all available exporters
`register_exporter()`	Register a custom exporter
`load_plugin_exporters()`	Load exporters from plugins
`BaseExporter`	Base class for a custom exporter
`Opt` / `OptionSpec`	Declarative option schema (`palettize formats` reads this)

Analysis

Export	Description
`analyze()`	Lightness, ΔE2000 uniformity, and color-vision simulation
`ColormapAnalysis`	The report `analyze()` returns
`simulate_cvd()`	Simulate one color under a color-vision deficiency

Rendering

Export	Description
`write_image()`	Write a `.png` or `.svg` preview
`png_bytes()`	PNG bytes, with no Pillow dependency
`svg_document()`	Standalone SVG document
`terminal_swatch()`	Rich text swatch for the terminal

Example: Full Workflow

from palettize import (
    create_colormap,
    get_scaler_by_name,
    get_exporter,
    list_available_presets,
)

# See what presets are available
presets = list_available_presets()
print(presets[:5])  # First 5 presets

# Create a colormap
cmap = create_colormap(
    preset="viridis",
    interpolation_space="oklch",
    cut_start=0.1,  # Skip first 10%
    cut_end=0.9,    # Skip last 10%
)

# Create a scaler for your data range
scaler = get_scaler_by_name(
    "linear",
    domain_min=0,
    domain_max=255
)

# Get colors for specific values
for value in [0, 64, 128, 192, 255]:
    color = cmap.apply_scaler(value, scaler)
    print(f"{value}: {color}")

# Export to a format
exporter = get_exporter("gdal")
output = exporter.export(
    colormap=cmap,
    scaler=scaler,
    domain_min=0,
    domain_max=255,
    options={"num_colors": 256}
)
print(output)

Transforms, Analysis, and Files

Transforms return a new colormap. analyze does not modify one. A saved file reloads through Colormap.load and can be passed to any command that accepts a preset name.

from palettize import Colormap, analyze, write_image

cmap = Colormap.from_preset("viridis").cut(0.2, 0.8).reversed()
cmap.save("my-map.json")

report = analyze(cmap)
report.lightness.shape       # "sequential"
report.uniformity.is_uniform
report.warnings              # plain-language problems; empty when clean

write_image(cmap, "preview.png")

See Colormap for the transform methods, and the transforms and colormap files guides.