feat(rembg): add RemoveBG Studio - native background removal app
C++ WebView2 host app driving a Python/rembg engine as a JSON-stdio sidecar, with live before/after preview for images and video frames. Also includes the original CLI (removebg.py) built on the same core/ engine. The WebView2 SDK is fetched on demand via native/third_party/fetch-webview2.ps1 (wired into the Makefile) rather than vendored, since it's ~15MB of prebuilt/generated Microsoft SDK content. A Makefile provides make sync/build/run/clean as the standard entry points.
This commit is contained in:
+137
@@ -0,0 +1,137 @@
|
||||
# ✂️ 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/`.
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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](https://ffmpeg.org/) are installed on your system.
|
||||
|
||||
Install required dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 Usage
|
||||
|
||||
### ⌨️ Command Line Interface (CLI)
|
||||
|
||||
#### 1. Single Image Processing
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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).
|
||||
Reference in New Issue
Block a user