ember-colorized/README.es.md

# Ember Colorizer

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

Aplica paletas de colores Ember a imágenes con alta precisión.

## Instalación

```bash
uv sync
```

### Aceleración GPU (opcional)

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

## Uso

```bash
# Nombre de salida automático: filename-{palette}-colorized.ext
ember-colorizer --colors=ember-light /ruta/imagen.png

# Ruta de salida personalizada
ember-colorizer --colors=ember -o /ruta/salida.png /ruta/imagen.jpg

# Modo rápido (mapeo directo RGB, sin K-means)
ember-colorizer --colors=ember-soft -m fast /ruta/imagen.png

# Ajustar fuerza de recolor (0.0 = original, 1.0 = completo)
ember-colorizer --colors=ember-light -s 0.7 /ruta/imagen.png

# Más clusters para mayor precisión (modo aggressive)
ember-colorizer --colors=ember -k 20 /ruta/imagen.png

# Usar aceleración GPU (solo modo aggressive)
ember-colorizer --colors=ember --use-gpu /ruta/imagen.png
```

## Paletas

| Paleta | Fondo | Tipo |
|--------|-------|------|
| `ember` | `#1c1b19` | oscuro |
| `ember-soft` | `#242320` | oscuro |
| `ember-light` | `#e6dac4` | claro |
| `ember-lighter` | `#e8e4de` | claro |

## Modos

### Modo aggressive (`-m aggressive`)

Usa **clustering K-means** para analizar la imagen antes de recolorear.

**¿Qué es K-means?** Es un algoritmo que agrupa colores similares. Imagina lanzar 12 dardos a un círculo de colores — cada dardo se mueve hacia el "centro de gravedad" de los colores más cercanos. Tras varias rondas, los dardos se asientan en los colores más representativos de la imagen.

**Cómo funciona:**
1. K-means encuentra los 12 colores dominantes de tu imagen (configurable con `-k`)
2. Cada color dominante se mapea al color Ember más cercano (distancia Euclídea RGB)
3. Cada pixel se reasigna al color de paleta de su cluster
4. La fuerza controla la mezcla entre original y recoloreado

**Resultado:** Los colores se agrupan naturalmente — el cielo mantiene coherencia, los tonos de piel se unifican. Ideal para fotos e imágenes complejas.

### Modo fast (`-m fast`)

**Mapeo directo pixel por pixel RGB** — sin clustering, sin filtros. Cada pixel se mapea independientemente al color Ember más cercano usando distancia Euclídea en espacio RGB.

**Cómo funciona:**
1. Para cada pixel, calcula la distancia Euclídea a todos los colores de la paleta en espacio RGB
2. Reemplaza el pixel con el color de paleta más cercano

**Resultado:** Preservación máxima del detalle — bordes, gradientes, líneas finas (cabello de anime, contornos) se mantienen nítidos. Ideal para anime, ilustraciones, arte con líneas, o cuando importa la velocidad.

### Aceleración GPU (`--use-gpu`)

Cuando se pasa `--use-gpu`, el clustering K-means se ejecuta en la GPU con downsample inteligente — clusteriza en un subconjunto de 200K pixeles, luego asigna todos los pixeles vectorizadamente. Esto acelera enormemente el tiempo de recoloreado de una imágen, ideal para procesar imágenes complejas y con altas resoluciónes

**Backends soportados** (auto-detectados):
| Backend | Hardware | Paquete |
|---------|----------|---------|
| cuML | NVIDIA GPU | `cuml-cu12` |
| PyTorch MPS | Apple Silicon | `torch` |
| PyTorch CUDA | NVIDIA GPU | `torch` |
| sklearn | CPU (fallback) | (siempre disponible) |

**Rendimiento** (imagen 5304×7952, 12 clusters):
| Backend | Tiempo |
|---------|--------|
| CPU (sklearn) | ~127s |
| GPU (Apple MPS) | ~8s |

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

### Diferencias clave

| | Aggressive | Fast |
|---|---|---|
| Algoritmo | K-means → mapeo por cluster | RGB nearest-color directo |
| Velocidad | Más lento (paso de clustering) | Más rápido (vectorizado) |
| Precisión | Mayor (coherencia de cluster) | Buena (por pixel) |
| Ideal para | Fotos, escenas complejas | Anime, ilustraciones, líneas |
| Control | `-k` clusters, `-s` fuerza | `-s` fuerza únicamente |
| GPU | `--use-gpu` soportado | Solo CPU |

## Showcase

- Recoloreado de una imágen de alta resolución usando GPU --use-gpu

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

- Recoloreado de la misma imágen usando solo CPU

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

- Recoloreado de una imágen simple usando el modo fast

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

Como puedes observar, al procesar una imágen de alta reslución y peso, el modo GPU acelera el proceso enormemente.

De momento esta característica ha sido probada en GPUs de Apple Silicon, debería funcionar también en NVIDIA, si encuentras un problema con tu GPU, no dudes en abrir una [incidencia.](https://openlat.dev/JesusChapman/ember-colorized/issues/new)

## Licencia

LGPL-3.0