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
-
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). -
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-oigual al archivo de entrada a menos que se use--in-place. -
Elimina el fondo:
ia remove in.jpg -o out.png. El color de fondo es la mediana del borde (--bg 255,255,255para 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. -
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,60Lee
check.jpg. Revisa también sobre un fondo oscuro. Busca halos, escalones, agujeros en detalles claros, blanco sobrante. -
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.
-
Extras opcionales: motas sobrantes (abajo), recoloreado (abajo).
-
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.pyocultó 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