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

🎨 Color Extraction

• Multiple Algorithms: K-means and DBSCAN clustering
• Color Spaces: RGB and LAB support
• Smart Preprocessing: CLAHE enhancement and bilateral filtering
• Accurate Results: Perceptually uniform color extraction

⚡ Performance

• GPU Acceleration: Optional CUDA support for 10-50x speedup
• Optimized Implementation: Cython-compiled with C++ backend
• Smart Fallback: Automatic CPU fallback when GPU unavailable
• Batch Processing: Efficient processing of multiple images

🛠️ Flexibility

• Pure Python API: Easy integration with existing projects
• Mask Support: Extract colors from specific regions
• Color Similarity: Find similar colors using perceptual metrics
• Export Options: JSON, CSV, and image outputs

📚 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")

🏗️ Repository Structure

marearts-xcolor/
├── examples/           # Complete code examples
│   ├── README.md                # Examples documentation
│   ├── basic_usage.py           # Simple color extraction
│   ├── gpu_usage.py             # GPU acceleration examples
│   ├── advanced_usage.py        # Advanced features
│   ├── integration_examples.py  # Integration with other libraries
│   ├── webcam_color_extractor.py # Real-time webcam demo
│   ├── advanced_webcam_demo.py  # Webcam demo with video recording
│   └── cli_usage.sh             # Command-line examples
└── sample_images/      # Test images
    ├── sample_image.jpg
    ├── product_example.jpg
    ├── color_test_image.jpg
    └── sample_mask.jpg

🔧 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

1. Use LAB color space for perceptually accurate colors
2. Enable preprocessing for images with poor lighting
3. GPU acceleration provides significant speedup for large images
4. 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__)"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

• PyPI Package
• GitHub Repository
• MareArts Homepage
• Live Test

MareArts Solutions

• Autpmatic Number Plate Recognition
• MareArts Reatime Video & Image Stiching
• MareArts Dominent Color Extraction

📞 Support

For questions or support:

• Email: hello@marearts.com

---

Made with ❤️ by MareArts