Color Palette Generator

Disclaimer: This project is vibe coded. It works, but don't expect enterprise-grade code quality or extensive documentation. Use at your own risk! 🎨

A Python application that extracts dominant colors from images using three different approaches:

1. ClassicMLColorPaletteAgent: Local K-means clustering (no internet required)
2. SimpleColorPaletteAgent (OpenAI): GPT-4o via OpenAI API (direct color extraction)
3. SimpleColorPaletteAgent (OpenRouter): GPT-4o + Qwen-VL via OpenRouter API (spatial reasoning with color localization)

What It Does

The tool analyzes images and extracts 5 representative colors, displaying them in a visual format. You can see the results in two ways:

Matplotlib Visualization

The matplotlib version shows the original image with numbered circles marking where each color was found, alongside a vertical color palette with hex codes and color names at the bottom.

Web Application

The web application provides a clean, minimalistic interface where you can upload images or provide URLs. It displays the original image with color position markers and shows the extracted colors as interactive swatches with descriptive names, hex codes, and RGB values.

Features

• Three extraction modes:
  • Classic K-means clustering (offline, fast)
  • OpenAI GPT-4o (direct color extraction with descriptions)
  • OpenRouter with spatial reasoning (GPT-4o + Qwen-VL for precise color localization)
• Extracts 5 dominant colors from images
• Automatically resizes images to 1024px on the larger side for faster processing (ML agent)
• Visualizes results with matplotlib or web interface
• Color descriptions for AI-based agents
• Uses uv for package management

Installation

1. Install dependencies using uv:

uv pip install -e .

2. Create a .env file in the project root with your API keys (only needed for AI agents):

OPENAI_API_KEY=your-openai-api-key-here
OPENROUTER_API_KEY=your-openrouter-api-key-here

Note:

• For the classic agent, no API keys are needed
• For OpenAI agent, you only need OPENAI_API_KEY
• For OpenRouter agent, you need OPENROUTER_API_KEY (used for both GPT-4o and Qwen-VL)

Usage

Classic K-means (Default - No Internet Required)

uv run python agent.py images/1.jpeg

This uses local K-means clustering. No API keys needed, works completely offline.

OpenAI Agent (Direct Color Extraction)

uv run python agent.py images/1.jpeg --agent openai

Uses GPT-4o to extract colors directly. Returns colors with vivid descriptions. Requires OPENAI_API_KEY in .env.

OpenRouter Agent (Spatial Reasoning)

uv run python agent.py images/1.jpeg --agent openrouter

Uses GPT-4o for color descriptions and Qwen-VL for precise pixel localization. Shows numbered circles on the image marking where each color was found. Requires OPENROUTER_API_KEY in .env.

Web Application

uv run python app.py

Starts a Flask web server on http://localhost:5000. The web app uses the OpenRouter agent by default. You can:

• Upload images from your computer
• Provide image URLs
• View results with interactive color swatches

Command-Line Options

For agent.py:

uv run python agent.py <image_path> [options]

Options:
  --agent {classic,openai,openrouter}  Agent to use (default: classic)
  -n, --num-colors N                   Number of colors to extract (default: 5, only for classic)
  -o, --output PATH                     Path to save the visualization (optional)

Examples:

# Classic agent with 8 colors
uv run python agent.py images/1.jpeg -n 8

# OpenAI agent, save to file
uv run python agent.py images/1.jpeg --agent openai -o output.png

# OpenRouter agent
uv run python agent.py images/1.jpeg --agent openrouter

Programmatic Usage

ClassicMLColorPaletteAgent

from agent import ClassicMLColorPaletteAgent

agent = ClassicMLColorPaletteAgent(n_colors=5)
colors = agent.visualize('path/to/image.jpg')
# Returns: numpy array of RGB colors (shape: (n_colors, 3))

SimpleColorPaletteAgent

from agent import SimpleColorPaletteAgent

# Using OpenAI (default)
agent = SimpleColorPaletteAgent(use_openrouter=False)
colors, points, descriptions = agent.extract_colors('path/to/image.jpg')
# Returns: (colors, None, descriptions) where colors is list of dicts with 'hex' and 'rgb'

# Using OpenRouter (spatial reasoning)
agent = SimpleColorPaletteAgent(use_openrouter=True)
colors, points, descriptions = agent.extract_colors('path/to/image.jpg')
# Returns: (colors, points, descriptions) where points are [x, y] coordinates

# Visualize
agent.visualize('path/to/image.jpg', output_path='output.png')

Output Format

Classic Agent

• Returns numpy array of RGB values: [[R, G, B], ...]
• No color names (uses generic "Color 1", "Color 2", etc.)
• No position markers

OpenAI Agent

• Returns list of color dictionaries: [{'hex': '#FF5733', 'rgb': [255, 87, 51]}, ...]
• Includes vivid color descriptions (e.g., "glowing amber moon")
• No position markers (direct extraction)

OpenRouter Agent

• Returns list of color dictionaries with position coordinates
• Includes vivid color descriptions
• Shows numbered circles on image marking color locations

Requirements

• Python 3.8+
• scikit-learn (for ClassicMLColorPaletteAgent)
• matplotlib
• numpy
• Pillow
• openai (for SimpleColorPaletteAgent)
• python-dotenv (for loading .env file)
• flask (for web app)
• requests (for web app URL downloads)

Project Structure

colorpalette/
├── agent.py          # Color extraction agents
├── main.py           # Main CLI entry point
├── app.py            # Flask web application
├── utils.py          # Shared utility functions
├── config.py         # Configuration constants
├── templates/        # Web app templates
│   └── index.html
├── images/           # Sample images and screenshots
└── README.md         # This file

License

Vibe coded, use freely! 🎨