A toolkit to extract dominant colors from images using various K-Means clustering approaches.
| Example |
|---|
 |
Extraction Methods
- Original K-Means: Standard K-Means clustering approach
- Aggressive Weighting: K-Means with aggressive saturation weighting to emphasize vibrant colors
- Vibrant Separate: Separate clustering for vibrant minority colors and base colors
- LAB Enhanced: LAB color space with saturation-weighted sampling for perceptually uniform clustering
- Multi-stage: Multi-stage extraction: vibrant colors first, then distinct base colors
Sorting
- Spatial sorting (left-to-right or top-to-bottom)
- Frequency-based sorting
With pip:
pip install color-extractOr with uv:
uv add color-extract# Basic extraction with default settings
color-extract image.jpg
# Extract 8 colors using the vibrant method
color-extract image.jpg -c 8 -m vibrant
# Compare all methods and define output folder
color-extract image.jpg -m all -o ./myfolderusage: color-extract [options] image
Arguments:
image Path to the input image
Options:
-h, --help Show help message
--colors, -c Number of colors to extract (default: 6)
--method, -m Extraction method (default: lab)
--output, -o Output file path (default: ./output)
--sort, -s Sorting method: (default: x-axis)
--no-plot Disable plot generation
--max-dimension Max dimension for downscaling (default: 64)
--dpi DPI for output plots (default: 150)
Console
┌─────────────────────────────────────┐
│ LAB Enhanced │
└─────────────────────────────────────┘
┌───────┬──────────┬──────────────────┐
│ ■■■ │ #277595 │ (39, 117, 149) │
│ ■■■ │ #68b2c6 │ (104, 178, 198) │
│ ■■■ │ #6c6963 │ (108, 105, 99) │
│ ■■■ │ #394d4d │ (57, 77, 77) │
│ ■■■ │ #782722 │ (120, 39, 34) │
│ ■■■ │ #102937 │ (16, 41, 55) │
└───────┴──────────┴──────────────────┘
Result saved to output/colors_image_lab_6.png
Plotted Images
| Aggressive Weighting | LAB Enhanced |
|---|---|
 |
 |
| Multi-stage | K-Means |
|---|---|
 |
 |
import color_extract
import numpy as np
from PIL import Image
# Simple extraction from file
colors = color_extract.extract_colors('image.jpg', method='lab', n_colors=5)
for color in colors:
print(color_extract.rgb_to_hex(color))
# Use with numpy array
img = Image.open('image.jpg')
img_array = np.array(img)
colors = color_extract.extract_colors(img_array, method='aggressive')
# Advanced usage with visualization
from color_extract import plot_single_result, load_and_prepare_image
img, img_array = load_and_prepare_image('image.jpg')
colors = color_extract.extract_colors_lab_enhanced(img_array, n_colors=6)
sorted_colors = color_extract.sort_colors_by_spatial_position(img_array, colors)
# Generate visualization
plot_single_result(img, img_array, sorted_colors, 'LAB Enhanced', 'output.png')Main convenience function for color extraction.
colors = extract_colors(image, method='lab', n_colors=6, sort_by='x-axis')
# Parameters:
# - image: File path (str) or numpy array (H, W, 3)
# - method: Extraction method name ('kmeans', 'aggressive', 'vibrant', 'lab', 'multstage')
# - n_colors: Number of colors to extract
# - sort_by: Sorting method ('x-axis', 'y-axis', 'frequency')
# Returns:
# - List of RGB tuplesEach method can be used directly for more control:
# Original K-Means
colors = extract_colors_kmeans_original(img_array, n_colors=6)
# LAB color space
colors = extract_colors_lab_enhanced(img_array, n_colors=6, saturation_boost=5.0)
# Aggressive saturation weighting
colors = extract_colors_weighted_aggressive(img_array, n_colors=6, saturation_boost=10.0)
# Separate vibrant colors
colors = extract_colors_vibrant_separate(img_array, n_colors=6, n_vibrant=3)
# Multi-stage extraction
colors = extract_colors_multistage(img_array, n_colors=6)