Publish ember-colorized source code

README.es.md

@@ -0,0 +1,138 @@
+# 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