background-remover-model 1.0.1

A FastAPI-based API for removing backgrounds from images and videos using backgroundremover

Background Remover - Full Stack Application

A production-ready full-stack application for removing backgrounds from images and videos using the backgroundremover library.

Installation

Prerequisites

• Python 3.10 or higher
• FFmpeg (for video processing)

Note: FFmpeg must be installed separately on your system:

• Ubuntu/Debian: sudo apt-get install ffmpeg
• macOS: brew install ffmpeg
• Windows: Download from ffmpeg.org

Install from PyPI

The recommended way to install the Background Remover Model is using a virtual environment:

Step 1: Install Python venv (if not already installed)

Ubuntu/Debian:

sudo apt install python3-venv -y

macOS:

# venv is usually pre-installed with Python
python3 --version

Windows:

# venv is usually pre-installed with Python
python --version

Step 2: Create Virtual Environment

python3 -m venv bgremover-env

Step 3: Activate Virtual Environment

Linux/macOS:

source bgremover-env/bin/activate

Windows:

bgremover-env\Scripts\activate

Step 4: Install the Package

pip install background-remover-model

This will install the package and all its dependencies. After installation, you can import and use the API in your Python projects.

Step 5: Deactivate Virtual Environment (when done)

deactivate

Note: Always activate your virtual environment before using the package. You can run Python scripts inside the activated environment.

Quick Start (After Installation)

Important: Make sure your virtual environment is activated before running the server:

# Activate virtual environment (if not already activated)
source bgremover-env/bin/activate  # Linux/macOS
# or
bgremover-env\Scripts\activate      # Windows

Once installed and activated, you can run the API server:

# Run the FastAPI server
uvicorn app.main:app --host 0.0.0.0 --port 8000

Or use it as a Python package in your code:

from app.main import app
from app.routers import image_router, video_router

# The FastAPI app is ready to use
# Access API docs at http://localhost:8000/docs

Features

• 🖼️ Image Background Removal: Remove backgrounds from images with various models
• 🎥 Video Background Removal: Process videos to remove backgrounds
• 🎨 Advanced Options: Alpha matting, custom background colors, background images
• 📊 Real-time Processing: Visual feedback during processing
• 🎯 Before/After Preview: Side-by-side comparison of original and processed files
• 📥 Easy Download: One-click download of processed files

Tech Stack

Backend

• Python 3.10+
• FastAPI
• backgroundremover
• PyTorch (CPU)
• FFmpeg
• Celery (optional for async processing)
• Redis (optional, for Celery)

Frontend

• React 18
• Vite
• TailwindCSS
• Axios

Project Structure

.
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application
│   │   ├── routers/             # API route handlers
│   │   │   ├── image_router.py
│   │   │   └── video_router.py
│   │   ├── services/            # Business logic
│   │   │   └── background_remover.py
│   │   ├── utils/               # Utility functions
│   │   │   └── file_cleanup.py
│   │   └── models/              # Pydantic models
│   │       └── schemas.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/          # React components
│   │   │   ├── FileUploader.jsx
│   │   │   ├── OptionsPanel.jsx
│   │   │   └── ResultViewer.jsx
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── nginx.conf
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Quick Start

Option 1: Install from PyPI (Recommended for API Usage)

1. Set up virtual environment (see Installation section above)

   # Install venv if needed
   sudo apt install python3-venv -y  # Ubuntu/Debian
   
   # Create and activate virtual environment
   python3 -m venv bgremover-env
   source bgremover-env/bin/activate
   

2. Install the package

   pip install background-remover-model
   

3. Install FFmpeg (required for video processing)

   • Ubuntu/Debian: sudo apt-get install ffmpeg
   • macOS: brew install ffmpeg
   • Windows: Download from ffmpeg.org

4. Run the API server

   uvicorn app.main:app --host 0.0.0.0 --port 8000
   

5. Access the API

   • API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

6. Deactivate virtual environment (when done)

   deactivate
   

Option 2: Using Docker (Full Stack Application)

Prerequisites

• Docker and Docker Compose
• (Optional) Node.js 18+ and Python 3.10+ for local development

1. Clone or navigate to the project directory

2. Start the application

   docker-compose up --build
   

3. Access the application

   • Frontend: http://localhost
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Local Development

Backend

1. Navigate to backend directory

   cd backend
   

2. Create virtual environment

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Install FFmpeg (if not already installed)

   • Ubuntu/Debian: sudo apt-get install ffmpeg
   • macOS: brew install ffmpeg
   • Windows: Download from ffmpeg.org

5. Run the server

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

Frontend

1. Navigate to frontend directory

   cd frontend
   

2. Install dependencies

   npm install
   

3. Run development server

   npm run dev
   

4. Access the app

   • Frontend: http://localhost:5173

API Endpoints

POST /remove-image

Remove background from an uploaded image.

Request:

• file (multipart/form-data): Image file
• model (optional): Model to use (u2net, u2netp, u2net_human_seg)
• alpha_matting (optional): Enable alpha matting (boolean)
• alpha_matting_foreground_threshold (optional): Foreground threshold (0-255)
• alpha_matting_background_threshold (optional): Background threshold (0-255)
• alpha_matting_erode_structure_size (optional): Erode structure size
• alpha_matting_base_size (optional): Base size for alpha matting
• background_color (optional): Hex color code (e.g., "#FF0000")
• background_image (optional): Background image file

Response:

• Processed image file (PNG)

POST /remove-video

Remove background from an uploaded video.

Request:

• file (multipart/form-data): Video file
• model (optional): Model to use
• tv (optional): TV mode flag (boolean)
• mk (optional): Masks only flag (boolean)
• tov (optional): Transparent output video flag (boolean)
• toi (optional): Transparent output images flag (boolean)
• gb (optional): Green background flag (boolean)
• wn (optional): White background flag (boolean)
• fr (optional): Frame rate (float)
• fl (optional): Frame limit (float)
• background_color (optional): Hex color code
• background_image (optional): Background image file

Response:

• Processed video file (MP4)

GET /health

Health check endpoint.

Response:

{
  "status": "healthy"
}

Usage

1. Upload a file: Drag and drop or click to browse for an image or video
2. Configure options: Select model, enable alpha matting, set background color/image
3. Process: Click "Remove Background" to start processing
4. View results: See side-by-side comparison of original and processed files
5. Download: Click "Download Result" to save the processed file

Models

• u2net: Default model, good general-purpose performance
• u2netp: Lightweight model, faster processing
• u2net_human_seg: Optimized for human segmentation

Advanced Options

Alpha Matting

Improves edge quality for better results, especially for fine details like hair.

Background Replacement

• Background Color: Replace background with a solid color (hex format)
• Background Image: Replace background with another image

Video Options

• TV Mode (-tv): Optimize for TV/video content
• Masks Only (-mk): Generate masks only
• Transparent Output: Create transparent backgrounds
• Frame Rate/Limit: Control video processing parameters

File Cleanup

The application automatically cleans up temporary files older than 24 hours. You can manually trigger cleanup by calling the cleanup service.

Troubleshooting

Backend Issues

1. FFmpeg not found

   • Ensure FFmpeg is installed in the Docker container or system
   • Check Dockerfile includes FFmpeg installation

2. Out of memory

   • Large videos may require more memory
   • Consider processing smaller files or increasing Docker memory limits

3. Processing fails

   • Check file format is supported
   • Verify model files are downloaded (first run may download models)

Frontend Issues

1. CORS errors

   • Update CORS_ORIGINS in .env file
   • Ensure backend is running and accessible

2. Upload fails

   • Check file size limits (configured in nginx.conf)
   • Verify backend is running

Development Scripts

Backend

# Start backend
cd backend
uvicorn app.main:app --reload

# Run cleanup
python -m app.utils.file_cleanup

Frontend

# Start dev server
cd frontend
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Docker Commands

# Build and start all services
docker-compose up --build

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild specific service
docker-compose build backend
docker-compose up -d backend

Environment Variables

Copy .env.example to .env and configure:

• CORS_ORIGINS: Allowed CORS origins (comma-separated)
• REDIS_URL: Redis connection URL (if using Celery)
• CELERY_BROKER_URL: Celery broker URL
• CELERY_RESULT_BACKEND: Celery result backend URL

License

This project uses the backgroundremover library. Please refer to the backgroundremover license for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues related to:

• backgroundremover library: GitHub Issues
• This application: Open an issue in this repository

Acknowledgments

• backgroundremover - The core library for background removal
• FastAPI - Modern Python web framework
• React & Vite - Frontend framework and build tool