CommunityImagemgithub.com

transparent-background

Transforme uma imagem com fundo liso ou quase liso (ilustração, adesivo, logotipo, digitalização, foto de produto sobre branco) em um PNG transparente limpo, corrija halos brancos, bordas serrilhadas e pixels de fundo remanescentes e, opcionalmente, recoloque formas separadas (marcas, textos, ícones) com uma cor fornecida ou amostrada.

O que é transparent-background?

Esta skill remove o fundo de imagens com fundo liso ou quase liso, como ilustrações, adesivos, logotipos, digitalizações e fotos de produto sobre branco, produzindo um PNG com transparência limpa. Ela também corrige artefatos comuns como halos brancos, bordas serrilhadas e pixels de fundo remanescentes (por exemplo, entre fios de cabelo ou dentro de contornos escuros). Além disso, oferece a capacidade de recolorir formas separadas (marcas, textos, ícones) amostrando a cor de uma imagem de referência ou fornecendo uma cor específica. A skill é executada através do `uv` (sem instalação global) nos sistemas macOS, Linux e Windows, utilizando um único script Python (`scripts/imgalpha.py`) com dependências Pillow, NumPy e SciPy. O fluxo de trabalho inclui inspeção visual em fundos contrastantes e uma tabela de sintomas → correções para agilizar o processo.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Fundo Transparente

Um único script, scripts/imgalpha.py, faz o trabalho. Execute-o via uv (sem instalações globais) no macOS, Linux ou Windows. Defina o helper ia uma vez por shell command, dentro do repositório. Ele resolve um caminho absoluto, então um cd posterior funciona. Os exemplos abaixo usam isso.

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 (o cmd.exe não possui funções, então use PowerShell ou 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

Escreva cores como r,g,b (--bg 40,96,200). Isso não precisa de aspas em nenhum shell. #rrggbb também funciona, mas coloque entre aspas: o PowerShell trata um # simples como comentário, e o cmd mantém aspas simples.

Fluxo de Trabalho

  1. Olhe primeiro. Leia a imagem. Este script é adequado para fundos lisos ou quase lisos. Para fotos ou fundos complexos, use um modelo de matting de IA (rembg, veja references/troubleshooting.md).

  2. Nunca toque no original. Escreva em um novo arquivo. Antes de editar um resultado no lugar, copie-o para uma pasta backup/<yymmdd-hhmm>/ ao lado dele. O script recusa -o = entrada a menos que --in-place.

  3. Remova o fundo: ia remove in.jpg -o out.png. A cor do fundo é a mediana da borda (--bg 255,255,255 para forçar). Remove o fundo conectado às bordas mais lacunas fechadas do matiz do fundo que não têm buraco, então pele, listras brancas e detalhes em forma de anel permanecem.

  4. Inspecione em uma cor contrastante, com zoom. A transparência esconde problemas no branco:

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

    Leia check.jpg. Verifique também em um fundo escuro. Procure por halos, serrilhados, buracos em detalhes claros, branco residual.

  5. Corrija o que você vê, um problema de cada vez, reinspecionando após cada um. Tabela de sintoma → correção: references/troubleshooting.md.

  6. Extras opcionais: resíduos (abaixo), recoloração (abaixo).

  7. Informe o caminho de saída, o que mudou, o que foi deliberadamente mantido e o local do backup.

Pixels de fundo remanescentes (specks)

Lascas brancas entre fios de cabelo ou dentro de contornos escuros. Sempre marque antes de preencher:

ia specks out.png --mark marked.jpg          # circula cada candidato; imprime a contagem
ia specks out.png -o fixed.png --keep 1237,1467   # preenche; protege um brilho deliberado

Leia marked.jpg e verifique cada círculo. Se algum estiver sobre arte real (renda, brilho nos olhos, brilho), use --keep x,y ou uma --region x0,y0,x1,y1. Em seguida, compare antes e depois com preview --crop. Os padrões são ajustados para áreas escuras e neutras (cabelo preto, contornos). Para áreas coloridas, aumente --surround-max-sat.

Recolorindo formas (components, recolor)

ia components out.png                    # id, bbox, tamanho, cor média 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 amostra a cor e a textura da forma em --like-at em uma imagem de referência. Cada pixel mantém seu desvio claro/escuro, então a textura do pincel ou do giz de cera sobrevive. Escolha formas com --at (um ponto dentro delas). É mais seguro do que ids, que mudam quando a imagem muda.

Regras

  • Inspecione o resultado você mesmo (leia a imagem de pré-visualização) após cada etapa. Não presuma que os padrões funcionaram.
  • Passe caminhos como argumentos e execute o Python com -I. Nunca nomeie um arquivo temporário com o nome de um módulo da stdlib (inspect.py ocultou a importação do numpy uma vez).
  • Mantenha a saída temporária na pasta tmp/ da tarefa ou na pasta temporária do sistema, não ao lado das imagens do usuário.

Testes

Ao desenvolver dentro do repositório da skill, execute o conjunto de testes Python com 100% de cobertura de ramos:

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

Habilidades Relacionadas