Readme

Color Extraction API

Advanced color extraction API that identifies dominant colors from images using multiple extraction methods. Perfect for designers, developers, and artists who need precise color analysis.

Features

5 Extraction Methods:
kmeans - K-means clustering (most versatile)
dominant - ColorThief library (fast and accurate)
median_cut - PIL’s median cut algorithm
adaptive - Area-aware extraction with minimum coverage filtering
histogram - Frequency-based color analysis
Multiple Output Formats:
json - Complete color data with RGB, hex, HSL, dominance, and names
hex_array - Simple array of hex color codes
rgb_array - Simple array of RGB values
palette_image - Generated color palette image
Smart Color Analysis:
Color name recognition (CSS3 standard + approximations)
Sorting by dominance, brightness, hue, or saturation
Quality control (1-10 scale for speed vs accuracy)
Area filtering to exclude tiny color spots

API Parameters

Parameter	Type	Default	Description
`image`	File	Required	Image to analyze (PNG, JPG, JPEG, GIF, BMP, WebP, AVIF, SVG)
`method`	String	`kmeans`	Extraction method (`kmeans`, `dominant`, `median_cut`, `adaptive`, `histogram`)
`num_colors`	Integer	`6`	Number of colors to extract (2-20)
`quality`	Integer	`5`	Quality level (1=fastest, 10=highest quality)
`output_format`	String	`json`	Output format (`json`, `hex_array`, `rgb_array`, `palette_image`)
`include_names`	Boolean	`true`	Include human-readable color names
`sort_by`	String	`dominance`	Sort colors by (`dominance`, `brightness`, `hue`, `saturation`, `none`)
`min_area_percent`	Float	`1.0`	Minimum area percentage for color inclusion (0.1-10.0)

Usage Examples

Python

import replicate

output = replicate.run(
    "merahburam/color-extraction",
    input={
        "image": open("your_image.jpg", "rb"),
        "method": "kmeans",
        "num_colors": 6,
        "output_format": "json"
    }
)

print(f"Dominant color: {output['dominant_color']['hex']}")
for color in output['colors']:
    print(f"{color['hex']} - {color['name']} ({color['dominance']:.1f}%)")

cURL

curl -X POST \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg",
      "method": "kmeans",
      "num_colors": 6
    }
  }' \
  https://api.replicate.com/v1/predictions

Node.js

import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.REPLICATE_API_TOKEN,
});

const output = await replicate.run(
  "merahburam/color-extraction",
  {
    input: {
      image: fs.createReadStream("image.jpg"),
      method: "kmeans",
      num_colors: 6,
      output_format: "json"
    }
  }
);

console.log("Dominant color:", output.dominant_color.hex);

Sample Output

JSON Format

{
  "colors": [
    {
      "rgb": [50, 50, 50],
      "hex": "#323232",
      "hsl": [0, 0, 19],
      "dominance": 76.11,
      "name": "gray",
      "name_similarity": 70.0,
      "method": "kmeans"
    }
  ],
  "dominant_color": {
    "rgb": [50, 50, 50],
    "hex": "#323232",
    "hsl": [0, 0, 19],
    "dominance": 76.11,
    "name": "gray",
    "name_similarity": 70.0,
    "method": "kmeans"
  },
  "total_colors": 6,
  "image_info": {
    "width": 2000,
    "height": 2000,
    "mode": "RGBA",
    "format": "PNG"
  }
}

Hex Array Format

{
  "hex_colors": ["#323232", "#F6F1E9", "#F1BA42", "#D7CDB8"],
  "total_colors": 4
}

Use Cases

Design Tools: Extract color palettes for design inspiration
E-commerce: Automatic product color tagging
Art Analysis: Analyze artwork color compositions
Brand Analysis: Extract brand colors from logos
Image Processing: Preprocess images for further analysis
Web Development: Generate CSS color variables
Marketing: Analyze visual content color trends

Method Comparison

Method	Speed	Accuracy	Best For
`kmeans`	Medium	High	General purpose, versatile
`dominant`	Fast	High	Quick results, web images
`median_cut`	Fast	Medium	Simple images, quick processing
`adaptive`	Medium	High	Complex images with small details
`histogram`	Fast	Medium	High contrast images

Performance Tips

Use quality=3 for fast processing of large images
Use quality=8-10 for precise color analysis
adaptive method works best for images with many small color areas
dominant method is fastest for simple color extraction
Set min_area_percent=2.0 to filter out noise in complex images

Local Development

# Clone and setup
git clone <your-repo>
cd color-extraction

# Install dependencies
pip install -r requirements.txt

# Test locally
cog predict -i image=@test.jpg -i method=kmeans

# Deploy to Replicate
cog push r8.im/merahburam/color-extraction

License

Open source - feel free to use and modify for your projects!

Built with: Python, OpenCV, scikit-learn, ColorThief, Pillow
Powered by: Replicate platform
Created by: @merahburam

Run time and cost