640 lines
14 KiB
Markdown
640 lines
14 KiB
Markdown
# Background Remove CLI Documentation
|
|
|
|
The `pm-media background:remove` command uses AI-powered background removal to automatically isolate subjects from their backgrounds. This tool leverages the [Replicate API](https://replicate.com/cjwbw/rembg) for high-quality results and supports batch processing with multiple AI models.
|
|
|
|
## Table of Contents
|
|
|
|
- [Installation](#installation)
|
|
- [Setup](#setup)
|
|
- [Basic Usage](#basic-usage)
|
|
- [AI Models](#ai-models)
|
|
- [Command Line Options](#command-line-options)
|
|
- [API Usage](#api-usage)
|
|
- [Examples](#examples)
|
|
- [Alpha Matting](#alpha-matting)
|
|
- [Performance Tips](#performance-tips)
|
|
- [Troubleshooting](#troubleshooting)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @polymech/media
|
|
```
|
|
|
|
## Setup
|
|
|
|
### 1. Get Replicate API Key
|
|
|
|
1. Visit [Replicate API Tokens](https://replicate.com/account/api-tokens)
|
|
2. Sign up or log in to your account
|
|
3. Create a new API token
|
|
4. Copy your API token
|
|
|
|
### 2. Set API Key
|
|
|
|
You can provide your API key in two ways:
|
|
|
|
**Option A: Environment Variable (Recommended)**
|
|
```bash
|
|
export REPLICATE_API_TOKEN="your_api_token_here"
|
|
```
|
|
|
|
**Option B: Command Line Argument**
|
|
```bash
|
|
pm-media background:remove --src input.jpg --apiKey "your_api_token_here"
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
pm-media background:remove --src <input> --dst <output> [options]
|
|
```
|
|
|
|
### Required Parameters
|
|
|
|
- `--src`: Source files (FILE|FOLDER|GLOB pattern)
|
|
|
|
### Optional Parameters
|
|
|
|
- `--dst`: Destination path (defaults to source location with modified name)
|
|
- `--apiKey`: Replicate API key (if not set via environment variable)
|
|
|
|
## AI Models
|
|
|
|
The tool supports multiple specialized AI models for different use cases:
|
|
|
|
### Available Models
|
|
|
|
| Model | Best For | Description |
|
|
|-------|----------|-------------|
|
|
| `u2net` (default) | General use | Universal background removal |
|
|
| `u2netp` | Performance | Lighter version of U2Net |
|
|
| `u2net_human_seg` | People | Optimized for human subjects |
|
|
| `u2net_cloth_seg` | Clothing | Specialized for clothing items |
|
|
| `silueta` | Portraits | High-quality person silhouettes |
|
|
|
|
### Model Selection
|
|
|
|
```bash
|
|
# General purpose (default)
|
|
pm-media background:remove --src photo.jpg --model u2net
|
|
|
|
# Optimized for people
|
|
pm-media background:remove --src portrait.jpg --model u2net_human_seg
|
|
|
|
# Clothing/fashion
|
|
pm-media background:remove --src product.jpg --model u2net_cloth_seg
|
|
```
|
|
|
|
## Command Line Options
|
|
|
|
### Core Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `--src` | string | required | Source files (FILE\|FOLDER\|GLOB) |
|
|
| `--dst` | string | - | Destination path |
|
|
| `--apiKey` | string | - | Replicate API key |
|
|
| `--model` | choice | "u2net" | AI model to use |
|
|
|
|
### Alpha Matting Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `--alphaMattting` | boolean | false | Enable alpha matting for better edges |
|
|
| `--alphaMattingForegroundThreshold` | number | 270 | Foreground detection threshold |
|
|
| `--alphaMattingBackgroundThreshold` | number | 10 | Background detection threshold |
|
|
| `--alphaMattingErodeSize` | number | 10 | Edge erosion size |
|
|
|
|
### Utility Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `--dry` | boolean | false | Preview mode (no API calls) |
|
|
| `--verbose` | boolean | false | Show detailed processing info |
|
|
| `--debug` | boolean | false | Enable debug messages |
|
|
| `--logLevel` | string | "info" | Log level (warn\|info\|debug\|error) |
|
|
|
|
## API Usage
|
|
|
|
### Import the Library
|
|
|
|
```typescript
|
|
import {
|
|
backgroundRemove,
|
|
removeBackgroundFile,
|
|
BackgroundRemoveOptions
|
|
} from '@polymech/media';
|
|
```
|
|
|
|
### Single File Background Removal
|
|
|
|
```typescript
|
|
import { removeBackgroundFile } from '@polymech/media';
|
|
|
|
await removeBackgroundFile(
|
|
'input.jpg',
|
|
'output.png',
|
|
{
|
|
apiKey: 'your_api_token',
|
|
model: 'u2net',
|
|
alpha_matting: false
|
|
}
|
|
);
|
|
```
|
|
|
|
### Batch Processing API
|
|
|
|
```typescript
|
|
import { backgroundRemove } from '@polymech/media';
|
|
|
|
const options: BackgroundRemoveOptions = {
|
|
src: 'photos/*.jpg',
|
|
dst: 'no-bg/',
|
|
apiKey: process.env.REPLICATE_API_TOKEN,
|
|
model: 'u2net_human_seg',
|
|
alpha_matting: true,
|
|
// ... other IOptions
|
|
};
|
|
|
|
await backgroundRemove(options);
|
|
```
|
|
|
|
### Advanced Configuration
|
|
|
|
```typescript
|
|
const advancedOptions: BackgroundRemoveOptions = {
|
|
src: 'portraits/*.jpg',
|
|
dst: 'processed/',
|
|
apiKey: 'your_token',
|
|
model: 'u2net_human_seg',
|
|
alpha_matting: true,
|
|
alpha_matting_foreground_threshold: 280,
|
|
alpha_matting_background_threshold: 15,
|
|
alpha_matting_erode_size: 8,
|
|
verbose: true
|
|
};
|
|
|
|
await backgroundRemove(advancedOptions);
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Example 1: Basic Background Removal
|
|
|
|
```bash
|
|
# Remove background from a single image
|
|
pm-media background:remove \
|
|
--src "photo.jpg" \
|
|
--dst "no-background.png"
|
|
```
|
|
|
|
### Example 2: Batch Processing
|
|
|
|
```bash
|
|
# Process multiple images
|
|
pm-media background:remove \
|
|
--src "photos/*.jpg" \
|
|
--dst "processed/" \
|
|
--model u2net
|
|
```
|
|
|
|
### Example 3: Portrait Optimization
|
|
|
|
```bash
|
|
# Optimized for people/portraits
|
|
pm-media background:remove \
|
|
--src "portraits/*.jpg" \
|
|
--dst "headshots/" \
|
|
--model u2net_human_seg \
|
|
--alphaMattting
|
|
```
|
|
|
|
### Example 4: Product Photography
|
|
|
|
```bash
|
|
# E-commerce product images
|
|
pm-media background:remove \
|
|
--src "products/*.jpg" \
|
|
--dst "catalog/" \
|
|
--model u2net_cloth_seg \
|
|
--alphaMattting \
|
|
--alphaMattingForegroundThreshold 280
|
|
```
|
|
|
|
### Example 5: High-Quality Processing
|
|
|
|
```bash
|
|
# Maximum quality with alpha matting
|
|
pm-media background:remove \
|
|
--src "studio-photos/*.jpg" \
|
|
--dst "final/" \
|
|
--model silueta \
|
|
--alphaMattting \
|
|
--alphaMattingForegroundThreshold 300 \
|
|
--alphaMattingBackgroundThreshold 5 \
|
|
--verbose
|
|
```
|
|
|
|
### Example 6: Fast Batch Processing
|
|
|
|
```bash
|
|
# Quick processing for previews
|
|
pm-media background:remove \
|
|
--src "batch/*.jpg" \
|
|
--dst "previews/" \
|
|
--model u2netp
|
|
```
|
|
|
|
### Example 7: Dry Run Preview
|
|
|
|
```bash
|
|
# Preview what would be processed
|
|
pm-media background:remove \
|
|
--src "archive/**/*.jpg" \
|
|
--dst "processed/" \
|
|
--dry \
|
|
--verbose
|
|
```
|
|
|
|
### Example 8: Organized Output
|
|
|
|
```bash
|
|
# Maintain folder structure
|
|
pm-media background:remove \
|
|
--src "organized/session-1/*.jpg" \
|
|
--dst "no-bg/session-1/" \
|
|
--model u2net_human_seg
|
|
```
|
|
|
|
## Alpha Matting
|
|
|
|
Alpha matting provides superior edge quality for complex subjects with fine details like hair, fur, or transparent materials.
|
|
|
|
### When to Use Alpha Matting
|
|
|
|
✅ **Use alpha matting for:**
|
|
- Portraits with detailed hair
|
|
- Furry animals
|
|
- Objects with fine edges
|
|
- Semi-transparent materials
|
|
- Professional/commercial work
|
|
|
|
❌ **Skip alpha matting for:**
|
|
- Simple shapes
|
|
- Hard edges
|
|
- Quick previews
|
|
- Batch processing (slower)
|
|
|
|
### Alpha Matting Parameters
|
|
|
|
```bash
|
|
# Standard alpha matting
|
|
pm-media background:remove \
|
|
--src input.jpg \
|
|
--dst output.png \
|
|
--alphaMattting
|
|
|
|
# Fine-tuned alpha matting
|
|
pm-media background:remove \
|
|
--src portrait.jpg \
|
|
--dst result.png \
|
|
--alphaMattting \
|
|
--alphaMattingForegroundThreshold 280 \
|
|
--alphaMattingBackgroundThreshold 12 \
|
|
--alphaMattingErodeSize 6
|
|
```
|
|
|
|
### Parameter Guidelines
|
|
|
|
| Parameter | Low Value | High Value | Effect |
|
|
|-----------|-----------|------------|--------|
|
|
| Foreground Threshold | 200 | 350 | More/less foreground detection |
|
|
| Background Threshold | 5 | 20 | More/less background detection |
|
|
| Erode Size | 3 | 15 | Smaller/larger edge refinement |
|
|
|
|
## File Format Support
|
|
|
|
### Supported Input Formats
|
|
- JPEG (.jpg, .jpeg)
|
|
- PNG (.png)
|
|
- WebP (.webp)
|
|
- TIFF (.tiff, .tif)
|
|
|
|
### Output Format
|
|
- **PNG with transparency** (recommended)
|
|
- Automatically adds transparency channel
|
|
- Preserves original quality
|
|
|
|
### Format Recommendations
|
|
|
|
```bash
|
|
# For web use
|
|
pm-media background:remove --src input.jpg --dst output.png
|
|
|
|
# For print/professional
|
|
pm-media background:remove --src input.tiff --dst output.png --alphaMattting
|
|
```
|
|
|
|
## Performance Tips
|
|
|
|
### 1. Choose Appropriate Models
|
|
|
|
```bash
|
|
# Fast processing
|
|
--model u2netp
|
|
|
|
# Balanced quality/speed
|
|
--model u2net
|
|
|
|
# High quality (slower)
|
|
--model silueta
|
|
```
|
|
|
|
### 2. Use Alpha Matting Selectively
|
|
|
|
```bash
|
|
# For most images (faster)
|
|
pm-media background:remove --src batch/*.jpg --dst output/
|
|
|
|
# For detailed work only (slower)
|
|
pm-media background:remove --src detailed/*.jpg --dst output/ --alphaMattting
|
|
```
|
|
|
|
### 3. Batch Processing Strategies
|
|
|
|
```bash
|
|
# Process in chunks for large batches
|
|
pm-media background:remove --src "batch1/*.jpg" --dst "output1/"
|
|
pm-media background:remove --src "batch2/*.jpg" --dst "output2/"
|
|
```
|
|
|
|
### 4. API Rate Limiting
|
|
|
|
The Replicate API has rate limits. For large batches:
|
|
- Process during off-peak hours
|
|
- Consider parallel processing limits
|
|
- Monitor API usage in your Replicate dashboard
|
|
|
|
## Cost Considerations
|
|
|
|
### Replicate Pricing
|
|
|
|
Background removal costs per prediction. Check current pricing at [Replicate Pricing](https://replicate.com/pricing).
|
|
|
|
### Cost Optimization
|
|
|
|
```bash
|
|
# Test with dry run first
|
|
pm-media background:remove --src "*.jpg" --dst "output/" --dry
|
|
|
|
# Use efficient models
|
|
--model u2netp # Fastest/cheapest
|
|
--model u2net # Balanced
|
|
--model silueta # Highest quality/most expensive
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### "API key is required"
|
|
```bash
|
|
# Set environment variable
|
|
export REPLICATE_API_TOKEN="your_token"
|
|
|
|
# Or use command line
|
|
pm-media background:remove --src input.jpg --apiKey "your_token"
|
|
```
|
|
|
|
#### "Replicate package not found"
|
|
```bash
|
|
# Install missing dependency
|
|
npm install replicate
|
|
```
|
|
|
|
#### Poor edge quality
|
|
```bash
|
|
# Enable alpha matting
|
|
pm-media background:remove \
|
|
--src input.jpg \
|
|
--dst output.png \
|
|
--alphaMattting \
|
|
--alphaMattingForegroundThreshold 280
|
|
```
|
|
|
|
#### API rate limit errors
|
|
- Reduce batch size
|
|
- Add delays between requests
|
|
- Check your Replicate dashboard for limits
|
|
|
|
#### Large file processing fails
|
|
- Resize images before processing
|
|
- Use appropriate model for image type
|
|
- Check API payload limits
|
|
|
|
### Debug Mode
|
|
|
|
Enable detailed logging:
|
|
|
|
```bash
|
|
pm-media background:remove \
|
|
--src "input/*" \
|
|
--dst "output/" \
|
|
--debug \
|
|
--verbose
|
|
```
|
|
|
|
### Quality Issues
|
|
|
|
```bash
|
|
# For people/portraits
|
|
--model u2net_human_seg
|
|
|
|
# For products/objects
|
|
--model u2net_cloth_seg
|
|
|
|
# For complex edges
|
|
--alphaMattting --alphaMattingForegroundThreshold 300
|
|
```
|
|
|
|
## Integration Examples
|
|
|
|
### E-commerce Workflow
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Product photography pipeline
|
|
|
|
INPUT_DIR="$1"
|
|
OUTPUT_DIR="$2"
|
|
|
|
# Remove backgrounds
|
|
pm-media background:remove \
|
|
--src "$INPUT_DIR/*.jpg" \
|
|
--dst "$OUTPUT_DIR/no-bg/" \
|
|
--model u2net_cloth_seg \
|
|
--alphaMattting
|
|
|
|
# Create thumbnails
|
|
pm-media resize \
|
|
--src "$OUTPUT_DIR/no-bg/*.png" \
|
|
--dst "$OUTPUT_DIR/thumbs/" \
|
|
--width 300 \
|
|
--height 300 \
|
|
--fit contain \
|
|
--background white
|
|
```
|
|
|
|
### Portrait Studio Workflow
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Professional portrait processing
|
|
|
|
pm-media background:remove \
|
|
--src "portraits/*.jpg" \
|
|
--dst "processed/" \
|
|
--model u2net_human_seg \
|
|
--alphaMattting \
|
|
--alphaMattingForegroundThreshold 290 \
|
|
--verbose
|
|
|
|
echo "Background removal complete"
|
|
```
|
|
|
|
### Batch Organization Script
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Organize processed images
|
|
|
|
for dir in */; do
|
|
if [ -d "$dir" ]; then
|
|
echo "Processing directory: $dir"
|
|
pm-media background:remove \
|
|
--src "$dir*.jpg" \
|
|
--dst "no-bg/$dir" \
|
|
--model u2net \
|
|
--verbose
|
|
fi
|
|
done
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Environment Configuration
|
|
|
|
```bash
|
|
# .env file
|
|
REPLICATE_API_TOKEN=your_token_here
|
|
DEFAULT_BG_MODEL=u2net_human_seg
|
|
ALPHA_MATTING=true
|
|
|
|
# Use in scripts
|
|
pm-media background:remove \
|
|
--src "*.jpg" \
|
|
--dst "output/" \
|
|
--model "$DEFAULT_BG_MODEL"
|
|
```
|
|
|
|
### Quality Control
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Process with multiple quality levels
|
|
|
|
INPUT="$1"
|
|
BASE_NAME=$(basename "$INPUT" .jpg)
|
|
|
|
# Quick preview
|
|
pm-media background:remove \
|
|
--src "$INPUT" \
|
|
--dst "preview/${BASE_NAME}_preview.png" \
|
|
--model u2netp
|
|
|
|
# High quality
|
|
pm-media background:remove \
|
|
--src "$INPUT" \
|
|
--dst "final/${BASE_NAME}_final.png" \
|
|
--model silueta \
|
|
--alphaMattting
|
|
```
|
|
|
|
### Conditional Processing
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Different models based on file type
|
|
|
|
for image in *.jpg; do
|
|
if [[ $image == *"portrait"* ]]; then
|
|
MODEL="u2net_human_seg"
|
|
elif [[ $image == *"product"* ]]; then
|
|
MODEL="u2net_cloth_seg"
|
|
else
|
|
MODEL="u2net"
|
|
fi
|
|
|
|
pm-media background:remove \
|
|
--src "$image" \
|
|
--dst "processed/" \
|
|
--model "$MODEL"
|
|
done
|
|
```
|
|
|
|
## TypeScript Definitions
|
|
|
|
```typescript
|
|
interface BackgroundRemoveOptions extends IOptions {
|
|
apiKey?: string;
|
|
model?: 'u2net' | 'u2netp' | 'u2net_human_seg' | 'u2net_cloth_seg' | 'silueta';
|
|
alpha_matting?: boolean;
|
|
alpha_matting_foreground_threshold?: number;
|
|
alpha_matting_background_threshold?: number;
|
|
alpha_matting_erode_size?: number;
|
|
}
|
|
|
|
declare function removeBackgroundFile(
|
|
inputPath: string,
|
|
outputPath: string,
|
|
options: BackgroundRemoveOptions
|
|
): Promise<void>;
|
|
|
|
declare function backgroundRemove(
|
|
options: BackgroundRemoveOptions
|
|
): Promise<any>;
|
|
```
|
|
|
|
## Security Notes
|
|
|
|
### API Key Security
|
|
|
|
- Never commit API keys to version control
|
|
- Use environment variables in production
|
|
- Rotate keys regularly
|
|
- Monitor usage in Replicate dashboard
|
|
|
|
### File Handling
|
|
|
|
- Validate input file types
|
|
- Check file sizes before processing
|
|
- Sanitize file paths
|
|
- Handle temporary files securely
|
|
|
|
## Contributing
|
|
|
|
For bug reports, feature requests, or contributions, please visit the project repository.
|
|
|
|
## References
|
|
|
|
- [Replicate API Documentation](https://replicate.com/docs)
|
|
- [rembg Model on Replicate](https://replicate.com/cjwbw/rembg)
|
|
- [Replicate Pricing](https://replicate.com/pricing)
|
|
- [API Rate Limits](https://replicate.com/docs/reference/http#rate-limits)
|
|
|
|
## License
|
|
|
|
This tool is part of the @polymech/media package. Please refer to the package license for usage terms.
|
|
|