color-api

A sophisticated REST API for complex color calculations, conversions, and analysis using industry-standard color science algorithms.

Quick Start

pip install -r requirements.txt
python app.py

Server runs on: https://color-api-henna.vercel.app/

API Endpoints Reference

Basic Color Operations

1. Color Conversion

Endpoint: /api/color/convert
Method: POST
Description: Convert colors between different formats

{
    "color": "#FF5733",
    "from": "hex",
    "to": "rgb"
}

Supported formats: hex, rgb, hsl, lab, xyz, cmyk

2. Color Schemes

Endpoint: /api/color/scheme
Method: POST

{
    "color": "#FF5733",
    "type": "complementary"
}

Scheme types:

• complementary
• triadic
• analogous
• split-complementary

3. Color Patterns

Endpoint: /api/color/pattern
Method: POST

{
    "type": "gradient",
    "colors": ["#FF5733", "#33FF57"],
    "steps": 5
}

4. Accessibility Check

Endpoint: /api/color/accessibility
Method: POST

{
    "foreground": "#000000",
    "background": "#FFFFFF"
}

Advanced Color Operations

5. Color Temperature

Endpoint: /api/color/advanced/temperature
Method: POST

{
    "color": "#FF5733"
}

Returns: Temperature in Kelvin and warmth description

6. Color Difference

Endpoint: /api/color/advanced/difference
Method: POST

{
    "color1": "#FF5733",
    "color2": "#33FF57"
}

Returns: Delta-E value and perceptibility metrics

7. Color Appearance

Endpoint: /api/color/advanced/appearance
Method: POST

{
    "color": "#FF5733",
    "background": "#FFFFFF",
    "illuminant": "D65"
}

Supported illuminants: D65, A, F2

8. Color Interpolation

Endpoint: /api/color/advanced/interpolate
Method: POST

{
    "color1": "#FF5733",
    "color2": "#33FF57",
    "steps": 5
}

9. Color Harmony Analysis

Endpoint: /api/color/advanced/harmony
Method: POST

{
    "colors": ["#FF5733", "#33FF57", "#5733FF"]
}

10. Spectral Analysis

Endpoint: /api/color/advanced/spectral
Method: POST

{
    "color": "#FF5733"
}

11. Gamut Analysis

Endpoint: /api/color/advanced/gamut
Method: POST

{
    "colors": ["#FF5733", "#33FF57", "#5733FF"]
}

12. Color Adaptation

Endpoint: /api/color/advanced/adaptation
Method: POST

{
    "color": "#FF5733",
    "source_white": "D65",
    "target_white": "A"
}

13. Palette Optimization

Endpoint: /api/color/advanced/optimize
Method: POST

{
    "colors": ["#FF5733", "#33FF57", "#5733FF"],
    "target_contrast": 4.5
}

Example Usage

Python

import requests

BASE_URL = "https://color-api-henna.vercel.app/"

# Color conversion!
response = requests.post(f"{BASE_URL}/api/color/convert", 
    json={"color": "#FF5733", "from": "hex", "to": "rgb"})
print(response.json())

# Color analysis!
response = requests.post(f"{BASE_URL}/api/color/advanced/temperature", 
    json={"color": "#FF5733"})
print(response.json())

# Color scheme generation!
response = requests.post(f"{BASE_URL}/api/color/scheme", 
    json={"color": "#FF5733", "type": "complementary"})
print(response.json())

cURL

# Convert color!
curl -X POST "https://color-api-henna.vercel.app/api/color/convert \
  -H "Content-Type: application/json" \
  -d '{"color": "#FF5733", "from": "hex", "to": "rgb"}'

# Generate color scheme!
curl -X POST "https://color-api-henna.vercel.app/api/color/scheme \
  -H "Content-Type: application/json" \
  -d '{"color": "#FF5733", "type": "complementary"}'

Response Formats

Success Responses

// Color conversion!
{
    "result": [255, 87, 51]
}

// Color scheme!
{
    "colors": ["#FF5733", "#3357FF"]
}

// Temperature analysis!
{
    "temperature": 2535,
    "description": "warm",
    "kelvin": 2535
}

// Accessibility check!
{
    "contrast_ratio": 21.0,
    "wcag_aa_large": true,
    "wcag_aa_small": true,
    "wcag_aaa_large": true,
    "wcag_aaa_small": true
}

Error Response

{
    "error": "Error message",
    "message": "Detailed error description"
}

Error Handling

All endpoints use standard HTTP status codes:

• 200: Success
• 400: Bad Request
• 404: Not Found
• 500: Internal Server Error

Example error handling:

response = requests.post(f"{BASE_URL}/api/color/convert", 
    json={"color": "#FF5733", "from": "hex", "to": "invalid"})
if response.status_code != 200:
    print(f"Error: {response.json()['error']}")

Background Details

Color Temperature

Based on the correlation between black body radiation and perceived color, measured in Kelvin (K). The implementation uses McCamy's approximation which provides accuracy within 2% for temperatures between 2856K and 6504K.

Color Difference (Delta-E)

Implements the CIEDE2000 color difference formula, which improves upon previous Delta-E formulations by introducing:

• Different weighting factors for lightness, chroma, and hue
• Interactive term between chroma and hue differences
• Scaling factors for better agreement with visual perception

Gamut Mapping

Uses a combination of:

1. Luminance preservation
2. Constant hue lines
3. Chroma compression
4. Convex hull calculations for volume

Color Appearance Model

Simplified CIECAM02 implementation including:

1. Chromatic adaptation
2. Dynamic adaptation factors
3. Appearance correlates calculation