marearts-xcolor 0.0.7
Advanced color extraction and similarity analysis toolkit
Requires Python: >=3.9
Keywords: color extraction, color analysis, image processing, computer vision, color similarity, dominant colors, color palette, k-means clustering, LAB color space, brand colors

# MareArts XColor

A robust, modern color extraction library for extracting dominant colors from images with support for mask-based region selection, advanced preprocessing, and color similarity analysis.

## Features

✨ **Modern Algorithms**: K-means and DBSCAN clustering with LAB color space  
🔍 **Color Similarity Analysis**: Find how much specific colors appear in images  
🎭 **Mask Support**: Extract colors from specific regions using mask images  
🚀 **Fast Performance**: Optimized for speed with configurable preprocessing  
🎨 **Accurate Results**: Perceptual LAB color space for better color accuracy  
⚡ **Easy API**: Simple functions for common use cases  

## Quick Start

### Installation

```bash
pip install marearts-xcolor
```

### Basic Usage

```python
from marearts_xcolor import ColorExtractor

# Extract dominant colors
extractor = ColorExtractor(n_colors=5)
colors = extractor.extract_colors('image.jpg')

print(colors)
# Output: [{'color': (255, 128, 64), 'percentage': 35.2}, ...]

# Check version
import marearts_xcolor
print(f"Version: {marearts_xcolor.__version__}")
```

### Color Similarity Analysis

```python
# Define colors you want to find
target_colors = {
    'red': (255, 0, 0),
    'white': (255, 255, 255),
    'blue': (0, 0, 255)
}

# Find how much each color appears in the image
results = extractor.analyze_color_similarity('image.jpg', target_colors)

print(results)
# Output: {'red': {'percentage': 20.5, 'similarity': 95.0}, ...}
```

## Usage Examples

### 1. Basic Color Extraction

```python
from marearts_xcolor import ColorExtractor

# Create extractor
extractor = ColorExtractor(n_colors=5)

# From file path
colors = extractor.extract_colors('image.jpg')

# From OpenCV image
import cv2
image = cv2.imread('image.jpg')
colors = extractor.extract_colors(image)

# From PIL image
from PIL import Image
import numpy as np
pil_image = Image.open('image.jpg')
image_array = np.array(pil_image)
colors = extractor.extract_colors(image_array)
```

### 2. With Mask (Region Selection)

```python
# Extract colors only from white areas of mask
colors = extractor.extract_colors('image.jpg', 'mask.jpg')

# Create circular mask
mask = np.zeros((height, width), dtype=np.uint8)
cv2.circle(mask, (center_x, center_y), radius, 255, -1)
colors = extractor.extract_colors(image, mask)
```

### 3. Color Similarity Analysis

```python
# Brand color analysis
brand_colors = {
    'brand_blue': (0, 123, 255),
    'brand_red': (220, 53, 69),
    'brand_green': (40, 167, 69)
}

results = extractor.analyze_color_similarity('product.jpg', brand_colors)

for color_name, result in results.items():
    print(f"{color_name}: {result['percentage']:.1f}% "
          f"(similarity: {result['similarity']:.1f}%)")
```

### 4. Advanced Configuration

```python
# Robust extraction (best quality)
extractor = ColorExtractor(
    n_colors=8,
    algorithm='kmeans',
    preprocessing=True,  # Enable noise reduction
    lab_space=True       # Use LAB color space
)

# Fast extraction (best speed)
extractor = ColorExtractor(
    n_colors=3,
    algorithm='kmeans',
    preprocessing=False,  # Skip preprocessing
    lab_space=False       # Use RGB
)
```

## API Reference

### ColorExtractor Class

```python
ColorExtractor(n_colors=5, algorithm='kmeans', preprocessing=True, lab_space=True)
```

**Parameters:**
- `n_colors`: Number of dominant colors to extract (default: 5)
- `algorithm`: 'kmeans' or 'dbscan' (default: 'kmeans')
- `preprocessing`: Enable noise reduction and lighting normalization (default: True)
- `lab_space`: Use LAB color space for accuracy (default: True)

### Methods

#### `extract_colors(image, mask=None)`
Extract dominant colors from image.

**Parameters:**
- `image`: Image file path or numpy array
- `mask`: Optional mask image (white areas = extraction regions)

**Returns:** List of `{'color': (R,G,B), 'percentage': float}`

#### `analyze_color_similarity(image, target_colors, mask=None)`
Analyze how much each target color appears in the image.

**Parameters:**
- `image`: Image file path or numpy array
- `target_colors`: Dict of `{'color_name': (R,G,B)}`
- `mask`: Optional mask image

**Returns:** Dict with similarity analysis for each target color

#### `find_color_matches(image, target_colors, mask=None)`
Detailed pixel-level color matching analysis.

**Parameters:**
- `image`: Image file path or numpy array
- `target_colors`: Dict of `{'color_name': (R,G,B)}`
- `mask`: Optional mask image

**Returns:** Detailed matching results with multiple similarity thresholds

## Command Line Interface

```bash
# Basic extraction
marearts-xcolor image.jpg --colors 5

# With mask and visualization
marearts-xcolor image.jpg --mask mask.jpg --colors 8 --visualize output.png

# Fast mode
marearts-xcolor image.jpg --fast --colors 3

# Different algorithm
marearts-xcolor image.jpg --algorithm dbscan --colors 5

# Alternative command
xcolor image.jpg --colors 5
```

## Examples and Demo

### Try It Out
```python
# Quick test
from marearts_xcolor import ColorExtractor

# Create a simple test
import numpy as np
test_image = np.zeros((100, 100, 3), dtype=np.uint8)
test_image[:50, :50] = [255, 0, 0]  # Red square
test_image[:50, 50:] = [0, 255, 0]  # Green square
test_image[50:, :] = [0, 0, 255]    # Blue bottom

extractor = ColorExtractor(n_colors=3)
colors = extractor.extract_colors(test_image)
print(colors)
```

### Example Output

**Color Extraction:**
```json
[
  {"color": [255, 128, 64], "percentage": 35.2},
  {"color": [120, 200, 150], "percentage": 28.7},
  {"color": [80, 80, 80], "percentage": 20.1}
]
```

**Color Similarity Analysis:**
```json
{
  "red": {
    "percentage": 20.5,
    "similarity": 95.0,
    "closest_color": [248, 12, 8],
    "distance": 3.2,
    "found_directly": true
  },
  "white": {
    "percentage": 15.3,
    "similarity": 88.2,
    "closest_color": [245, 245, 250],
    "distance": 8.1,
    "found_directly": true
  }
}
```

## Use Cases

🛍️ **E-commerce**: Extract product colors for filtering and search  
🎨 **Design Tools**: Generate color palettes from images  
🏭 **Quality Control**: Automated color consistency checking  
📊 **Brand Analysis**: Measure brand color presence in marketing materials  
🖼️ **Art Analysis**: Extract dominant colors from artwork  
📱 **Mobile Apps**: Real-time color detection from camera  

## Technical Details

### Algorithms
- **K-means**: Fast and reliable, good for most images
- **DBSCAN**: Better for noisy data, handles outliers automatically
- **LAB Color Space**: Perceptually uniform for accurate color representation

### Preprocessing Pipeline
1. **CLAHE**: Contrast Limited Adaptive Histogram Equalization
2. **Bilateral Filter**: Noise reduction while preserving edges
3. **Color Space Conversion**: RGB → LAB for perceptual accuracy

### Color Similarity
- Uses perceptual LAB color space distances
- Multiple similarity thresholds (very close, close, somewhat close)
- Handles cases where exact colors aren't present

## Performance

- **Small images (500x500)**: ~100ms
- **Large images (2000x2000)**: ~500ms
- **Memory usage**: <100MB for any image size

## Requirements

- Python 3.9, 3.10, 3.11, 3.12
- opencv-python==4.10.0.84
- scikit-learn>=1.0.0
- numpy>=1.21.0 (numpy==1.23.5 for Python < 3.12, numpy==1.26.0 for Python >= 3.12)
- matplotlib>=3.5.0
- pillow>=8.0.0
- scipy>=1.7.0

## Files Structure

```
marearts-xcolor/
├── color_extractor.py           # Main ColorExtractor class
├── api.py                      # Simple API and CLI
├── demo.py                     # Basic demo
├── color_similarity_demo.py    # Color similarity demo
├── examples.py                 # Various input examples
├── requirements.txt            # Dependencies
├── README.md                   # This file
└── DEVELOPMENT.md             # Development guide
```

## Contributing

We welcome contributions! Please see our development guide for details on:
- Setting up the development environment
- Running tests
- Submitting pull requests

## Repository

- GitHub: [https://github.com/marearts/marearts-xcolor](https://github.com/marearts/marearts-xcolor)
- PyPI: [https://pypi.org/project/marearts-xcolor](https://pypi.org/project/marearts-xcolor)

## License

MIT License - Feel free to use in commercial and personal projects.