background-remover-model 1.0.1
A FastAPI-based API for removing backgrounds from images and videos using backgroundremover
Requires Python: >=3.10
Keywords: background-removal, image-processing, video-processing, fastapi, backgroundremover

# Background Remover - Full Stack Application

A production-ready full-stack application for removing backgrounds from images and videos using the [backgroundremover](https://github.com/nadermx/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](https://ffmpeg.org/download.html)

### 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:**
```bash
sudo apt install python3-venv -y
```

**macOS:**
```bash
# venv is usually pre-installed with Python
python3 --version
```

**Windows:**
```bash
# venv is usually pre-installed with Python
python --version
```

#### Step 2: Create Virtual Environment

```bash
python3 -m venv bgremover-env
```

#### Step 3: Activate Virtual Environment

**Linux/macOS:**
```bash
source bgremover-env/bin/activate
```

**Windows:**
```bash
bgremover-env\Scripts\activate
```

#### Step 4: Install the Package

```bash
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)

```bash
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:

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

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

```python
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)
   ```bash
   # 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**
   ```bash
   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](https://ffmpeg.org/download.html)

4. **Run the API server**
   ```bash
   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)
   ```bash
   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**
   ```bash
   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**
   ```bash
   cd backend
   ```

2. **Create virtual environment**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   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](https://ffmpeg.org/download.html)

5. **Run the server**
   ```bash
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   ```

#### Frontend

1. **Navigate to frontend directory**
   ```bash
   cd frontend
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Run development server**
   ```bash
   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:**
```json
{
  "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
```bash
# Start backend
cd backend
uvicorn app.main:app --reload

# Run cleanup
python -m app.utils.file_cleanup
```

### Frontend
```bash
# Start dev server
cd frontend
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

## Docker Commands

```bash
# 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](https://github.com/nadermx/backgroundremover) 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](https://github.com/nadermx/backgroundremover/issues)
- **This application**: Open an issue in this repository

## Acknowledgments

- [backgroundremover](https://github.com/nadermx/backgroundremover) - The core library for background removal
- FastAPI - Modern Python web framework
- React & Vite - Frontend framework and build tool