Metadata-Version: 2.4
Name: resizebox-background-remover
Version: 1.0.0
Summary: AI background removal for Python by ResizeBox.com (https://resizebox.com/remove-background).
Author: ResizeBox
License-Expression: MIT
Project-URL: Homepage, https://resizebox.com/remove-background
Project-URL: Documentation, https://resizebox.com/remove-background
Project-URL: Privacy, https://resizebox.com/privacy-policy
Keywords: background remover,remove background,image segmentation,transparent background,onnx,pillow,png,resizebox
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface-hub<2,>=0.34
Requires-Dist: numpy<3,>=1.26
Requires-Dist: onnxruntime<2,>=1.20
Requires-Dist: Pillow<13,>=10.4
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# resizebox-background-remover

AI background removal for Python by ResizeBox.com: https://resizebox.com/remove-background

Built by [ResizeBox.com](https://resizebox.com/remove-background), a privacy-focused image toolkit. Images are processed locally in your Python process.

## Install

```bash
pip install resizebox-background-remover
```

## Remove a background

```python
from resizebox_background_remover import remove_background

result = remove_background(
    "input.jpg",
    "output.png",
)

print(result.width, result.height)
```

The first run downloads the quantized `onnx-community/ormbg-ONNX` model from Hugging Face and caches it locally. The model is then executed locally with ONNX Runtime. Your image is not uploaded to ResizeBox or Hugging Face.

## Work with bytes

```python
from resizebox_background_remover import remove_background

with open("input.webp", "rb") as file:
    source = file.read()

result = remove_background(source)

with open("result.png", "wb") as file:
    file.write(result.data)
```

`bytes`, `bytearray`, binary file-like objects, `str` paths, and `pathlib.Path` are supported as inputs.

## Solid background color

Transparent PNG is the default output. A six-digit hex color can be used instead:

```python
result = remove_background(
    "input.png",
    "white-background.png",
    background="#FFFFFF",
)
```

## Preload the model

Download and initialize the model before processing the first image:

```python
from resizebox_background_remover import preload_model

model_path = preload_model()
print(model_path)
```

You can provide a custom Hugging Face cache directory:

```python
preload_model(cache_dir="./model-cache")
```

## ONNX Runtime providers

By default, ONNX Runtime chooses the providers available in the current Python environment. You can explicitly select providers when needed:

```python
result = remove_background(
    "input.jpg",
    providers=["CPUExecutionProvider"],
)
```

## Result

Every call returns a `BackgroundRemovalResult`:

```python
result.data        # PNG bytes
result.width
result.height
result.mime_type   # "image/png"
result.filename
result.output_path
```

## Errors

Validation, model download, model initialization, inference, and encoding failures raise `BackgroundRemoverError` with a machine-readable `code`.

```python
from resizebox_background_remover import BackgroundRemoverError, remove_background

try:
    remove_background("input.jpg")
except BackgroundRemoverError as error:
    print(error.code)
```

## Input and output

Supported input formats:

- JPEG
- PNG
- WebP

Output format:

- PNG with transparency by default
- PNG composited onto a custom solid background when requested

The package validates decoded image format, file size, image dimensions, and model output before returning a result.

## Model

The model is not bundled into the PyPI package. On first use, the package downloads:

`onnx-community/ormbg-ONNX/onnx/model_quantized.onnx`

The model repository is licensed separately under Apache-2.0. The Python package code is licensed under MIT.

## Privacy

Image processing runs locally in your Python process. Image content is not uploaded to ResizeBox or Hugging Face. Hugging Face is contacted only to download the AI model file.

Website: https://resizebox.com/remove-background

Privacy Policy: https://resizebox.com/privacy-policy

## License

MIT
