Metadata-Version: 2.4
Name: emberify
Version: 0.1.0.post1
Summary: Apply Ember color palettes to images
Author: JesusChapman
Author-email: JesusChapman <jesuschapman@openlat.dev>
License-Expression: GPL-3.0-only
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Dist: numpy>=2.2.6
Requires-Dist: pillow>=12.3.0
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: pyopencl>=2026.1.2
Requires-Dist: torch>=2.7.0 ; extra == 'gpu'
Requires-Python: >=3.10
Project-URL: Homepage, https://embertheme.com
Project-URL: Repository, https://github.com/ember-theme/emberify
Provides-Extra: gpu
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://embertheme.com/logo.svg" alt="Ember" width="80" />
</p>

<h1 align="center">Emberify</h1>

<p align="center">
  <em>Apply Ember color palettes to any image.</em>
</p>

<p align="center">
  <a href="https://github.com/ember-theme/ember">Palette & Docs</a> ·
  <a href="https://embertheme.com">embertheme.com</a>
</p>

---

## What it does

Emberify recolors images using the Ember palette — 19 carefully chosen colors spanning warm graphite, coral, gold, olive, sage, steel, rose, and mauve.

```
emberify photo.png -c ember
```

Output: `photo-ember-colorized.png`

## Install

The recommended way to install emberify is using [pipx](https://pipx.pypa.io/stable/)

```bash
pipx install emberify

# With GPU acceleration (Apple Silicon / NVIDIA):
pipx install 'emberify[gpu]'
```

## Usage

```bash
# Auto-generated output: filename-{palette}-colorized.ext
emberify photo.jpg -c ember-light

# Custom output path
emberify photo.jpg -c ember -o output.png

# Adjust recolor strength (0.0 = original, 1.0 = full)
emberify photo.jpg -c ember-light -s 0.7

# Aggressive mode with more clusters for better accuracy
emberify photo.jpg -c ember -m aggressive -k 20

# GPU acceleration (requires aggressive mode)
emberify photo.jpg -c ember -m aggressive --use-gpu
```

## 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.

**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 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.

**Supported backends** (auto-detected via pyopencl):
| 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 |

### 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

<details>
<summary>GPU acceleration (high-resolution)</summary>

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

</details>

<details>
<summary>CPU only (same image)</summary>

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

</details>

<details>
<summary>Fast mode (simple image)</summary>

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

</details>

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://github.com/ember-theme/emberify/issues/new).

## License

GPL-3.0 — JesusChapman
