138 lines
4.4 KiB
Markdown
138 lines
4.4 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
- 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](https://openlat.dev/JesusChapman/ember-colorized/issues/new).
|
||
|
||
## License
|
||
|
||
LGPL-3.0
|