Metadata-Version: 2.4
Name: color-palette-extractor
Version: 1.2.1
Summary: Extract dominant colors, generate PNG palettes, JSON exports, and name colors using custom palettes.
Author: Youssef Helioui
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: colormath
Dynamic: license-file

# 🎨 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

```python
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
```json
{
    "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
