Communitygithub.com

OpenGHz/rembg-bg-removal

Habilidad de agente: elimina fondos de imágenes con rembg en un entorno aislado y con CUDA compatible — recortes PNG transparentes para una imagen o una carpeta completa.

¿Qué es rembg-bg-removal?

Esta habilidad para agentes de IA proporciona una solución robusta y empaquetada para la eliminación de fondos de imágenes utilizando la biblioteca rembg, eliminando la complejidad de configurar un entorno de trabajo con soporte GPU. La habilidad automatiza la creación de un entorno aislado (conda o venv), la instalación de onnxruntime-gpu con la versión de CUDA correcta para evitar conflictos de bibliotecas compartidas (como `libcudart.so`), y la descarga de modelos de segmentación con reintentos y verificación MD5. Soporta tanto archivos individuales como carpetas enteras, generando automáticamente archivos PNG con fondo transparente. Incluye envoltorios de script para configurar el entorno una sola vez y ejecutar la eliminación de fondos de forma sencilla, con opciones para seleccionar el modelo (por defecto birefnet-general) y ajustar la calidad mediante parámetros como `-ppm` o `-a` (alpha matting). Está diseñada para agentes como Claude Code y Cursor, y su documentación detallada cubre desde la instalación inicial hasta la resolución de problemas comunes.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add OpenGHz/rembg-bg-removal

Preguntar en tu IA favorita

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

Documentación

Eliminación de fondos con rembg

Elimina fondos de imágenes usando rembg. La parte difícil no es la eliminación en sí, sino conseguir un entorno aislado y funcional con un backend GPU que coincida con la versión de CUDA de la máquina. Esta habilidad empaqueta esa configuración para que sea un script de una sola vez, y luego un envoltorio de ejecución ligero.

Flujo de trabajo

  1. Verificar que el entorno existe. Compruébalo antes de ejecutar cualquier cosa:

    # conda (por defecto cuando está presente):
    conda env list | grep -q '\brembg\b' && echo EXISTE
    # fallback venv:
    test -x ~/.venvs/rembg/bin/rembg && echo EXISTE
    

    Si no existe, ejecuta el script de configuración (ver más abajo). Si existe, salta directamente a la ejecución.

  2. Ejecutar la eliminación de fondo mediante el envoltorio (detecta automáticamente archivo vs carpeta):

    bash <skill>/scripts/run_rembg.sh <entrada> <salida> [-m MODELO] [banderas]
    
  3. Informar dónde se guardaron las salidas y qué modelo se usó. Si al usuario le importa la calidad, dirígelo a las opciones de ajuste.

Configuración (solo la primera vez)

Ejecuta el instalador incluido. Crea un entorno dedicado e instala solo allí — nunca modifica el entorno activo o base del usuario.

bash <skill>/scripts/setup_env.sh

Qué hace y por qué:

  • Aislamiento. Crea un entorno conda dedicado llamado rembg (o un venv en ~/.venvs/rembg si conda no está disponible). Calcula una ruta explícita del intérprete e instala con <ese-python> -m pip, para que nada caiga en el entorno que esté activo.
  • Backend coincidente con CUDA. Lee la versión de CUDA del driver desde nvidia-smi. Para CUDA 12.x instala onnxruntime-gpu==1.22.0 más las ruedas coincidentes nvidia-cudnn-cu12 / cublas / cuda-runtime. Esto importa: la última versión de onnxruntime-gpu (1.23+) está compilada para CUDA 13 y falla al importar en una máquina con CUDA 12 con libcudart.so.13: cannot open shared object file. Para CUDA ≥13 usa la compilación GPU más reciente; sin GPU usa la compilación CPU.
  • Ruta de carga. onnxruntime-gpu necesita las bibliotecas pip de NVIDIA en LD_LIBRARY_PATH. El instalador añade un hook de conda activate.d, y el envoltorio de ejecución también lo establece (para que venv funcione), así el usuario nunca tiene que exportar nada.
  • Precarga de modelos. Descarga birefnet-general (~928MB) y u2net con wget -c reanudable + verificación md5, porque los enlaces de los releases de GitHub suelen fallar a mitad de descarga.

Variables de entorno útiles: ENV_TYPE=venv, ENV_PATH=~/.venvs/rembg, FORCE_CPU=1, PROXY=http://127.0.0.1:7890 (enruta descargas a través de un proxy; vacío por defecto), RECREATE=1 (reconstruir desde cero), MODELS="birefnet-general isnet-anime".

Ejecución

El envoltorio maneja archivos individuales y carpetas de forma idéntica: pasa un archivo para obtener un archivo, un directorio para obtener un directorio de recortes. La ruta de salida es opcional: omítela y el envoltorio escribe junto a la entrada con un sufijo _rembg (foto.jpg → foto_rembg.png, iconos/ → iconos_rembg/), así no es necesario inventar una.

# imagen única, salida automática -> foto_rembg.png
bash <skill>/scripts/run_rembg.sh foto.jpg

# salida explícita
bash <skill>/scripts/run_rembg.sh foto.jpg foto_recorte.png

# carpeta completa, salida automática -> iconos_rembg/
bash <skill>/scripts/run_rembg.sh ./iconos -m birefnet-general -ppm

# elegir un modelo / pasar banderas de rembg (las banderas pueden seguir directamente a la entrada)
MODEL=isnet-anime bash <skill>/scripts/run_rembg.sh personaje.png -ppm

El envoltorio desactiva primero cualquier proxy socks:// (esto rompe la importación de gradio de rembg). No usa proxy por defecto; establece PROXY para enrutar las descargas bajo demanda de modelos a través de un proxy http.

Elección de modelo y ajuste de calidad

El predeterminado es birefnet-general (mejores bordes generales). Si el usuario no está satisfecho con los bordes, menciona pelo/bordes suaves, anime o retratos, o quiere un fondo de color sólido, lee references/models_and_flags.md para la tabla completa de modelos y el orden de ajuste de banderas (empieza con -ppm, luego un modelo más fuerte, luego -a alpha matting con ajuste -ae de erosión).

Solución de problemas

  • No onnxruntime backend found — la rueda GPU falló al importar (generalmente un desajuste mayor de versión CUDA). Vuelve a ejecutar setup_env.sh; selecciona el backend coincidente.
  • libcudart.so.13: cannot open shared object file — onnxruntime-gpu está compilado para CUDA 13 pero la máquina tiene CUDA 12. Esto es exactamente lo que el pin de versión en setup_env.sh corrige.
  • Unknown scheme for proxy URL 'socks://...' — un socks:// all_proxy rompe gradio/httpx. El envoltorio de ejecución lo desactiva; si ejecutas rembg manualmente, haz unset all_proxy ALL_PROXY primero.
  • The CLI dependencies are not installed — rembg se instaló sin el extra [cli]. setup_env.sh instala rembg[cpu,cli]; vuelve a ejecutarlo.
  • La descarga del modelo se detiene / SSL EOF — establece un PROXY funcional, o precarga con wget -c en ~/.u2net/<nombre>.onnx (el instalador hace esto).

Skills relacionados