ember-colorized/README.md

# Ember Colorizer

[English](README.md) · [Español](README.es.md)

Apply Ember color palettes to images with high precision.

## Installation

```bash
uv sync
```

### GPU acceleration (optional)

```bash
# Apple Silicon (MPS) or NVIDIA (CUDA)
pip install 'ember-colorized[gpu]'
```

## Usage

```bash
# Auto-generated output: filename-{palette}-colorized.ext
ember-colorizer --colors=ember-light /path/to/image.png

# Custom output path
ember-colorizer --colors=ember -o /path/to/output.png /path/to/image.jpg

# Fast mode (direct RGB mapping, no K-means)
ember-colorizer --colors=ember-soft -m fast /path/to/image.png

# Adjust recolor strength (0.0 = original, 1.0 = full)
ember-colorizer --colors=ember-light -s 0.7 /path/to/image.png

# More clusters for better accuracy (aggressive mode)
ember-colorizer --colors=ember -k 20 /path/to/image.png

# Use GPU acceleration (aggressive mode only)
ember-colorizer --colors=ember --use-gpu /path/to/image.png
```

## Palettes

| Palette | Background | Type |
|---------|-----------|------|
| `ember` | `#1c1b19` | dark |
| `ember-soft` | `#242320` | dark |
| `ember-light` | `#e6dac4` | light |
| `ember-lighter` | `#e8e4de` | light |

## Modes

### Aggressive mode (`-m aggressive`)

Uses **K-means clustering** to analyze the image before recoloring.

**What is K-means?** It's an algorithm that groups similar colors together. Imagine throwing 12 darts at a color wheel — each dart moves to the "center of gravity" of the colors closest to it. After several rounds, the darts settle on the most representative colors in the image.

**How it works:**
1. K-means finds the 12 dominant colors in your image (configurable with `-k`)
2. Each dominant color is mapped to its nearest Ember palette color (RGB Euclidean distance)
3. Every pixel is reassigned to its cluster's mapped palette color
4. Strength controls the blend between original and recolored

**Result:** Colors group naturally — sky areas stay coherent, skin tones stay unified. Best for photos and complex images.

### Fast mode (`-m fast`)

**Direct pixel-by-pixel RGB nearest-color mapping** — no clustering, no filters. Each pixel independently maps to the closest Ember palette color using Euclidean distance in RGB space.

**How it works:**
1. For each pixel, compute Euclidean distance to all palette colors in RGB space
2. Replace the pixel with the nearest palette color

**Result:** Maximum detail preservation — edges, gradients, fine lines (anime hair, outlines) stay sharp. Best for anime, illustrations, line art, or when speed matters.

### GPU acceleration (`--use-gpu`)

When `--use-gpu` is passed, K-means clustering runs on the GPU with smart downsampling — clusters on a 200K-pixel subset, then assigns all pixels vectorized. This greatly accelerates the recoloring time for complex, high-resolution images.

**Supported backends** (auto-detected):
| Backend | Hardware | Package |
|---------|----------|---------|
| cuML | NVIDIA GPU | `cuml-cu12` |
| PyTorch MPS | Apple Silicon | `torch` |
| PyTorch CUDA | NVIDIA GPU | `torch` |
| sklearn | CPU fallback | (always available) |

**Performance** (5304×7952 image, 12 clusters):
| Backend | Time |
|---------|------|
| CPU (sklearn) | ~127s |
| GPU (Apple MPS) | ~8s |

**Output example:**
```
Input:    photo.png
Palette:  ember (Ember)
Mode:     aggressive
Strength: 1.0
GPU:      yes (Apple (arm64))
Output:   photo-ember-colorized.png
  ⠹ Clustering colors...
Success! in 7.818s
```

### Key differences

| | Aggressive | Fast |
|---|---|---|
| Algorithm | K-means → cluster mapping | Direct RGB nearest-color |
| Speed | Slower (clustering pass) | Fastest (vectorized) |
| Accuracy | Higher (cluster coherence) | Good (per-pixel) |
| Best for | Photos, complex scenes | Anime, illustrations, line art |
| Control | `-k` clusters, `-s` strength | `-s` strength only |
| GPU | `--use-gpu` supported | CPU only |

## Showcase

- High-resolution image recoloring using GPU --use-gpu

![gpu_yes](./showcase/use_gpu.png)

- Same image recoloring using CPU only

![gpu_no](./showcase/use_cpu.png)

- Simple image recoloring using fast mode

![fast_mode](./showcase/fast_mode.png)

As you can see, when processing a high-resolution image, GPU mode significantly accelerates the process.

This feature has been tested on Apple Silicon GPUs; it should also work on NVIDIA. If you encounter any issues with your GPU, feel free to open an [issue](https://openlat.dev/JesusChapman/ember-colorized/issues/new).

## License

LGPL-3.0