CommunityImagengithub.com

transparent-background

Convierte una imagen con fondo plano o casi plano (ilustración, pegatina, logo, escaneo, foto de producto sobre blanco) en un PNG limpio con transparencia, corrige halos blancos, bordes dentados y píxeles sobrantes, y opcionalmente recolorea formas separadas.

¿Qué es transparent-background?

Esta habilidad para agentes de IA (compatible con Claude Code, Cursor y otros) permite eliminar fondos planos o casi planos de imágenes como ilustraciones, logos, stickers, escaneos y fotos de producto sobre blanco, y convertirlos en PNG con transparencia limpia. Además de la eliminación del fondo, ofrece herramientas para corregir halos blancos, bordes dentados y píxeles sobrantes entre mechones de cabello o contornos oscuros. También incluye funcionalidades avanzadas como la inspección del resultado sobre fondos de contraste y el recoloreado de formas separadas (marcas, texto, iconos) usando colores dados o muestreados de una imagen de referencia, preservando la textura original del pincel o crayón. El script se ejecuta mediante uv sin instalaciones globales en macOS, Linux o Windows, y sigue un flujo de trabajo paso a paso: inspeccionar la imagen original, eliminar el fondo, revisar sobre un color contrastante, corregir problemas uno a uno y opcionalmente aplicar extras como eliminación de motas o recoloreado. Es importante no modificar la imagen original y siempre hacer copias de seguridad antes de editar resultados.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shino369/kyoten-skills/tree/HEAD/skills/transparent-background

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Fondo Transparente

Un único script, scripts/imgalpha.py, hace el trabajo. Ejecútalo a través de uv (sin instalaciones globales) en macOS, Linux o Windows. Define el helper ia una vez por shell, desde dentro del repositorio. Este resuelve una ruta absoluta, por lo que un cd posterior no afecta. Los ejemplos a continuación lo usan.

bash / zsh / Git Bash:

IA_PY="$(git rev-parse --show-toplevel)/.agents/skills/transparent-background/scripts/imgalpha.py"
ia() { uv run --quiet --python 3.12 --with pillow --with numpy --with scipy python -I "$IA_PY" "$@"; }
ia remove in.jpg -o out.png

PowerShell (cmd.exe no tiene funciones, así que usa PowerShell o Git Bash):

$IA_PY = Join-Path (git rev-parse --show-toplevel) '.agents/skills/transparent-background/scripts/imgalpha.py'
function ia { uv run --quiet --python 3.12 --with pillow --with numpy --with scipy python -I $IA_PY @args }
ia remove in.jpg -o out.png

Escribe los colores como r,g,b (--bg 40,96,200). No necesita comillas en ningún shell. #rrggbb también funciona, pero ponlo entre comillas: PowerShell trata un # desnudo como un comentario, y cmd mantiene las comillas simples.

Flujo de trabajo

  1. Inspecciona primero. Lee la imagen. Este script es adecuado para fondos planos o casi planos. Para fotos o fondos con mucho detalle usa en su lugar un modelo de recorte por IA (rembg, consulta references/troubleshooting.md).

  2. Nunca toques el original. Escribe en un archivo nuevo. Antes de editar un resultado sobre el original, cópialo a una carpeta backup/<aammdd-hhmm>/ junto a él. El script rechaza -o igual al archivo de entrada a menos que se use --in-place.

  3. Elimina el fondo: ia remove in.jpg -o out.png. El color de fondo es la mediana del borde (--bg 255,255,255 para forzarlo). Elimina el fondo conectado a los bordes más los huecos encerrados del tono del fondo que no tienen agujero, por lo que la piel, las rayas blancas y los detalles en forma de anillo se conservan.

  4. Inspecciona sobre un color contrastante, con zoom. La transparencia oculta problemas sobre blanco:

    ia preview out.png -o check.jpg --bg 40,96,200 --crop 600,140 --crop 260,1140,60
    

    Lee check.jpg. Revisa también sobre un fondo oscuro. Busca halos, escalones, agujeros en detalles claros, blanco sobrante.

  5. Corrige lo que veas, un problema a la vez, volviendo a inspeccionar después de cada uno. Síntoma → tabla de soluciones: references/troubleshooting.md.

  6. Extras opcionales: motas sobrantes (abajo), recoloreado (abajo).

  7. Informa la ruta de salida, qué cambió, qué se mantuvo deliberadamente y la ubicación de la copia de seguridad.

Píxeles de fondo sobrantes (specks)

Finas tiras blancas entre mechones de cabello o dentro de contornos oscuros. Siempre márcalas antes de rellenar:

ia specks out.png --mark marked.jpg          # rodea cada candidato; imprime la cuenta
ia specks out.png -o fixed.png --keep 1237,1467   # rellena; protege un destello intencionado

Lee marked.jpg y revisa cada círculo. Si uno está sobre arte real (encaje, brillo de ojo, destello), usa --keep x,y o un --region x0,y0,x1,y1. Luego compara antes y después con preview --crop. Los valores por defecto están ajustados para áreas oscuras y neutras (pelo negro, contornos). Para áreas de color aumenta --surround-max-sat.

Recolorear formas (components, recolor)

ia components out.png                    # id, bbox, tamaño, color medio de cada forma
ia recolor out.png -o red.png --at 200,640 --at 1400,500 --like other.png --like-at 1350,880
ia recolor out.png -o red.png --ids 2,3 --color 228,100,91

--like muestrea el color y la textura de la forma en --like-at de una imagen de referencia. Cada píxel mantiene su desviación de claro/oscuro, por lo que la textura del pincel o crayón sobrevive. Elige formas con --at (un punto dentro de ellas). Es más seguro que los ids, que cambian cuando la imagen cambia.

Reglas

  • Inspecciona el resultado tú mismo (lee la imagen de previsualización) después de cada paso. No asumas que los valores por defecto funcionaron.
  • Pasa las rutas como argumentos y ejecuta Python con -I. Nunca nombres un archivo temporal como un módulo de la stdlib (inspect.py ocultó la importación de numpy una vez).
  • Mantén la salida temporal en la carpeta tmp/ de la tarea o en la carpeta temporal del sistema, no junto a las imágenes del usuario.

Pruebas

Al desarrollar dentro del repositorio de la habilidad, ejecuta la suite de pruebas de Python con cobertura del 100% de ramas:

uv run --quiet --python 3.12 --with pytest --with pytest-cov --with pillow --with numpy --with scipy python -I -B -m pytest -q -p no:cacheprovider skills/transparent-background/scripts --cov=imgalpha --cov-branch --cov-fail-under=100

Skills relacionados