bg-removal

name: bg-removal description: >- Removes backgrounds from images and produces transparent PNGs with anti-aliased edge blending. Use this skill when the user wants to remove a background from an image, make an image background transparent, cut out a subject from a photo, remove a white background, extract a logo or icon from a solid background, or prepare images for compositing. Also trigger when the user mentions "transparent PNG", "remove bg", "cutout", "background removal", "isolate the subject", "make this logo transparent", or uploads an image and asks to clean up or separate the foreground. Works with white, light, or colored solid backgrounds using color-based thresholding with tunable parameters. Do NOT use for AI-based semantic segmentation, photo editing beyond background removal, format conversion without transparency, image resizing or cropping, or removing complex multi-color or gradient backgrounds. license: MIT compatibility: >- Requires Python 3.8+, Pillow, and NumPy. Works on all platforms (macOS, Linux, Windows). No network access needed. metadata: author: bpolania version: 1.0.0 tags: - image-processing - background-removal - transparency - png

Background Removal

Removes solid-color backgrounds from images and produces transparent PNGs with anti-aliased edge blending.

Setup

Install Pillow and NumPy in a temporary venv to avoid system package conflicts:

python3 -m venv /tmp/imgtools
/tmp/imgtools/bin/pip install Pillow numpy

Use /tmp/imgtools/bin/python to run the processing script.

Workflow

1. Identify the input image from the user's uploads (e.g., /mnt/user-data/uploads/).
2. Copy it to a working directory (e.g., /home/claude/).
3. Run the background removal script located at scripts/remove_bg.py relative to this SKILL.md.
4. Copy the result to the output location (e.g., /mnt/user-data/outputs/) and present it to the user.

Running the Script

/tmp/imgtools/bin/python <skill-dir>/scripts/remove_bg.py \
  --input /home/claude/input.png \
  --output /home/claude/output.png

Arguments

Common Scenarios

White background removal (default):

/tmp/imgtools/bin/python scripts/remove_bg.py --input photo.png --output clean.png

Strict removal (only near-pure-white):

/tmp/imgtools/bin/python scripts/remove_bg.py --input photo.png --output clean.png \
  --hard-threshold 250 --soft-threshold 230

Aggressive removal (light grays too):

/tmp/imgtools/bin/python scripts/remove_bg.py --input photo.png --output clean.png \
  --hard-threshold 220 --soft-threshold 180

Colored background (e.g., light blue #ADD8E6 = 173,216,230):

/tmp/imgtools/bin/python scripts/remove_bg.py --input photo.png --output clean.png \
  --target-color 173,216,230 --color-distance 40

Preview mode (check before committing):

/tmp/imgtools/bin/python scripts/remove_bg.py --input photo.png --output clean.png --preview

How It Works

1. Converts the image to RGBA (adds alpha channel if missing).
2. Hard cutoff: pixels close enough to the target background color become fully transparent (alpha = 0).
3. Edge blending: pixels in the transition zone get partial transparency proportional to their distance from the background color, preventing jagged edges around anti-aliased artwork.

Tuning Guide

Start with defaults and adjust if the result isn't right:

• Too much removed (subject has holes): raise --hard-threshold toward 250 and --soft-threshold toward 230.
• Background residue remains: lower --hard-threshold toward 220 and --soft-threshold toward 180.
• Colored background: use --target-color R,G,B --color-distance 40 and adjust distance up/down.
• Use --preview to check pixel counts before writing the output file.

Edge Cases and Limitations

• JPEG input: The script auto-converts to RGBA, but JPEG compression artifacts leave off-white pixels. Lower --hard-threshold to ~220 for best results. The script warns about this.
• White subjects: If the subject itself contains white areas (e.g., white text, a white shirt), those pixels become transparent too. This is a color-based tool with no subject detection. Warn the user about this limitation.
• Noisy backgrounds: Non-uniform or gradient backgrounds produce patchy results. Suggest a more sophisticated tool for those cases.
• Output format: Always save as PNG. Other formats do not support transparency.

After Processing

Present the output file to the user. Mention the settings used and offer to re-run with different thresholds if the result isn't satisfactory.