0
# Background Removal
1

2
Core background removal functionality that provides the main API for removing backgrounds from images using AI models. Supports multiple input/output formats, advanced alpha matting, and various post-processing options.
3

4
## Capabilities
5

6
### Primary Background Removal
7

8
The main function for removing backgrounds from images with comprehensive configuration options.
9

10
```python { .api }
11
def remove(
12
    data: Union[bytes, PILImage, np.ndarray],
13
    alpha_matting: bool = False,
14
    alpha_matting_foreground_threshold: int = 240,
15
    alpha_matting_background_threshold: int = 10,
16
    alpha_matting_erode_size: int = 10,
17
    session: Optional[BaseSession] = None,
18
    only_mask: bool = False,
19
    post_process_mask: bool = False,
20
    bgcolor: Optional[Tuple[int, int, int, int]] = None,
21
    force_return_bytes: bool = False,
22
    *args,
23
    **kwargs
24
) -> Union[bytes, PILImage, np.ndarray]:
25
    """
26
    Remove the background from an input image.
27

28
    Parameters:
29
    - data: Input image as bytes, PIL Image, or numpy array
30
    - alpha_matting: Use advanced alpha matting for smoother edges
31
    - alpha_matting_foreground_threshold: Threshold for foreground detection (0-255)
32
    - alpha_matting_background_threshold: Threshold for background detection (0-255)
33
    - alpha_matting_erode_size: Erosion size for alpha matting refinement
34
    - session: Specific model session to use (defaults to u2net)
35
    - only_mask: Return only the binary mask instead of cutout
36
    - post_process_mask: Apply morphological operations to smooth mask
37
    - bgcolor: RGBA background color tuple for non-transparent output
38
    - force_return_bytes: Force output as bytes regardless of input type
39

40
    Returns:
41
    Processed image in same format as input (or bytes if force_return_bytes=True)
42
    """
43
```
44

45
**Usage Examples:**
46

47
```python
48
from rembg import remove
49
from PIL import Image
50

51
# Basic usage
52
input_img = Image.open('photo.jpg')
53
result = remove(input_img)
54

55
# With alpha matting for higher quality
56
result = remove(input_img, alpha_matting=True)
57

58
# Get only the mask
59
mask = remove(input_img, only_mask=True)
60

61
# Apply custom background color
62
result = remove(input_img, bgcolor=(255, 255, 255, 255))  # White background
63

64
# Process bytes directly
65
with open('input.jpg', 'rb') as f:
66
    input_bytes = f.read()
67
output_bytes = remove(input_bytes)
68
```
69

70
### Advanced Cutout Methods
71

72
Specialized cutout functions for different quality levels and use cases.
73

74
```python { .api }
75
def alpha_matting_cutout(
76
    img: PILImage,
77
    mask: PILImage,
78
    foreground_threshold: int,
79
    background_threshold: int,
80
    erode_structure_size: int
81
) -> PILImage:
82
    """
83
    Perform alpha matting cutout for high-quality edge refinement.
84

85
    Parameters:
86
    - img: Input PIL image
87
    - mask: Binary mask PIL image
88
    - foreground_threshold: Threshold for foreground pixels (0-255)
89
    - background_threshold: Threshold for background pixels (0-255)
90
    - erode_structure_size: Size of erosion structure for refinement
91

92
    Returns:
93
    PIL Image with refined alpha channel
94
    """
95

96
def naive_cutout(img: PILImage, mask: PILImage) -> PILImage:
97
    """
98
    Perform simple cutout using mask composite operation.
99

100
    Parameters:
101
    - img: Input PIL image
102
    - mask: Binary mask PIL image
103

104
    Returns:
105
    PIL Image with background removed
106
    """
107

108
def putalpha_cutout(img: PILImage, mask: PILImage) -> PILImage:
109
    """
110
    Apply mask directly as alpha channel to image.
111

112
    Parameters:
113
    - img: Input PIL image
114
    - mask: Binary mask PIL image
115

116
    Returns:
117
    PIL Image with mask applied as alpha channel
118
    """
119
```
120

121
### Mask Post-Processing
122

123
Functions for improving mask quality through morphological operations.
124

125
```python { .api }
126
def post_process(mask: np.ndarray) -> np.ndarray:
127
    """
128
    Post-process mask for smooth boundaries using morphological operations.
129

130
    Applies opening operation followed by Gaussian blur and threshold
131
    to create smoother mask boundaries.
132

133
    Parameters:
134
    - mask: Binary numpy mask array
135

136
    Returns:
137
    Processed numpy mask array with smoother boundaries
138
    """
139
```
140

141
### Model Download Management
142

143
Utility for downloading AI models used in background removal.
144

145
```python { .api }
146
def download_models(models: tuple[str, ...]) -> None:
147
    """
148
    Download AI models for background removal.
149

150
    Parameters:
151
    - models: Tuple of model names to download. If empty, downloads all models.
152

153
    Available models: u2net, u2netp, u2net_human_seg, u2net_cloth_seg, 
154
    u2net_custom, birefnet_general, birefnet_general_lite, birefnet_portrait,
155
    birefnet_dis, birefnet_hrsod, birefnet_cod, birefnet_massive, dis_anime,
156
    dis_custom, dis_general_use, sam, silueta, bria_rmbg, ben_custom
157
    """
158
```
159

160
## Error Handling
161

162
The `remove()` function raises `ValueError` for unsupported input types:
163

164
```python
165
try:
166
    result = remove(unsupported_data)
167
except ValueError as e:
168
    print(f"Unsupported input type: {e}")
169
    # Use force_return_bytes=True as fallback
170
    result = remove(unsupported_data, force_return_bytes=True)
171
```
172

173
## Performance Considerations
174

175
- **Input Type**: PIL Images are most efficient, numpy arrays require conversion
176
- **Alpha Matting**: Significantly slower but produces higher quality results
177
- **Model Selection**: Different models have different speed/quality tradeoffs
178
- **GPU Acceleration**: Use `pip install rembg[gpu]` for CUDA support
179
- **Batch Processing**: Reuse sessions for multiple images to avoid model reloading