Tools/rembg/README.md

✂️ RemoveBG Studio (Images & Video with FFmpeg)

A powerful, high-performance background removal tool supporting single images, batch image folders, and video files with lossless frame extraction using FFmpeg. Ships as a native Windows app with a modern WebView2 UI, plus a scriptable CLI.

---

🖥️ Native App (Recommended)

native/ is a small C++ host application: a native window that embeds a WebView2 view (Chromium, via the OS-provided WebView2 Runtime) for the UI, and spawns the Python engine as a background sidecar process it talks to over a newline-delimited JSON protocol on stdin/stdout.

native/RemoveBGStudio.exe   (native C++ host + WebView2 UI, no console)
        │
        ├── web/index.html, styles.css, app.js   (the actual UI)
        │
        └── spawns → .venv/Scripts/python.exe -u core/sidecar.py
                       (rembg + FFmpeg engine, JSON-over-stdio)

The C++ side never talks to rembg/FFmpeg directly — all of that logic still lives in core/processor.py and core/ffmpeg_utils.py, unchanged. core/sidecar.py is the only new piece of Python: it wraps those modules in a JSON request/response loop so the native UI can drive them.

Building the native app

Requirements: CMake 3.20+, MSVC (Visual Studio 2022 Build Tools or full VS), PowerShell, make, Windows 10/11 x64. No vcpkg or NuGet install needed — native/third_party/fetch-webview2.ps1 pulls the WebView2 SDK headers/libs straight from nuget.org the first time they're needed. The nlohmann/json single header is small enough to vendor directly and lives at native/third_party/json/.

make sync   # uv sync — installs the Python engine's dependencies
make run    # fetches WebView2 SDK (first run only) → configures → builds → launches

Other targets: make build (build only), make fetch-deps (just the WebView2 SDK fetch), make clean (removes native/build/).

The exe locates the repo root by walking up from its own path looking for pyproject.toml, then launches the sidecar with .venv/Scripts/python.exe if that venv exists, otherwise falls back to python on PATH.

For a console-attached debug variant with DevTools enabled (right-click → Inspect in the WebView2 UI) and sidecar stderr visible, configure manually with -DRBG_CONSOLE=ON:

cmake -S native -B native/build -G "Visual Studio 17 2022" -A x64 -DRBG_CONSOLE=ON
cmake --build native/build --config Release

---

🌟 Key Features

• Single & Batch Image Support: Remove backgrounds from a single image or an entire folder of images in PNG, WebP, JPG, BMP, or TIFF.
• FFmpeg Lossless Video Processing:
  • Extracts frames in 100% Lossless PNG format (-c:v png) to ensure zero quality degradation during extraction.
  • Preserves original audio streams from input videos.
  • Supports exporting to QuickTime MOV (ProRes 4444 with Alpha Channel), WebM VP9 (Alpha Transparency), MP4 H.264 (Solid / Green Screen keying), or raw PNG Frame Sequences.
• Multiple AI Models:
  • u2net: General purpose default model.
  • u2netp: Lightweight and fast model.
  • u2net_human_seg: Optimized for human portraits & people.
  • u2net_cloth_seg: Optimized for fashion & clothing.
  • isnet-general-use: High detail and crisp edge detection.
  • birefnet-general: State-of-the-art high-precision background removal.
• Background Replacement: Replace background with transparency, green screen keying (#00FF00), solid white, solid black, or any custom hex color.
• Alpha Matting: Optional advanced alpha matting for fine details (hair, fur, transparent fabrics).
• Dual Interface: Use either the native GUI (native/) or the scriptable CLI (removebg.py).

---

🚀 Quick Start

1. Requirements

Ensure Python 3.8+ and FFmpeg are installed on your system.

Install required dependencies:

pip install -r requirements.txt

---

💻 Usage

⌨️ Command Line Interface (CLI)

1. Single Image Processing

# Output defaults to input_nobg.png
python removebg.py -i portrait.jpg

# Specify output destination & custom model
python removebg.py -i portrait.jpg -o result.png --model isnet-general-use

2. Batch Image Processing

# Process all images in a directory
python removebg.py -b ./my_photos -o ./no_bg_photos

# Batch processing with green screen background replacement & WebP output
python removebg.py -b ./my_photos -o ./green_photos --bg-color green --format webp

3. Video Processing (FFmpeg Frame Extraction & Reassembly)

# Extract frames, remove background, reassemble as transparent MOV ProRes 4444:
python removebg.py -v input.mp4 -o output_transparent.mov --export-format mov_transparent

# Video with Green Screen background keying:
python removebg.py -v dance.mp4 -o dance_green.mp4 --export-format mp4_solid --bg-color green

# Export as WebM with alpha transparency:
python removebg.py -v video.mp4 -o video_alpha.webm --export-format webm_transparent

# Export processed frames as a PNG sequence folder:
python removebg.py -v clip.mp4 -o ./processed_frames --export-format png_sequence

---

⚙️ CLI Options Reference

Argument	Short	Description
--image	-i	Input image file path(s)
--batch	-b	Input directory containing images for batch processing
--video	-v	Input video file path for FFmpeg frame extraction & processing
--output	-o	Output file path or directory
--model	-m	AI model selection (u2net, u2netp, u2net_human_seg, isnet-general-use, birefnet-general)
--bg-color	-bg	Background replacement (green, white, black, or Hex #00FF00)
--alpha-matting	-am	Enable alpha matting for finer edge detail (hair/fur)
--format		Output image format (png, webp, jpg)
--fps		Target frame rate for video frame extraction (0 = original FPS)
--export-format		Video reassembly format (mov_transparent, webm_transparent, mp4_solid, png_sequence)

---

🎨 Frame Extraction & Quality Guarantee

When processing video files:

1. FFmpeg extracts frames using -c:v png -pred mixed into a 24-bit/32-bit PNG sequence, ensuring zero compression loss during frame extraction.
2. The AI background removal engine processes each PNG frame cleanly.
3. FFmpeg reassembles frames with original audio synced into your target codec (ProRes 4444 / VP9 / H.264).