138 lines
4.7 KiB
Markdown
138 lines
4.7 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
- Recoloreado de la misma imágen usando solo CPU
|
||
|
||
|
||
|
||
- Recoloreado de una imágen simple usando el modo fast
|
||
|
||
|
||
|
||
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
|