color-palette-extractor 1.2.1

Extract dominant colors, generate PNG palettes, JSON exports, and name colors using custom palettes.

🎨 Color Palette Extractor

A modern Python package for extracting dominant colors from images, generating PNG palette previews, exporting color data to JSON, and naming colors using any custom palette (e.g., Pantone, Material, Brand palettes).

Version 1.2.0

This package includes:

• Dominant color extraction using K-Means
• Color dominance percentages — each color includes its share of the image pixels
• Colors sorted by dominance (most dominant first)
• Optional filtering of near-white and/or near-black pixels before extraction
• RGB or HEX output
• PNG color palette image generation
• JSON export with dominance data
• Optional color naming using custom palettes (Pantone-compatible if you provide the licensed palette)
• Command-line interface (colorpalette)
• Clean import API for integration in other scripts

Installation

pip install color-palette-extractor

CLI Usage

colorpalette input.jpg --colors 5 --format hex --json palette.json --png palette.png

Filtering white and black

colorpalette input.jpg --ignore-white --ignore-black --json palette.json

Custom thresholds (default: white=240, black=15):

colorpalette input.jpg --ignore-white --white-threshold 220 --ignore-black --black-threshold 20

Color Naming

Provide a custom palette JSON:

colorpalette input.jpg --name-colors --palette pantone.json

Python Usage

from color_palette_extractor import extract_palette, save_palette_json

# Basic usage
colors, names, dominance = extract_palette("image.jpg", num_colors=5, output_format="hex")

# With white/black filtering
colors, names, dominance = extract_palette(
    "image.jpg",
    num_colors=5,
    output_format="hex",
    ignore_white=True,
    ignore_black=True,
    white_threshold=240,  # optional, default 240
    black_threshold=15,   # optional, default 15
)

# colors and dominance are parallel lists, sorted by dominance descending
for color, pct in zip(colors, dominance):
    print(f"{color} — {pct}%")

# Save to JSON (includes dominance)
save_palette_json(colors, "palette.json", dominance=dominance)

JSON output format

{
    "palette": ["#1a2b3c", "#4d5e6f", "..."],
    "dominance": [45.2, 30.1, 12.4, 7.8, 4.5]
}

Package Structure

color_palette_extractor/
├── extractor.py
├── palette_image.py
├── utils.py
├── color_naming.py
├── cli.py
└── __init__.py

License

MIT License — Copyright (c) 2026 Youssef Helioui