babayaga 207cb53f6f media : background | watermark

2025-08-11 12:25:45 +02:00

14 KiB

Raw Blame History

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 for high-quality results and supports batch processing with multiple AI models.

Installation
Setup
Basic Usage
AI Models
Command Line Options
API Usage
Examples
Alpha Matting
Performance Tips
Troubleshooting

Installation

npm install @polymech/media

Setup

1. Get Replicate API Key

Visit Replicate API Tokens
Sign up or log in to your account
Create a new API token
Copy your API token

2. Set API Key

You can provide your API key in two ways:

Option A: Environment Variable (Recommended)

export REPLICATE_API_TOKEN="your_api_token_here"

Option B: Command Line Argument

pm-media background:remove --src input.jpg --apiKey "your_api_token_here"

Basic Usage

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

# 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

import { 
  backgroundRemove,
  removeBackgroundFile,
  BackgroundRemoveOptions 
} from '@polymech/media';

Single File Background Removal

import { removeBackgroundFile } from '@polymech/media';

await removeBackgroundFile(
  'input.jpg',
  'output.png',
  {
    apiKey: 'your_api_token',
    model: 'u2net',
    alpha_matting: false
  }
);

Batch Processing API

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

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

# Remove background from a single image
pm-media background:remove \
  --src "photo.jpg" \
  --dst "no-background.png"

Example 2: Batch Processing

# Process multiple images
pm-media background:remove \
  --src "photos/*.jpg" \
  --dst "processed/" \
  --model u2net

Example 3: Portrait Optimization

# Optimized for people/portraits
pm-media background:remove \
  --src "portraits/*.jpg" \
  --dst "headshots/" \
  --model u2net_human_seg \
  --alphaMattting

Example 4: Product Photography

# 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

# 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

# Quick processing for previews
pm-media background:remove \
  --src "batch/*.jpg" \
  --dst "previews/" \
  --model u2netp

Example 7: Dry Run Preview

# Preview what would be processed
pm-media background:remove \
  --src "archive/**/*.jpg" \
  --dst "processed/" \
  --dry \
  --verbose

Example 8: Organized Output

# 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

# 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

# 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

# Fast processing
--model u2netp

# Balanced quality/speed
--model u2net

# High quality (slower)
--model silueta

2. Use Alpha Matting Selectively

# 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

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

Cost Optimization

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

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

# Install missing dependency
npm install replicate

Poor edge quality

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

pm-media background:remove \
  --src "input/*" \
  --dst "output/" \
  --debug \
  --verbose

Quality Issues

# 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

#!/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

#!/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

#!/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

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

#!/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

#!/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

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

License

This tool is part of the @polymech/media package. Please refer to the package license for usage terms.

14 KiB Raw Blame History