투명 배경은(는) 무엇을 하나요?
하나의 스크립트 scripts/imgalpha.py가 모든 작업을 수행합니다. macOS, Linux, Windows에서 uv를 통해 실행합니다(전역 설치 불필요). 리포지토리 내에서 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). 모든 셸에서 따옴표가 필요 없습니다. #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,60check.jpg를 읽습니다. 어두운 배경에서도 확인합니다. 후광, 계단 현상, 밝은 디테일의 구멍, 남은 흰색을 찾습니다. -
발견한 문제를 한 번에 하나씩 수정하고, 각 단계 후 다시 검사합니다. 증상 → 수정 표: references/troubleshooting.md.
-
선택적 추가 작업: 남은 스펙(아래), 재채색(아래).
-
출력 경로, 변경 사항, 의도적으로 유지한 부분, 백업 위치를 보고합니다.
남은 배경 픽셀 (스펙)
머리카락 사이 또는 어두운 윤곽선 내부의 흰색 가느다란 조각. 채우기 전에 항상 표시합니다:
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을 높이세요.
모양 재채색 (컴포넌트, 리컬러)
ia components out.png # 각 모양의 id, bbox, 크기, 평균 색상
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(모양 내부의 점)으로 모양을 선택합니다. ID는 이미지가 변경되면 바뀔 수 있으므로 ID보다 안전합니다.
규칙
- 매 단계 후 직접 결과를 검사합니다(미리보기 이미지를 읽습니다). 기본값이 제대로 작동했다고 가정하지 마십시오.
- 경로를 인수로 전달하고
-I플래그로 Python을 실행합니다. 스크래치 파일을 표준 라이브러리 모듈 이름으로 절대 지정하지 마십시오(inspect.py가 numpy의 import를 가린 적이 있습니다). - 스크래치 출력물은 작업의
tmp/폴더나 시스템 임시 폴더에 보관하고, 사용자 이미지 옆에 두지 마십시오.
테스트
스킬 리포지토리 내에서 개발할 때, 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