MareArts XColor - High-performance color extraction library for Python

MareArts XColor is a powerful color extraction library that uses advanced clustering algorithms to extract dominant colors from images. It features both CPU and GPU acceleration, multiple color space support, and intelligent preprocessing for accurate color analysis.

🚀 Installation

For CPU Users (Most Common)

pip install marearts-xcolor

For GPU Users (Advanced Performance)

# For CUDA 11.x
pip install marearts-xcolor[gpu] cupy-cuda11x

# For CUDA 12.x
pip install marearts-xcolor[gpu] cupy-cuda12x

📋 Requirements

• Python 3.9, 3.10, 3.11, or 3.12
• Operating System: Windows, macOS, or Linux
• Architecture: x86_64 or ARM64

🎯 Quick Start

Basic Usage

from marearts_xcolor import ColorExtractor

# Create extractor instance
extractor = ColorExtractor()

# Extract 5 dominant colors from an image
colors = extractor.extract_colors("your_image.jpg")

# Print results
for color in colors:
    print(f"RGB: {color['rgb']}, Percentage: {color['percentage']:.2f}%")

Advanced Usage with GPU

from marearts_xcolor import ColorExtractor

# Enable GPU acceleration (automatically falls back to CPU if unavailable)
extractor = ColorExtractor(
    n_colors=7,
    algorithm='dbscan',
    lab_space=True,
    use_gpu='auto'
)

# Extract colors
colors = extractor.extract_colors("image.jpg")

Command Line Interface

# Basic usage
xcolor image.jpg --colors 5

# Advanced options
xcolor image.jpg --colors 8 --algorithm dbscan --fast

# Batch processing
xcolor *.jpg --output results.json --gpu auto

🌟 Key Features

📚 Examples

Extract Colors from Product Images

from marearts_xcolor import ColorExtractor
import json

extractor = ColorExtractor(n_colors=5, use_gpu='auto')

# Analyze product image
colors = extractor.extract_colors("product.jpg")

# Save results
with open('product_colors.json', 'w') as f:
    json.dump(colors, f, indent=2)

Batch Process Multiple Images

import glob
from marearts_xcolor import ColorExtractor

extractor = ColorExtractor(n_colors=5, use_gpu='auto')

# Process all images in directory
for image_path in glob.glob("images/*.jpg"):
    colors = extractor.extract_colors(image_path)
    print(f"\n{image_path}:")
    for color in colors:
        print(f"  {color['hex']} - {color['percentage']:.1f}%")

Color Similarity Analysis

from marearts_xcolor import ColorExtractor

# Extract colors from reference image
extractor_ref = ColorExtractor(n_colors=5)
reference_colors = extractor_ref.extract_colors("reference.jpg")

# Extract more colors from target image
extractor_target = ColorExtractor(n_colors=10)
target_colors = extractor_target.extract_colors("target.jpg")

# Analyze similarity
for ref_color in reference_colors:
    similar = extractor.find_similar_colors(
        ref_color['rgb'], 
        target_colors,
        threshold=10.0  # Delta-E threshold
    )
    print(f"Similar to {ref_color['hex']}: {len(similar)} colors found")

🔧 Configuration Options

Parameter	Options	Description
n_colors	int (e.g., 1-20)	Number of colors to extract
algorithm	'kmeans', 'dbscan'	Clustering algorithm
lab_space	True/False	Use LAB color space (True) or RGB (False)
use_gpu	'auto', 'force', 'never'	GPU acceleration mode
preprocessing	True/False	Enable CLAHE enhancement and bilateral filtering

💡 Tips for Best Results

• Use LAB color space for perceptually accurate colors
• Enable preprocessing for images with poor lighting
• GPU acceleration provides significant speedup for large images
• DBSCAN clustering works better for images with distinct color regions

🐛 Troubleshooting

GPU not detected?

# Check GPU availability
from marearts_xcolor.gpu_utils import get_gpu_info
print(get_gpu_info())

Installation issues?

# For CPU-only installation
pip install marearts-xcolor --no-deps
pip install numpy opencv-python scikit-learn pillow matplotlib scipy

# Verify installation
python -c "import marearts_xcolor; print(marearts_xcolor.__version__)"

Free to use on github 
https://github.com/MareArts/MareArts-Xcolor