# 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.