README.md

---
title: AI Image Editor - Palette Swapper
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.4.0
app_file: app.py
pinned: false
---

# AI Image Editor - Palette Swapper

Upload an image, extract its color palette, then swap colors using color theory harmonies with AI-enhanced recoloring.

## Features

- **Color Palette Extraction**: K-means clustering extracts dominant colors with proportions
- **Intelligent Palette Transform**: Preserves tonal relationships (light/dark, saturated/muted)
- **Color Harmonies**: Complementary, Analogous, Triadic, Split-Complementary, Tetradic, Monochromatic
- **AI-Enhanced Recoloring**: InstructPix2Pix uses your K-means palette as context to recolor naturally
- **Reference Image**: Extract palette from another image to apply
- **Custom Mapping**: Dropdown controls to map source colors to target colors

## How It Works

1. **Upload** an image to extract its color palette (K-means clustering)
2. **Pick a base color** - this becomes the new dominant color
3. **Choose a harmony type** - determines how other colors branch from the base
4. **Generate** the target palette (preserves tonal relationships from source)
5. **Apply** the palette swap:
   - **Basic mode**: Pixel-level color replacement based on K-means distance
   - **AI mode**: InstructPix2Pix uses your palette mapping as context to recolor while preserving lighting, textures, and natural transitions

## The Hybrid Architecture

Your K-means algorithm provides the "what" and "where":
- Identifies dominant color clusters
- Generates masks for each color region

The AI provides intelligent application:
- Understands scene context (sky vs. shirt vs. car)
- Preserves shadows, highlights, and textures
- Creates natural color transitions

## Tech Stack

- **Gradio**: Web interface
- **InstructPix2Pix**: AI-enhanced recoloring (via diffusers)
- **scikit-learn**: K-means clustering for palette extraction
- **Pillow**: Image processing
- **colorsys**: HSV color space transformations