API Reference¶

Package Overview

Modern Colorthief provides two main functions for color extraction, both backed by a Rust implementation of the Median Cut Color Quantization algorithm.

Functions

modern_colorthief.get_palette(image, color_count=10, quality=10)[source]¶

Extract a palette of dominant colors from an image.

Uses the Median Cut Color Quantization algorithm implemented in Rust for high performance.

Args:

image: File path, raw image bytes, or a BytesIO object. color_count: Number of colors to extract. Defaults to 10. quality: Downsample factor – every Nth pixel is skipped.

Higher is faster but less accurate. Defaults to 10.

Returns:

A deduplicated list of RGB tuples, each (R, G, B) with values in the range 0..=255.

Raises:

ValueError: If the image is invalid or the algorithm fails. TypeError: If the image type is unsupported.

Example:

>>> from modern_colorthief import get_palette
>>> get_palette("photo.jpg", color_count=5)
[(139, 69, 19), (220, 20, 60), (255, 250, 240), (34, 139, 34), (70, 130, 180)]

Parameters:

image (str | bytes | BytesIO)
color_count (int)
quality (int)

Return type:

list[tuple[int, int, int]]

modern_colorthief.get_color(image, quality=10)[source]¶

Extract the single dominant color from an image.

Internally extracts a small palette and returns the top color.

Args:

image: File path, raw image bytes, or a BytesIO object. quality: Downsample factor – every Nth pixel is skipped.

Higher is faster but less accurate. Defaults to 10.

Returns:

An RGB tuple (R, G, B) with values in the range 0..=255.

Raises:

ValueError: If the image is invalid or the algorithm fails. TypeError: If the image type is unsupported.

Example:

>>> from modern_colorthief import get_color
>>> get_color("photo.jpg")
(139, 69, 19)

Parameters:

image (str | bytes | BytesIO)
quality (int)

Return type:

tuple[int, int, int]

Version

modern_colorthief.__version__¶: The current version string of the package.

Accepted Input Types

Both get_color() and get_palette() accept the following input types:

Supported Inputs¶
Type	Description
`str`	A file path pointing to a supported image format (JPEG, PNG, WebP, GIF, BMP, TIFF)
`bytes`	Raw image data in memory
`io.BytesIO`	A binary I/O stream containing image data

Return Types

Return Values¶
Function	Return Type
`get_color()`	`tuple[int, int, int]` – an RGB triple
`get_palette()`	`list[tuple[int, int, int]]` – a list of RGB triples

Note

All color values are integers in the range 0..=255 representing the Red, Green, and Blue channels respectively.