Extract color palettes from images using the command line or Python library

---

Documentation: qtiptip.github.io/Pylette

Source code: qTipTip/Pylette

---

What is Pylette?

Pylette helps you extract color palettes from images. Use the command-line interface for quick tasks or the Python library for more advanced workflows.

Key Features: - Extract palettes from single images or batch process multiple files - Export to JSON format with metadata and hex colors - Support for different colorspaces (RGB, HSV, HLS) - Handle transparent images with alpha channel masking - Fast parallel processing for multiple images - Rich progress display with color previews

Getting Started

Installation

You can easily install Pylette using pip:

shell pip install Pylette

Or if you prefer using uv:

shell uv add Pylette

Command Line Usage

Extract palettes from images using simple commands:

```bash

Extract 5 colors from an image (shows clean table output)

pylette image.jpg

Process multiple images and export to JSON files

pylette *.jpg --export-json --output results/

Extract 8 colors in HSV colorspace with structured export

pylette photo.png --n 8 --colorspace hsv --export-json --output colors.json

Batch process with parallel processing and table display

pylette images/*.png --n 6 --num-threads 4 ```

Example Output: ✓ Extracted 5 colors from sunset.jpg ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓ ┃ Hex ┃ RGB ┃ Frequency┃ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩ │ #FF6B35 │ (255, 107, 53) │ 28.5% │ │ #F7931E │ (247, 147, 30) │ 23.2% │ │ #FFD23F │ (255, 210, 63) │ 18.7% │ │ #06FFA5 │ (6, 255, 165) │ 15.4% │ │ #4ECDC4 │ (78, 205, 196) │ 14.2% │ └──────────┴─────────────────┴──────────┘

Export Options

Control how your palettes are saved:

```bash

Individual JSON files for each image

pylette *.jpg --export-json --output palettes/

Creates: palettes/palette001.json, palettes/palette002.json, etc.

Combined JSON file with all palettes

pylette *.jpg --export-json --output all_colors.json

Export with different colorspace

pylette image.jpg --colorspace hsv --export-json --output hsv_palette.json

Suppress table output, only export JSON

pylette *.png --export-json --output results/ --no-stdout ```

Common Options

```bash

Use different extraction algorithms

pylette image.jpg --mode MedianCut --n 6

Handle transparent images

pylette logo.png --alpha-mask-threshold 128

Customize output

pylette image.jpg --no-stdout --display-colors ```

Python Library

For programmatic usage and advanced workflows:

```python from Pylette import extract_colors

Extract palette with rich metadata

palette = extractcolors(image='image.jpg', palettesize=8)

Access color properties with hex support

for color in palette.colors: print(f"RGB: {color.rgb}") print(f"Hex: {color.hex}") print(f"HSV: {color.hsv}") print(f"Frequency: {color.freq:.2%}")

Export to structured JSON

palette.to_json(filename='palette.json', colorspace='hsv')

Access metadata

print(f"Source: {palette.imagesource}") print(f"Extraction time: {palette.processingstats['extraction_time']:.2f}s")

Simple export method

palette.export('mycolors', colorspace='hls', includemetadata=True) ```

Batch Processing

For processing multiple images programmatically:

```python from Pylette import batchextractcolors

Process multiple images with parallel processing

results = batchextractcolors( images=['image1.jpg', 'image2.png', 'image3.jpg'], palettesize=8, maxworkers=4, mode='KMeans' )

Handle results

for result in results: if result.success and result.palette: print(f"✓ {result.source}: {len(result.palette.colors)} colors") result.palette.export(f"{result.source}_palette") else: print(f"✗ {result.source}: {result.error}") ```

The Python library provides full programmatic access to all CLI features plus detailed metadata and customization options.

JSON Export Format

Pylette exports rich JSON data with semantic field names:

json { "colors": [ { "rgb": [142, 152, 174], "hex": "#8E98AE", "frequency": 0.25 } ], "palette_size": 5, "colorspace": "rgb", "metadata": { "image_source": "photo.jpg", "extraction_params": { "palette_size": 5, "mode": "KMeans" }, "processing_stats": { "extraction_time": 0.234 } } }

Different colorspaces use semantic field names: - RGB: {"rgb": [255, 128, 64], "hex": "#FF8040", "frequency": 0.25} - HSV: {"hsv": [0.08, 0.75, 1.0], "rgb": [255, 128, 64], "hex": "#FF8040", "frequency": 0.25} - HLS: {"hls": [0.08, 0.63, 0.75], "rgb": [255, 128, 64], "hex": "#FF8040", "frequency": 0.25}

Interactive Table Output

When run without --export-json, Pylette displays a clean table:

✓ Extracted 5 colors from photo.jpg ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓ ┃ Hex ┃ RGB ┃ Frequency┃ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩ │ #FF8040 │ (255, 128, 64) │ 25.2% │ │ #4080FF │ (64, 128, 255) │ 30.1% │ └──────────┴─────────────────┴──────────┘

The table automatically adapts to show the chosen colorspace (RGB, HSV, or HLS).

Working with Transparent Images

Handle transparency in both CLI and Python:

```bash

CLI: Exclude pixels with alpha < 128

pylette transparent.png --alpha-mask-threshold 128 ```

```python

Python: Same functionality

from Pylette import extractcolors palette = extractcolors('transparent.png', alphamaskthreshold=128) ```

Why Choose Pylette?

• Clean, Visual Output: No more raw CSV dumps - see your colors in beautiful tables
• Rich Metadata: Every palette includes extraction details, timing, and image info
• Flexible Export: JSON format with semantic field names for easy parsing
• Batch Ready: Process hundreds of images with parallel processing and progress bars
• Developer Friendly: Comprehensive Python API with full type hints
• Modern CLI: Intuitive commands that guide you toward the right options

CLI Reference

For complete usage information:

bash pylette --help

All Options

``` Usage: pylette [OPTIONS] IMAGE_SOURCES...

Arguments: IMAGE_SOURCES... Images, URLs, or directories to process [required]

Options: --mode [KMeans|MedianCut] Extraction algorithm [default: KMeans] --n INTEGER Number of colors to extract [default: 5] --sort-by [frequency|luminance] Sort colors by [default: luminance] --colorspace [rgb|hsv|hls] Color space [default: rgb] --export-json Export to JSON format --output PATH Output file or directory for JSON export --alpha-mask-threshold [0-255] Alpha threshold for transparency --num-threads INTEGER Parallel processing threads --display-colors Show palette images --no-stdout Suppress table output --help Show help message ```