ember-colorized/README.es.md

Ember Colorizer

English · Español

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

Instalación

uv sync

Aceleración GPU (opcional)

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

Uso

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

Licencia

LGPL-3.0