remove-bg: usuwanie tła ze zdjęć z natywnego macOS, z poziomu terminala

TL;DR

remove-bg
to dwucyfrowa liczba linii Swifta, która opakowuje natywny macOS Vision
request VNGenerateForegroundInstanceMaskRequest w CLI.
Czyli ten sam silnik usuwania tła co Preview/Finder „Usuń
tło” — tylko z terminala, w pipeline’ach, w pętli
for po folderze. Plus skill do Claude Code, żeby agent sam
to wołał, kiedy mówisz „wytnij tło z tego pliku”.

Repo: github.com/stroniarz/remove-bg
Licencja: MIT Wymagania: macOS 14+

Problem

Zdjęcia produktowe, mockupy, hero illustrations, ikonki na Slacka —
co kilka dni potrzebuję wyciąć obiekt z tła. Klikanie w Preview działa,
ale:

• nie działa w pętli po folderze
• nie działa z poziomu skryptu publikacyjnego
• nie działa, kiedy Claude Code prowadzi cały workflow przygotowania
  assetów

remove.bg API kosztuje, ma rate limit i wysyła wszystko na zewnątrz.
Lokalnych modeli (rembg, BiRefNet) używałem — i jakość bywa, ale
instalacja Pythona z odpowiednimi wagami za każdym razem to nie jest
„one-liner”.

A Apple od macOS 14 ma w systemie model, który robi
to lepiej niż większość lokalnych torchowych setupów. Ten sam, który
widzisz w Preview, w Finderze, w Photos. Brakowało tylko CLI.

Rozwiązanie: 70 linii Swifta

let request = VNGenerateForegroundInstanceMaskRequest()
let handler = VNImageRequestHandler(ciImage: ciImage, options: [:])
try handler.perform([request])

To są trzy kluczowe linie. Reszta to wczytanie obrazka, kompozycja
maski na alfę, zapis PNG. Cały skrypt buduje się jednym
xcrun swiftc -O remove_bg.swift -o remove-bg — bez
zewnętrznych zależności, bez pip install, bez
kontenerów.

Użycie:

remove-bg input.jpg output.png

Batch:

mkdir -p out
for f in *.jpg; do remove-bg "$f" "out/${f%.jpg}.png"; done

I to jest cała powierzchnia narzędzia. Bo tak naprawdę inteligencja
siedzi w Vision frameworku — i Apple ją utrzymuje.

Dlaczego CLI to było warte
zachodu

Trzy momenty z ostatniego tygodnia, kiedy remove-bg
ratował robotę:

1. Przygotowanie zdjęć produktowych dla klienta.
Folder z 40 fotkami ze studia, każda z bałaganem na podłodze, wszystkie
potrzebne na białym/transparentnym tle. Zamiast 40 razy klikać w Preview
—
for f in *.jpg; do remove-bg "$f" "out/${f%.jpg}.png"; done.
Cztery sekundy.

2. Hero ilustracja na bloga. Generuję background w
heroes/, do tego potrzebuję mockupa terminala wyciętego na
alfę. Skript generate-hero.js woła remove-bg w
jednym kroku pipeline’u — bez ręcznego rozdzielania faz „wygeneruj
background”, „wytnij obiekt”, „połącz”.

3. Claude Code workflow. „Zrób mi hero do posta o
NotebookLM” — Claude generuje grafikę, woła remove-bg,
wkleja w hero template, daje preview. Zero klikania.

Punkt 3 był punktem zapalnym do napisania skilla do Claude
Code.

Skill do Claude Code

W repo jest plik SKILL.md — frontmatter + opis, który
Claude Code czyta i decyduje, czy odpalić to narzędzie. Triggery są
dwujęzyczne (EN/PL):

Triggers on phrases like “remove background”, “cut out subject”,
“isolate product”, “transparent PNG”, and Polish equivalents (“wytnij
tło”, “usuń tło”).

Po ./install.sh skill jest symlinkowany do
~/.claude/skills/remove-bg/. W sesji Claude Code
wystarczy:

Wytnij tło z ~/Desktop/produkt.jpg.

Claude czyta SKILL.md, wie że ma uruchomić
remove-bg input output, robi to, raportuje ścieżkę pliku
wynikowego. Bez tłumaczenia za każdym razem „a teraz uruchom to
narzędzie z tymi argumentami”.

To jest dla mnie ten moment, kiedy „tool” staje się częścią
agenta, a nie kolejnym CLI do zapamiętania.

Co działa, co nie

Działa: – JPG, PNG, HEIC, TIFF, WEBP — wszystko, co
Cocoa potrafi zdekodować – Subject z wyraźną krawędzią — produkty,
ludzie, zwierzęta, większość obiektów – Batch po folderze – Pipeline’y
CI/CD na macOS runnerach

Nie działa albo działa źle: – macOS < 14 — Vision
request nie istnieje, exit 3 – Brak wyraźnego foreground subject — pusta
maska, output transparentny – Wiele subjectów na jednym zdjęciu — Vision
łączy wszystkie w jedną maskę, nie dokładnie izoluje pojedyncze – Bardzo
duże obrazy (>50 MP) — Vision potrafi wyrzucić out-of-memory; trzeba
downscale’ować przez sips najpierw

Dlaczego
nie po prostu „uruchom Preview z Automatorem”

Próbowałem. Automator workflow z Preview działa, ale: – nie integruje
się z Claude Code – wolniejszy (uruchamia GUI Preview) – nie jest
pipe-friendly — output to plik w Trashu po Quick Action – nie ma kodów
wyjścia do skryptów

CLI z exit codes (0 ok / 1 usage /
2 load failed / 3 Vision error) to standard,
który skrypty mogą obsłużyć. Plus 70 linii Swifta jest bardzo
przejrzyste — całe repo można przeczytać w 2 minuty.

Plan na dalej

• Wersja z prompt-em (jak Claude Vision API) — żeby
  móc napisać „wytnij tylko buty, zostaw resztę”. Vision tego natywnie nie
  ma; trzeba by zhybrydyzować z Apple Intelligence albo zewnętrznym
  modelem.
• Dodanie tła — drugi tryb: zamiast usuwać, generować
  podmiankę tła z prompt-a (Vision + Image Playground od macOS 15).
• Web wrapper — rzecz jasna nie publiczny, bo wtedy
  ktoś by go zaczął rate-limit’ować w produkcji; ale wewnętrzny do paneli
  klienckich, gdzie obrazy lecą po SSH na MacMini, są przerabiane i
  wracają na S3.

Repo

Całość na MIT: github.com/stroniarz/remove-bg.
Issues mile widziane, PR-y też. Jeśli coś nie zadziała na Twoim macOS —
interesuje mnie, dlaczego, bo właśnie po to to publikuję.