透明背景 是做什么的?
由一个脚本 scripts/imgalpha.py 完成所有工作。通过 uv 运行(无需全局安装),支持 macOS、Linux 或 Windows。在仓库内为每个 shell 会话定义一次 ia 辅助命令即可,它会解析绝对路径,因此后续的 cd 操作不会影响。下面的示例使用它。
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 没有函数,请使用 PowerShell 或 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
颜色写作 r,g,b 格式(例如 --bg 40,96,200),在任何 shell 中都不需要引号。#rrggbb 格式也有效,但需要加引号:PowerShell 会将裸 # 视为注释,cmd 会保留单引号。
工作流程
-
先查看图像。 读取图像。此脚本适用于平坦或近乎平坦的背景。对于照片或复杂背景,请改用 AI 抠图模型(
rembg,请参阅 references/troubleshooting.md)。 -
永远不要修改原始文件。 写入新文件。在就地编辑结果之前,先将其复制到旁边的
backup/<yymmdd-hhmm>/文件夹中。除非使用--in-place,否则脚本拒绝-o等于输入文件。 -
移除背景:
ia remove in.jpg -o out.png。背景颜色是边框的中值颜色(强制使用--bg 255,255,255)。它会移除连接到边缘的背景像素以及颜色相同但无孔洞的封闭间隙,因此皮肤、白色条纹和环形细节得以保留。 -
在对比色背景下放大检查。 透明度会掩盖白色背景上的问题:
ia preview out.png -o check.jpg --bg 40,96,200 --crop 600,140 --crop 260,1140,60查看
check.jpg。也检查深色背景。寻找光晕、阶梯锯齿、浅色细节中的孔洞以及残留的白色像素。 -
逐个修复看到的每个问题,并在每次修复后重新检查。症状 → 修复对照表:请参阅 references/troubleshooting.md。
-
可选扩展操作: 处理残留背景像素(如下所示)、重新着色(如下所示)。
-
报告输出路径、更改内容、有意保留的内容以及备份位置。
残留背景像素(specks)
头发丝之间的白色细丝或深色轮廓内部的白色间隙。在填充前务必先进行标记:
ia specks out.png --mark marked.jpg # 圈出每个候选像素;打印计数
ia specks out.png -o fixed.png --keep 1237,1467 # 填充;保护一个有意的闪光点
查看 marked.jpg 并检查每个圈。如果某个圈位于真实艺术品上(蕾丝、眼睛反光、闪光),使用 --keep x,y 或 --region x0,y0,x1,y1。然后使用 preview --crop 比较前后效果。默认参数针对深色、中性区域(黑发、轮廓)调整。对于彩色区域,请提高 --surround-max-sat。
重新着色形状(components、recolor)
ia components out.png # 每个形状的 id、边界框、大小、平均颜色
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 从参考图像的 --like-at 位置采样该形状的颜色和纹理。每个像素保留其明暗变化,因此画笔或蜡笔纹理得以保留。使用 --at(形状内部的一个点)选择形状。这比使用 ids 更安全,因为 ids 会在图像变化时改变。
规则
- 每个步骤后你自己检查结果(查看预览图像)。不要假设默认参数已完美工作。
- 将路径作为参数传递,并使用
-I运行 Python。绝不要将临时文件命名为像标准库模块的名称(inspect.py曾经遮盖了 numpy 的导入)。 - 将临时输出保存在任务的
tmp/目录或系统的临时文件夹中,不要放在用户的图像旁边。
测试
在技能仓库内进行开发时,运行 Python 测试套件以达到 100% 分支覆盖率:
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