Dominant Color

Extract the dominant colors from an image with detailed color information and percentages.

Request Parameters

Response

Returns a JSON object containing the dominant colors in the image, along with their RGB, HSL, and hex values, approximate percentages, and color names.

Example Request

    // example.sh
curl -X POST "https://oyyi.xyz/api/image/dominant-color"   -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg" \
  -F "num_colors=3"
  

Example with Python

    // get_dominant_colors.py
import requests
import json

url = "https://oyyi.xyz/api/image/dominant-color"

files = {
    'file': open('image.jpg', 'rb')
}

data = {
    'num_colors': 3
}

response = requests.post(url, files=files, data=data)

# Parse the JSON response
colors = response.json()
print(json.dumps(colors, indent=2))
  

Example with JavaScript

    // get_dominant_colors.js
// Using fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('num_colors', '3');

fetch('https://oyyi.xyz/api/image/dominant-color', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(colors => {
  console.log(colors);
  // Display or process the dominant colors
})
.catch(error => console.error('Error:', error));
  

Example Response

    // response.json
{
  "colors": [
    {
      "hex": "#2C8ECB",
      "rgb": [44, 142, 203],
      "hsl": [204, 64, 48],
      "percentage": 32.5,
      "name": "Blue"
    },
    {
      "hex": "#F5F5F5",
      "rgb": [245, 245, 245],
      "hsl": [0, 0, 96],
      "percentage": 28.7,
      "name": "White"
    },
    {
      "hex": "#E74C3C",
      "rgb": [231, 76, 60],
      "hsl": [6, 78, 57],
      "percentage": 15.3,
      "name": "Red"
    },
    {
      "hex": "#3A3A3A",
      "rgb": [58, 58, 58],
      "hsl": [0, 0, 23],
      "percentage": 12.8,
      "name": "Dark Gray"
    },
    {
      "hex": "#27AE60",
      "rgb": [39, 174, 96],
      "hsl": [145, 63, 42],
      "percentage": 10.7,
      "name": "Green"
    }
  ],
  "background_color": "#F5F5F5",
  "foreground_color": "#2C8ECB"
}
  

Response Structure

How It Works

The dominant-color endpoint analyzes the color distribution in an image to identify the most prominent colors:

1. Image Processing: The image is loaded and optionally resized for faster processing (depending on the quality setting).
2. Color Quantization: The image's colors are quantized (reduced) to a manageable number of representative colors.
3. Clustering: Similar colors are grouped together using a clustering algorithm (typically k-means).
4. Filtering: Colors are filtered based on the provided parameters (ignore_white, ignore_black, min_saturation).
5. Sorting: The resulting color clusters are sorted by their prevalence in the image.
6. Color Naming: Each color is assigned a human-readable name based on its position in the color space.
7. Background/Foreground Detection: The algorithm attempts to identify which colors are likely to be background vs. foreground/accent colors.

The result is a comprehensive analysis of the image's color palette, which can be used for design, matching, or analysis purposes.

Quality Settings

Error Responses

Notes

• The percentages provided are approximations and may not sum exactly to 100% due to rounding and the clustering algorithm.
• Color names are approximations based on the nearest named color in a standard color database.
• For images with gradients or smooth color transitions, the dominant colors will represent the most significant color regions.
• Setting ignore_white and ignore_black to true can be useful for images with white backgrounds or black borders that would otherwise dominate the results.
• The min_saturation parameter can be used to focus on more vibrant colors by filtering out grays and desaturated colors.
• The maximum file size allowed is 20MB.
• For consistent results across multiple images, use the same quality setting and parameters for all analyses.

Use Cases

• Automatically generating color palettes from images
• Creating color schemes for websites or applications based on a brand image
• Finding complementary or matching colors for design purposes
• Analyzing product images to extract brand colors
• Categorizing or searching images based on color content
• Automatically selecting text colors that contrast well with image backgrounds
• Creating data visualizations of color distributions in image collections
• Detecting color themes in photography or artwork