透明背景 是做什麼的?
一個腳本 scripts/imgalpha.py 負責所有工作。直接透過 uv 執行(無需全域安裝),支援 macOS、Linux 或 Windows。在 repo 目錄內,每個 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 從參考圖片的指定點取樣形狀的顏色和紋理。每個像素會保留自己的亮/暗偏差,因此畫筆或蠟筆的紋理得以保留。使用 --at(形狀內部的點)來選取形狀。這比使用 id 更安全,因為 id 會在圖片改變時發生變化。
規則
- 每個步驟結束後,親自檢查結果(讀取預覽圖片)。不要假設默認值能完美運作。
- 將路徑作為參數傳遞,並使用
-I執行 Python。切勿將暫存檔案命名為 stdlib 模組的名稱(曾經有過inspect.py遮蔽了 numpy 導入的情況)。 - 將暫存輸出放在任務的
tmp/目錄或系統暫存資料夾中,而不是放在使用者的圖片旁邊。
測試
在技能 repo 內開發時,使用 100% 分支覆蓋率執行 Python 測試套件:
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