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
-
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). -
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. -
Remova o fundo:
ia remove in.jpg -o out.png. A cor do fundo é a mediana da borda (--bg 255,255,255para 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. -
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,60Leia
check.jpg. Verifique também em um fundo escuro. Procure por halos, serrilhados, buracos em detalhes claros, branco residual. -
Corrija o que você vê, um problema de cada vez, reinspecionando após cada um. Tabela de sintoma → correção: references/troubleshooting.md.
-
Extras opcionais: resíduos (abaixo), recoloração (abaixo).
-
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.pyocultou 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