bgone

Ultra-fast CLI tool for removing solid background colors from images using color unmixing.

Features

• Blazing fast - Written in Rust with parallel processing
• Multiple foreground colors - Handles images with multiple foreground colors mixed with the background
• Auto background detection - Automatically detects background color from image edges
• Auto color deduction - Can automatically find unknown foreground colors using the auto keyword
• Opacity optimization - Maximizes opacity while maintaining exact color accuracy
• Precise color unmixing - Uses least-squares optimization for accurate color separation
• Flexible modes - Strict mode for exact color matching, or non-strict mode for more natural transparency

Usage

Non-Strict Mode (Default)

In non-strict mode, bgone can use any color needed to perfectly reconstruct the image while making the background transparent.

# Remove background without specifying foreground colors
bgone input.png output.png

# With specific foreground colors - optimizes for high opacity when pixels match these colors
bgone input.png output.png --fg=#ff0000

# With specific background color - overrides automatic detection
bgone input.png output.png --fg=#ff0000 --bg=#ffffff

# Multiple foreground colors
bgone input.png output.png --fg ff0000 00ff00 0000ff

# Automatic color deduction - finds unknown colors
bgone input.png output.png --fg auto
bgone input.png output.png --fg auto auto --bg ffffff

# Mix known and unknown colors
bgone input.png output.png --fg ff0000 auto

# Using shorthand notation
bgone input.png output.png -f f00 -b fff
bgone input.png output.png -f auto -s
bgone input.png output.png -f f00 0f0 00f -b fff -t 0.1

Strict Mode

Strict mode restricts unmixing to only the specified foreground colors, ensuring exact color matching.

# Strict mode requires --fg, but supports both known colors and 'auto'
bgone input.png output.png --strict --fg=#ff0000
bgone input.png output.png --strict --fg auto
bgone input.png output.png --strict --fg ff0000 auto

# With specific background color
bgone input.png output.png --strict --fg=#f00 --bg=#fff

Additional Examples

# Multiple colors with # prefix still works, but requires quotes in shell
bgone input.png output.png --fg "#f00" "#0f0" "#00f"

# Mix of shorthand and full notation
bgone input.png output.png --fg ff0000 0f0 00f --bg fff

CLI Options

• input - Path to the input image
• output - Path for the output image
• -f, --fg COLOR... - Foreground colors in hex format (e.g., f00, ff0000, #ff0000) or auto for automatic deduction
  • Optional in non-strict mode
  • Required in strict mode
• -b, --bg COLOR - Background color in hex format
  • If not specified, automatically detects the background color
• -s, --strict - Enable strict mode (requires --fg and restricts to specified colors only)
• -t, --threshold FLOAT - Color similarity threshold (0.0-1.0, default: 0.05)
  • When using --fg auto: colors within this threshold are considered similar during deduction
  • When using any --fg in non-strict mode: pixels within this threshold of a foreground color will use that color
• -h, --help - Print help information
• -v, --version - Print version information

How it works

The tool uses a color unmixing algorithm to determine how much of each foreground color and the background color contributed to each pixel. It then reconstructs the image with proper alpha transparency.

Non-Strict Mode (Default)

• Without foreground colors: Finds the optimal color and transparency for each pixel to perfectly reconstruct the image. Uses the minimum transparency needed for each pixel.
• With foreground colors:
  • Pixels within the threshold distance (default: 5%) of specified foreground colors use those colors with high opacity
  • Other pixels (like glows, shadows, or gradients) can use ANY color needed for perfect reconstruction
  • Always prioritizes correctness - every pixel is perfectly reconstructed

Strict Mode

• Requires foreground colors to be specified
• Restricts unmixing to only the specified colors
• Optimizes for maximum opacity while maintaining exact color accuracy
• Best for images with known, specific foreground colors

Automatic Color Deduction

When using the auto keyword, bgone:

1. Analyzes all colors in the image
2. Calculates what unmixed foreground colors could produce the observed blended colors
3. Evaluates different color combinations to find the best match
4. Optimizes for maximum opacity while preserving exact color accuracy

Project Structure

src/
├── main.rs        # CLI entry point
├── lib.rs         # Main image processing logic
├── color.rs       # Color types and utilities
├── background.rs  # Background detection
├── deduce.rs      # Automatic color deduction
└── unmix.rs       # Color unmixing algorithm

Building

cargo build --release

Running Locally

You can test the tool without installing it using cargo run:

# Debug mode (faster compilation, slower execution)
cargo run -- input.png output.png --fg ff0000

# Release mode (slower compilation, much faster execution)
cargo run --release -- input.png output.png --fg ff0000

The -- separates cargo's arguments from bgone's arguments.

Testing

The project includes a comprehensive testing framework that validates the color unmixing algorithm by:

1. Processing test images to remove backgrounds
2. Overlaying the results back onto the original background color
3. Comparing with the original image to ensure accuracy

Running Tests

# Run all tests
cargo test -- --nocapture

# Generate test fixtures (only needed once)
cargo test --test generate_fixtures -- --ignored

# Run integration tests with output
cargo test --test integration_test -- --nocapture

Test Results

The algorithm achieves excellent results:

• Simple cases (solid colors): 100% similarity, infinite PSNR
• Complex cases (gradients, multiple colors): 100% similarity, >50 dB PSNR

PSNR values above 40 dB indicate excellent quality reconstruction.

Test Coverage

• Unit tests: Cover color parsing, normalization, background detection, color unmixing algorithm, and image overlaying
• Integration tests: Test the full CLI workflow including auto-background detection
• Validation approach: Process image → overlay on background → compare with original