Metadata-Version: 2.4
Name: dvbackground
Version: 0.1.1
Summary: AI-powered Python image background remover and background replacement library with automatic background resizing and transparent PNG support.
Author: DVPackages
License-Expression: MIT
Keywords: background removal,background remover,remove background,remove image background,image background remover,image background removal,AI background removal,AI background remover,artificial intelligence background removal,background replacement,background replacer,replace background,replace image background,change background,change image background,image background replacement,photo background remover,photo background removal,photo background replacement,picture background remover,picture background removal,image processing,image processor,image editing,image manipulation,photo editing,photo processing,image segmentation,foreground extraction,foreground segmentation,image cutout,photo cutout,background cutout,transparent background,transparent image,transparent PNG,PNG background remover,PNG transparency,alpha channel,remove photo background,remove picture background,automatic background removal,automated background removal,AI image processing,AI image editing,AI image background,computer vision,computer-vision,Python image processing,Python image editing,Python image manipulation,Python background remover,Python background removal,Python background replacement,Python image background,Python computer vision,Python computer-vision,Python image processor,Python image library,Python image tool,Python photo processing,Python photo editing,rembg,Pillow,PIL,background changer,photo background changer,image background changer,background editor,image background editor,automatic background resizing,background image resizing,background image fitting,background fitting,aspect ratio,aspect ratio preservation,image resizing,image cropping,automatic image processing,photo background replacement,transparent photo,photo transparency,image transparency,subject extraction,foreground removal,background removal AI,AI photo editing,AI image editor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: rembg[cpu]>=2.0.0
Dynamic: license-file

# DVBackground

## AI-Powered Image Background Remover & Background Replacement for Python

**DVBackground** is an AI-powered Python image-processing library for
**removing image backgrounds, creating transparent images, and replacing
backgrounds with custom images**.

It provides a simple Python API that allows developers to integrate AI-powered
background removal and image background replacement into their own Python
applications, scripts, automation workflows, desktop applications, and image
processing pipelines.

Instead of manually editing images or depending on external online tools,
developers can process images directly from their Python applications.

---

# ✨ Features

- 🤖 AI-powered image background removal
- ✂️ Automatic foreground extraction
- 🪄 Transparent background generation
- 🌄 Custom image background replacement
- 📐 Automatic background resizing
- 🔲 Aspect-ratio-preserving background fitting
- 🖼️ Support for common image formats
- 🧩 Simple Python API
- 🐍 Designed for Python applications
- 💻 Useful for desktop and backend applications
- 🔄 Automatic image compositing
- 📦 PNG output with transparency
- 🧪 Automated tests included

---

# 🚀 Installation

Install DVBackground using pip:

```bash
pip install dvbackground
```

After installation:

```python
from dvbackground import remove_background, replace_background
```

---

# 🪄 Quick Start

DVBackground currently provides two main operations:

1. Remove an image background
2. Replace an image background

---

# 1. Remove an Image Background

Use `remove_background()` to automatically remove the background from an
image and create a transparent PNG.

```python
from dvbackground import remove_background

result = remove_background(
    "person.jpg",
    "person_no_background.png"
)

print(result)
```

### Processing flow

```text
Original Image
      ↓
AI Background Removal
      ↓
Foreground Extraction
      ↓
RGBA Image
      ↓
Transparent PNG
```

The subject remains while the detected background becomes transparent.

---

# 2. Replace an Image Background

Use `replace_background()` when you want to remove the original background
and place the subject on a different image.

```python
from dvbackground import replace_background

result = replace_background(
    "person.jpg",
    "beach.jpg",
    "person_on_beach.png"
)

print(result)
```

### Processing flow

```text
Original Image
      ↓
AI Background Removal
      ↓
Foreground Extraction
      ↓
Custom Background
      ↓
Automatic Background Fitting
      ↓
Image Composition
      ↓
Final PNG
```

---

# 📐 Automatic Background Resizing

One of the important features of DVBackground is automatic background fitting.

When replacing a background, the selected background image may have completely
different dimensions or aspect ratio from the original image.

For example:

```text
Foreground:
1000 × 1000

Background:
1920 × 1080
```

DVBackground automatically calculates the appropriate scale required for the
background to completely cover the foreground image.

The background is:

1. Scaled proportionally
2. Resized while preserving its aspect ratio
3. Cropped where necessary
4. Matched to the foreground dimensions
5. Composited behind the extracted subject

This prevents the replacement background from being unnecessarily stretched
or squashed.

### Example

```text
Original Background

┌──────────────────────────────┐
│                              │
│        Background Image      │
│                              │
└──────────────────────────────┘

              ↓

Scale while preserving aspect ratio

              ↓

┌────────────────────┐
│                    │
│    Target Area     │
│                    │
└────────────────────┘

              ↓

Crop excess area

              ↓

Final background
matching the foreground dimensions
```

---

# 🖼️ Supported Image Formats

DVBackground uses **Pillow** for image loading, conversion, resizing,
cropping, compositing, and saving.

Because of this, DVBackground can work with many image formats supported by
the installed Pillow version.

## Commonly supported formats

| Format | Extensions |
|---|---|
| JPEG | `.jpg`, `.jpeg` |
| PNG | `.png` |
| WebP | `.webp` |
| BMP | `.bmp` |
| GIF | `.gif` |
| TIFF | `.tif`, `.tiff` |
| ICO | `.ico` |
| PPM | `.ppm` |
| PGM | `.pgm` |
| PBM | `.pbm` |

Additional formats may also be supported depending on the installed Pillow
version and the specific image.

For the most reliable results, use:

- JPG
- JPEG
- PNG
- WEBP

---

# 📦 Output Format

DVBackground currently saves processed images as:

```text
PNG
```

PNG is used because it supports an alpha channel.

This allows background removal results to contain transparent pixels.

---

# 🧠 How Background Removal Works

At a high level:

```text
Input Image
     ↓
Image Loading
     ↓
AI Background Detection
     ↓
Foreground / Subject Extraction
     ↓
RGBA Conversion
     ↓
PNG Output
```

The library handles the image-processing steps required to turn the extracted
foreground into a usable image.

---

# 🖼️ How Background Replacement Works

When using `replace_background()`:

```text
Original Image
       │
       ▼
AI Background Removal
       │
       ▼
Foreground Subject
       │
       ├───────────────┐
       │               │
       ▼               ▼
Foreground       Custom Background
                       │
                       ▼
                Resize & Crop
                       │
                       ▼
                Match Dimensions
                       │
                       └───────┐
                               ▼
                       Alpha Compositing
                               │
                               ▼
                         Final PNG
```

---

# 📏 Aspect Ratio Preservation

DVBackground does not simply force the custom background into the target
dimensions.

Instead, it calculates the scale required for the background to completely
cover the target image.

For example:

```text
Background:
1920 × 1080

Target:
1000 × 1000
```

The background is resized proportionally and the excess area is cropped.

This helps avoid:

```text
❌ Stretched images
❌ Squashed images
❌ Distorted backgrounds
```

Instead:

```text
✅ Aspect ratio preserved
✅ Background covers target area
✅ Excess area cropped
```

---

# 🧩 Simple Python API

DVBackground is intentionally designed with a small public API.

## Remove background

```python
from dvbackground import remove_background

remove_background(
    "input.jpg",
    "output.png"
)
```

## Replace background

```python
from dvbackground import replace_background

replace_background(
    "person.jpg",
    "background.jpg",
    "result.png"
)
```

---

# 🎯 Use Cases

DVBackground can be used as a component inside many different Python
applications.

## E-commerce

Automatically process product photographs.

```text
Product Photo
     ↓
Background Removal
     ↓
Transparent Product Image
```

Useful for:

- Product catalogs
- Online stores
- Marketplace images
- Product photography
- Automated product processing

---

## Profile Pictures

Automatically remove unwanted backgrounds from profile or portrait images.

---

## Product Photography

Create clean product cutouts and place products over custom backgrounds.

---

## Image Automation

Integrate background removal into automated Python workflows.

For example:

```text
Input Folder
     ↓
Process Images
     ↓
Remove Backgrounds
     ↓
Save Transparent PNGs
```

---

## Desktop Applications

DVBackground can be integrated into Python desktop applications built with
frameworks such as:

- Tkinter
- CustomTkinter
- PyQt
- PySide
- wxPython

---

## Backend Applications

The library can also be used as part of a Python backend or image-processing
service.

---

## Computer Vision

The extracted foreground can be used as part of larger computer-vision or
image-processing workflows.

---

## Graphic and Design Workflows

Generate transparent image cutouts that can then be used in other design
applications.

---

# 🔧 Technologies

DVBackground is built using Python and the following major libraries.

## Python

The main programming language used by DVBackground.

## Pillow

Pillow is used for:

- Image loading
- Image conversion
- Image resizing
- Image cropping
- Image compositing
- Image saving
- Image format handling

## rembg

`rembg` provides the AI-powered background removal functionality.

---

# ⚙️ Requirements

DVBackground requires:

- Python 3.10 or newer
- Pillow
- rembg

These dependencies are installed automatically when installing DVBackground
from PyPI.

```bash
pip install dvbackground
```

---

# 💡 Basic Example

A complete example:

```python
from dvbackground import (
    remove_background,
    replace_background
)


# Remove the background
remove_background(
    "person.jpg",
    "person_transparent.png"
)


# Replace the background
replace_background(
    "person.jpg",
    "beach.jpg",
    "person_on_beach.png"
)
```

---

# 🧪 Testing

DVBackground includes automated tests covering:

- Background removal
- Background replacement
- Output file creation
- PNG output
- RGBA conversion
- Missing input image handling
- Missing background image handling

Run the complete test suite:

```bash
python -m pytest
```

Expected result:

```text
4 passed
```

---

# 🛠️ Development

Clone the project and install it in editable mode:

```bash
pip install -e .
```

Run the tests:

```bash
python -m pytest
```
---

# 📋 Current API

The current public API contains:

```python
from dvbackground import remove_background
from dvbackground import replace_background
```

## `remove_background()`

Removes the background from an image and saves a transparent PNG.

## `replace_background()`

Removes the original background, automatically fits a custom background image,
and creates a final PNG.

---

# 🚧 Project Status

DVBackground is currently in **Alpha** development.

The current release focuses on image background processing.

### Current functionality

- ✅ AI background removal
- ✅ Transparent PNG generation
- ✅ Custom background replacement
- ✅ Automatic background resizing
- ✅ Aspect-ratio-preserving background fitting
- ✅ PNG output
- ✅ Common image format support
- ✅ Automated tests

---

# 🤝 Contributing

Suggestions, bug reports, feature requests, and contributions are welcome.

As the project develops, contribution guidelines and project resources will
be added.

---

# 📄 License

DVBackground is released under the MIT License.

See the `LICENSE` file for the complete license text.
