aiocean aio-remove-background — RMBG-2.0 alpha matting → PNG RGBA cutout
Tách nền ảnh thành PNG RGBA cutout bằng RMBG-2.0 (BiRefNet) — alpha matte mềm bám sát silhouette, kể cả tóc/khói/glow. Pipeline đóng cứng (không tham số fiddle): matting → despill (color unmixing khử ánh nền hắt lên mép) → erode 1px.
Engine-agnostic. Ảnh nguồn từ đâu cũng được — chụp thật, screenshot, render từ
gpt-image / Imagen / SDXL / FLUX / Grok. Không phụ thuộc nền phải phẳng. Nếu ảnh có
nền phẳng (vd flat-magenta #FF00FF key từ render), despill còn ăn thêm — mép
sạch nhất.
Environment
- python3: !
which python3 2>/dev/null || echo "NOT INSTALLED" - Pillow: !
python3 -c "import PIL" 2>/dev/null && echo "installed" || echo "NOT INSTALLED" - numpy: !
python3 -c "import numpy" 2>/dev/null && echo "installed" || echo "NOT INSTALLED" - torch: !
python3 -c "import torch" 2>/dev/null && echo "installed" || echo "NOT INSTALLED" - transformers: !
python3 -c "import transformers" 2>/dev/null && echo "installed" || echo "NOT INSTALLED" - HF auth: !
hf auth whoami 2>/dev/null || huggingface-cli whoami 2>/dev/null || echo "NOT LOGGED IN (cần cho RMBG-2.0 gated repo)" - Script: !
echo "${CLAUDE_PLUGIN_ROOT}/skills/aio-remove-background/scripts/chroma-key.py"
Quick start
RB="${CLAUDE_PLUGIN_ROOT}/skills/aio-remove-background/scripts"
python3 $RB/chroma-key.py input.png output.png
python3 $RB/chroma-key.py render-magenta.png sprite.png # despill on (default)
python3 $RB/chroma-key.py photo.jpg cutout.png --no-despill # nền không phẳng → không cần despill
python3 $RB/chroma-key.py input.png out.png --model ZhengPeng7/BiRefNet # MIT, không gated
Output luôn là PNG RGBA — auto thêm .png nếu thiếu đuôi.
Hợp đồng
| Tham số | Bắt buộc | Ý nghĩa |
|---|---|---|
<input> |
✅ | Ảnh nguồn bất kỳ (PNG/JPG/WEBP). |
<output.png> |
✅ | Path PNG RGBA. Script auto thêm .png nếu thiếu. |
--despill / --no-despill |
⬜ | Mặc định bật. Khử ánh nền hắt lên mép (color unmixing dựa trên alpha và màu góc). Nền lộn xộn (ảnh chụp) → tắt vì sample 4 góc không còn nghĩa. |
--model |
⬜ | Mặc định briaai/RMBG-2.0 (CC BY-NC 4.0, gated). Thương mại → ZhengPeng7/BiRefNet (MIT, không gated). |
Despill — khi nào bật / tắt
Despill giải mô hình pixel C = α·F + (1−α)·Key, lấy Key từ trung bình 4 góc ảnh.
- ✅ Bật (default) khi nền phẳng đồng màu (magenta key, green screen, white studio): mép sạch, không halo.
- ❌ Tắt (
--no-despill) khi nền lộn xộn (ảnh chụp ngoài trời, cảnh phức tạp): 4 góc không đại diện nền → despill kéo lệch màu subject. Lúc đó chỉ dùng matting + erode.
Setup lần đầu
pip install pillow numpy torch torchvision transformers kornia
hf auth login # paste HuggingFace access token
# vào https://huggingface.co/briaai/RMBG-2.0 → bấm chấp nhận điều khoản
Lần chạy đầu sẽ tải model (~150MB), những lần sau cached.
License
RMBG-2.0 = CC BY-NC 4.0 (phi thương mại). Dùng cho personal / research / open-source non-commercial OK. Thương mại hoá → 2 đường:
- Mua license Bria (commercial tier).
- Chuyển sang
--model ZhengPeng7/BiRefNet(MIT, hiệu năng tương đương, không gated).
Errors
| Triệu chứng | Nguyên nhân | Fix |
|---|---|---|
cần Pillow / numpy / torch transformers |
Chưa cài deps | Chạy lệnh pip install ở mục Setup |
không tải được 'briaai/RMBG-2.0' |
Gated repo, chưa accept terms hoặc chưa hf auth login |
Accept ToS trên model page + hf auth login, hoặc đổi --model ZhengPeng7/BiRefNet |
| Halo magenta/lục còn dính mép | Despill tắt hoặc nền không thực sự phẳng | Bật despill; nếu nền photo lộn xộn, despill không cứu được → re-render trên nền phẳng |
| Subject mất vùng | Subject color trùng nền (subject magenta trên nền magenta) | Đổi màu key, hoặc thêm rim light trong prompt để tách subject khỏi nền |
| Erode quá gắt với subject mảnh | Subject < 3px (tóc thưa, dây) | Hiện cố định 1px — fork script chỉnh ERODE_PX = 0 nếu cần |
Pipeline điển hình với flat-magenta render
Hầu hết text-to-image engine (gpt-image-2, Imagen, FLUX, SDXL, Midjourney, Grok) không xuất
transparent PNG ổn định. Workaround universal: render subject trên nền phẳng #FF00FF rồi chroma-key:
prompt (subject on flat magenta #FF00FF)
→ [bất kỳ image gen engine của bạn]
→ render-raw.png (subject + nền magenta phẳng)
→ python3 $RB/chroma-key.py render-raw.png sprite.png
→ sprite.png (PNG RGBA, mép sạch, không halo magenta)
Câu nền nên copy nguyên vào cuối prompt để engine không nhét magenta lên subject:
"The subject stands alone, centered on a completely flat uniform solid pure chroma magenta background (hex FF00FF) filling the entire frame; this magenta appears nowhere on the subject itself. A clean image with no lettering, no interface elements, no text, no watermark."
Nền lộn xộn (photo, screenshot) → cứ chạy thẳng script với --no-despill, RMBG-2.0 vẫn matte tốt.