principal_colors

principal_colors is a dead-simple tool to extract a strong, distinct palette from any image.

It is designed around one obvious path for normal users:

principal-colors path/to/image.jpg

That prints the palette to stdout and also writes a single JSON file next to the image, such as:

image.palette.json

Under the hood, it uses OKLab distances and can optionally account for common color-vision deficiencies, but those are secondary features rather than the headline.

Why this rewrite

This package has been rewritten around a simpler public UX:

• standard CLI flags instead of key=value
• a positional image path
• no import-time side effects
• a clean Python API for both simple and detailed use
• a single runtime dependency: Pillow
• feature-rich advanced exports without cluttering the default experience

Installation

From PyPI:

pip install principal-colors

From a local checkout:

pip install .

For development:

python -m pip install -e '.[dev]'

Command line usage

The basic path is:

principal-colors image.jpg

That will:

• print the palette as hex colors to stdout
• save image.palette.json

Basic examples

principal-colors image.jpg
principal-colors image.jpg --colors 10
principal-colors image.jpg --stdout-only
principal-colors image.jpg --output my_palette.json

Advanced examples

principal-colors image.jpg --cb-mode all
principal-colors image.jpg --save-formats json,svg,png --output-prefix out/palette
principal-colors image.jpg --print-format rgb
principal-colors image.jpg --details

No arguments

If you run:

principal-colors

it shows an overview, a manual, and an ASCII logo.

Python API

The simple API returns hex colors by default:

from principal_colors import extract_palette

colors = extract_palette("image.jpg")
print(colors)

You can ask for other return types:

from principal_colors import extract_palette

rgb_colors = extract_palette("image.jpg", return_format="rgb")
result = extract_palette("image.jpg", return_format="result")

Or use the detailed API directly:

from principal_colors import extract_palette_result

result = extract_palette_result("image.jpg", num_colors=10)
print(result.hex_colors)
print(result.rgb_colors)
print(result.oklab_colors)
result.save()  # writes image.palette.json
result.save_many(["json", "svg", "png"], output_prefix="out/palette")

Public low-level helpers

The lower-level functions are intentionally public, so advanced users can do things like:

from principal_colors import rgb_to_oklab, oklab_to_rgb, simulate_cb

Output formats

The package can write:

• JSON
• TXT
• CSV
• SVG
• PNG swatches
• CSS variables
• Tailwind JSON
• Matplotlib style files
• GIMP palette files

The default automatic save format is JSON because it is a reasonable, machine-readable single-file default.

API docs

A small API reference lives in docs/API.md.

Development

Run checks with:

ruff check .
pytest
python -m build
python -m twine check dist/*

License

MIT.