Ember Colorizer

English · Español

Apply Ember color palettes to images with high precision.

Installation

uv sync

GPU acceleration (optional)

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

Usage

# 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

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):

Performance (5304×7952 image, 12 clusters):

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

Showcase

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

• Same image recoloring using CPU only

• Simple image recoloring using fast mode

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.

License

LGPL-3.0