| 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
- Identify the input image from the user's uploads (e.g.,
/mnt/user-data/uploads/).
- Copy it to a working directory (e.g.,
/home/claude/).
- Run the background removal script located at
scripts/remove_bg.py relative to this SKILL.md.
- 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
| Flag | Default | Purpose |
|---|
--input | (required) | Path to input image (PNG or JPEG) |
--output | (required) | Path to output PNG |
--hard-threshold | 235 | Pixels with R, G, B all above this become fully transparent |
--soft-threshold | 200 | Pixels between soft and hard threshold get partial transparency (edge blending) |
--target-color | 255,255,255 | Background color as R,G,B. Change for colored backgrounds |
--color-distance | 0 | When >0, use Euclidean distance from target color instead of per-channel thresholds. Good for colored backgrounds (try 30-60) |
--preview | off | Print pixel stats without writing the output file. Useful for tuning thresholds |
--quiet | off | Suppress stats output. Useful for scripting and pipelines |
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
- Converts the image to RGBA (adds alpha channel if missing).
- Hard cutoff: pixels close enough to the target background color become fully transparent (alpha = 0).
- 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.
