bg-remove

# Background Remove — Local AI Background Removal Remove backgrounds from images using rembg (local, offline, no data sent externally). Outputs RGBA PNG with proper transparency. ## Input Arguments after `/bg-remove`: - **Source image path** (required) — path to the image - **`--trim`** (optional) — auto-trim transparent padding after removal - **`--output <path>`** (optional) — custom output path. Default: same directory, `<name>-transparent.png` Examples: - `/bg-remove assets/character/mascot.png` - `/bg-remove image.png --trim` - `/bg-remove image.png --output ~/Desktop/result.png` ## Setup rembg is installed in a dedicated venv. Always activate it before use: ```bash source ~/.claude/tools/rembg-env/bin/activate ``` If the venv doesn't exist, install it: ```bash python3 -m venv ~/.claude/tools/rembg-env && source ~/.claude/tools/rembg-env/bin/activate && pip install "rembg[cpu,cli]" ``` Model files are cached in `~/.u2net/` (downloaded on first use per model, ~170MB for birefnet-general). ## Process ### Step 1: Verify Input 1. Check the source image exists 2. Get dimensions: `sips -g pixelWidth -g pixelHeight <path>` 3. View the image with the Read tool to understand what we're working with ### Step 2: Remove Background Use the `birefnet-general` model — validated in testing on illustrated/character art *and* general photos, producing clean edges across both. ```bash source ~/.claude/tools/rembg-env/bin/activate && rembg i -m birefnet-general <input> <output> ``` **Model choice:** Default to `birefnet-general`. In side-by-side testing it gave clean edges on both illustrated subjects and photographic ones. Avoid anime-trained models (e.g. `isnet-anime`): on non-anime and even some illustrated inputs they tend to add artifacts and leave dark patches around edges. If `birefnet-general` underperforms on a specific image, compare against another general model rather than an anime-specific one. ### Step 3: Verify Result The Read tool renders transparency as black, so you MUST verify by compositing on a colored background: ```bash source ~/.claude/tools/rembg-env/bin/activate && python3 -c " from PIL import Image import numpy as np # Load result img = Image.open('<output>').convert('RGBA') alpha = np.array(img)[:,:,3] total = alpha.size transparent = np.sum(alpha == 0) opaque = np.sum(alpha == 255) print(f'Dimensions: {img.size}') print(f'Transparent: {transparent/total*100:.1f}%') print(f'Opaque: {opaque/total*100:.1f}%') print(f'Corners alpha: TL={alpha[0,0]} TR={alpha[0,-1]} BL={alpha[-1,0]} BR={alpha[-1,-1]}') # Composite on magenta for visual verification bg = Image.new('RGBA', img.size, (255, 0, 255, 255)) bg.paste(img, (0, 0), img) bg.save('<output_dir>/verify-magenta.png') print('Verification image saved') " ``` Then view the magenta verification image with the Read tool. The magenta should only show where background was removed. ### Step 4: Optional Trim If `--trim` was requested, trim transparent padding: ```bash source ~/.claude/tools/rembg-env/bin/activate && python3 -c " from PIL import Image import numpy as np img = Image.open('<output>').convert('RGBA') alpha = np.array(img)[:,:,3] # Find bounding box of non-transparent pixels rows = np.any(alpha > 0, axis=1) cols = np.any(alpha > 0, axis=0) rmin, rmax = np.where(rows)[0][[0, -1]] cmin, cmax = np.where(cols)[0][[0, -1]] # Add small padding (2% of dimensions) pad_h = max(int(img.height * 0.02), 4) pad_w = max(int(img.width * 0.02), 4) rmin = max(0, rmin - pad_h) rmax = min(img.height - 1, rmax + pad_h) cmin = max(0, cmin - pad_w) cmax = min(img.width - 1, cmax + pad_w) cropped = img.crop((cmin, rmin, cmax + 1, rmax + 1)) cropped.save('<output>') print(f'Trimmed: {img.size} -> {cropped.size}') " ``` ### Step 5: Report ``` Done: background removed Source: <input_path> Output: <output_path> Dimensions: <width>x<height> Transparent pixels: <percent>% Model: birefnet-general (local, offline) ``` **Verify before shipping:** open the output in Preview.app (or any viewer that shows the checkerboard pattern) to confirm real transparency. The Read tool renders transparency as solid black, so it cannot distinguish a transparent background from a black one — composite-over-a-color (Step 3) or a checkerboard viewer is the only reliable check. ## Important Rules 1. **Default to `birefnet-general`** — in side-by-side testing it produced the cleanest edges on both illustrated and photographic inputs; anime-trained models added artifacts. Only switch models if it visibly underperforms on a specific image. 2. **Always activate the venv** before running rembg or Python with Pillow/numpy. 3. **Always verify with magenta composite** — don't trust the Read tool's rendering of transparency. 4. **Never send images to external services** — rembg runs 100% locally. 5. **Preserve original files** — output to a new file, never overwrite the source. 6. **Clean up verification images** — delete the magenta composite after confirming quality.