tomevault-io Remove Background
Remove image backgrounds using BiRefNet_lite model. Runs locally on CPU, MPS (Apple Silicon), or CUDA.
When to Use
- User wants to remove background from an image
- User wants a transparent PNG version of an image
- User wants to isolate a subject from its background
Requirements
No API keys required. Model downloads automatically on first run (~100MB, cached).
Command
./scripts/remove_background <input_image> [options]
Options
| Option | Description |
|---|---|
input |
Input image path (required) |
-o, --output |
Output path (default: {name}_nobg.png) |
-c, --crop |
Smart crop to foreground bounding box |
-p, --padding |
Padding around crop in pixels (default: 0) |
--device |
Force device: cuda/mps/cpu (default: auto-detect) |
-f, --format |
Output: json (default) or table |
Examples
# Basic usage - outputs photo_nobg.png
./scripts/remove_background photo.jpg
# Smart crop to subject
./scripts/remove_background photo.jpg --crop
# Smart crop with 20px padding
./scripts/remove_background photo.jpg --crop --padding 20
# Custom output path
./scripts/remove_background photo.jpg -o transparent.png
# Force CPU (if MPS has issues)
./scripts/remove_background photo.jpg --device cpu
# Human-readable output
./scripts/remove_background photo.jpg --format table
Output Format
JSON (default):
{
"input": "photo.jpg",
"output": "photo_nobg.png",
"device": "mps",
"original_size": [1920, 1080],
"output_size": [800, 600],
"cropped": true,
"crop_box": [120, 80, 920, 680],
"model": "ZhengPeng7/BiRefNet_lite"
}
Notes
- First run downloads model (~100MB), subsequent runs use cache
- Output is always PNG with alpha channel (transparency)
- Device auto-detection: CUDA > MPS > CPU
- MPS (Apple Silicon) may have some op fallbacks to CPU
Source: nc9/skills — distributed by TomeVault.