Pylette

Welcome to Pylette, the easy-to-use Python library for extracting color palettes from images!

Documentation: https://qtiptip.github.io/Pylette/

What is Pylette?

Pylette is a powerful yet user-friendly library designed to help you extract color palettes from images. Whether you're working on computer graphics, visualizations, or generative art, Pylette makes it easy to create visually appealing color sets.

Key features:

Extract color palettes from images
Support for various color modes (RGB, RGBa, HSV, etc.)
Random color selection from palettes
Command-line interface for quick palette extraction

Getting Started

Installation

You can easily install Pylette using pip:

pip install Pylette

Or if you prefer using Poetry:

poetry add Pylette

Quick Start Guide

Here's how to extract a color palette from an image and work with it in Python:

Extracting a Color Palette

from Pylette import extract_colors

palette = extract_colors(image='image.jpg', palette_size=10)
# Access colors by index
most_common_color = palette[0]
least_common_color = palette[-1]

# Get color information
print(most_common_color.rgb)
print(most_common_color.hls)
print(most_common_color.hsv)

# Display the palette, and save the image to file
palette.display(save_to_file=True)

# Save palette's color values to CSV
palette.to_csv(filename='color_palette.csv', frequency=True)

# Pick random colors
random_color = palette.random_color(N=1, mode='uniform')
random_colors = palette.random_color(N=100, mode='frequency')

This will give you a palette of 10 colors, sorted by frequency. The image is automatically resized to 256x256 pixels for faster processing. See the reference documentation for a complete list of available methods and attributes.

Command Line Tool

Pylette also comes with a handy command-line tool. Here's a quick overview of its usage:

Command Line Usage

Extracting a Color Palette using the CLIOptions

pylette --filename image.jpg --mode KM --n 5 --sort_by luminance --colorspace rgb --display-colors True

╰─❯ pylette --help
usage: pylette [-h] (--filename FILENAME | --image-url IMAGE_URL) [--mode {KM,MC}] [--n N] [--sort_by {luminance,frequency}] [--stdout STDOUT] [--colorspace {rgb,hsv,hls}] [--out_filename OUT_FILENAME]
               [--display-colors DISPLAY_COLORS]

options:
  -h, --help            show this help message and exit
  --filename FILENAME   path to image file (default: None)
  --image-url IMAGE_URL
                        url to the image file (default: None)
  --mode {KM,MC}        extraction_mode (KMeans/MedianCut (default: KM)
  --n N                 the number of colors to extract (default: 5)
  --sort_by {luminance,frequency}
                        sort by luminance or frequency (default: luminance)
  --stdout STDOUT       whether to display the extracted color values in the stdout (default: True)
  --colorspace {rgb,hsv,hls}
                        color space to represent colors in (default: RGB)
  --out_filename OUT_FILENAME
                        where to save the csv file (default: None)
  --display-colors DISPLAY_COLORS
                        Open a window displaying the extracted palette (default: False)

Example Palettes

Check out these palettes extracted using Pylette! The top row corresponds to extraction using K-Means, and the bottom row corresponds to Median-Cut extraction. The colors are sorted by luminosity.

Original Image	Extracted Palette

How Pylette Works

Pylette uses various color quantization algorithms to extract the most representative colors from your images. Currently, it supports:

K-Means clustering
Median-Cut algorithm

We'd Love Your Feedback And Contributions!

Pylette is an ongoing project, and we're always looking to improve it. If you have any suggestions, questions, or just want to share how you're using Pylette, please don't hesitate to reach out, or make a pull request on our GitHub repository.

Happy color extracting!