Colorthief

0.2.1 · active · verified Thu Apr 16

Colorthief is a minimalistic Python module (version 0.2.1) for extracting the dominant color or a representative color palette from an image. It relies on the Pillow library for image processing and uses a modified median cut quantization algorithm. While it hasn't seen recent updates, it remains functional for basic color extraction tasks.

Common errors

```
ImportError: cannot import name ColorThief from 'colorthief'
```
cause The `colorthief` package or its dependencies (like Pillow) were not installed correctly, or there's an environment conflict preventing proper import.

fix First, ensure `Pillow` is installed (`pip install Pillow`). Then, try reinstalling `colorthief` by running `pip uninstall colorthief` followed by `pip install colorthief`. Check your Python environment for conflicts.
```
Colorthief / PIL is returning wrong values (inaccurate colours)
```
cause The median cut algorithm used by `colorthief`, especially with higher `quality` settings, might not always align perfectly with human visual perception of 'dominant' color. Also, some images naturally lack a single clearly dominant color.

fix Adjust the `quality` parameter to `1` for the highest accuracy, though this will be slower. For images with complex color distributions, consider increasing the `color_count` for the palette or exploring alternative libraries like `fast-colorthief` which might offer different quantization algorithms.

Warnings

deprecated The `colorthief` library (version 0.2.1) has not been updated since February 2017. While it remains functional, more actively maintained and faster alternatives like `fast-colorthief` or `modern_colorthief` are available and recommended for new projects or performance-critical applications.
Fix: For new projects or improved performance, consider `pip install fast-colorthief` or `pip install modern_colorthief` and adjust imports/API calls accordingly.
gotcha The `quality` parameter in `get_color()` and `get_palette()` significantly impacts both processing speed and the perceived accuracy of the extracted colors. A `quality` of 1 offers the highest precision but is the slowest, while larger numbers (e.g., 10 or more) provide faster results at the cost of potential visual accuracy.
Fix: Experiment with different `quality` values. For the most visually accurate dominant color, use `quality=1`. For a faster, less precise palette, increase the `quality` value.
gotcha When passing a file object instead of a file path to `ColorThief`, the object must be opened in binary mode (`'rb'`) and implement `read()`, `seek()`, and `tell()` methods.
Fix: Ensure file objects are opened in binary mode (e.g., `with open('image.jpg', 'rb') as f: color_thief = ColorThief(f)`).

Install

pip install colorthief Install latest stable version

Imports

ColorThief
```
from colorthief import ColorThief
```

Quickstart

This quickstart demonstrates how to create a `ColorThief` object from an image file, extract its dominant color, and generate a color palette. It includes an example of creating a dummy image for easy testing.

import os

# NOTE: Pillow is a required dependency for colorthief.
# Ensure it's installed: pip install Pillow

try:
    from PIL import Image
    from colorthief import ColorThief

    # Create a dummy image for demonstration if it doesn't exist
    # In a real scenario, replace 'temp_image.png' with your image file path.
    dummy_image_path = "temp_image.png"
    if not os.path.exists(dummy_image_path):
        # Create a simple image with a dominant red color
        img = Image.new('RGB', (100, 100), color = 'red')
        img.save(dummy_image_path)
        print(f"Created a dummy image: {dummy_image_path}")

    # Initialize ColorThief with your image file path
    color_thief = ColorThief(dummy_image_path)

    # Get the dominant color (RGB tuple)
    # quality=1 provides the highest quality but is slower.
    dominant_color = color_thief.get_color(quality=1)
    print(f"Dominant color (RGB): {dominant_color}")

    # Get a color palette (list of RGB tuples)
    # color_count: desired number of colors in the palette
    # quality: higher numbers are faster but lower quality
    palette = color_thief.get_palette(color_count=6, quality=10)
    print(f"Color palette (RGB): {palette}")

    # To clean up the dummy image after use:
    # os.remove(dummy_image_path)

except ImportError as e:
    if "Pillow" in str(e):
        print("Error: Pillow is not installed. Please install it with 'pip install Pillow'.")
    else:
        print(f"An import error occurred: {e}")
except FileNotFoundError:
    print(f"Error: The image file '{dummy_image_path}' was not found.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →