0
# Utility Functions
1
2
Image processing utilities that support the core background removal functionality. These functions handle image manipulation, orientation correction, background application, and specialized cutout operations.
3
4
## Capabilities
5
6
### Image Orientation
7
8
Correct image orientation based on EXIF metadata to ensure proper processing.
9
10
```python { .api }
11
def fix_image_orientation(img: PILImage) -> PILImage:
12
"""
13
Fix the orientation of the image based on its EXIF data.
14
15
Automatically rotates and flips the image according to the EXIF orientation
16
tag to ensure the image displays correctly.
17
18
Parameters:
19
- img: Input PIL image that may have orientation metadata
20
21
Returns:
22
PIL Image with corrected orientation
23
"""
24
```
25
26
**Usage Example:**
27
28
```python
29
from rembg.bg import fix_image_orientation
30
from PIL import Image
31
32
# Fix orientation for camera photos
33
image = Image.open('camera_photo.jpg')
34
corrected_image = fix_image_orientation(image)
35
```
36
37
### Background Color Application
38
39
Apply solid background colors to images with transparency.
40
41
```python { .api }
42
def apply_background_color(
43
img: PILImage,
44
color: Tuple[int, int, int, int]
45
) -> PILImage:
46
"""
47
Apply the specified background color to a transparent image.
48
49
Creates a new background layer with the specified RGBA color and
50
composites the input image over it.
51
52
Parameters:
53
- img: Input PIL image (should have alpha channel)
54
- color: RGBA color tuple (red, green, blue, alpha) with values 0-255
55
56
Returns:
57
PIL Image with background color applied
58
"""
59
```
60
61
**Usage Examples:**
62
63
```python
64
from rembg.bg import apply_background_color
65
from PIL import Image
66
67
# Apply white background
68
transparent_img = Image.open('cutout.png')
69
white_bg = apply_background_color(transparent_img, (255, 255, 255, 255))
70
71
# Apply colored background
72
blue_bg = apply_background_color(transparent_img, (0, 100, 200, 255))
73
74
# Apply semi-transparent background
75
semi_bg = apply_background_color(transparent_img, (255, 255, 255, 128))
76
```
77
78
### Image Concatenation
79
80
Combine multiple images vertically for comparison or batch visualization.
81
82
```python { .api }
83
def get_concat_v(img1: PILImage, img2: PILImage) -> PILImage:
84
"""
85
Concatenate two images vertically.
86
87
Creates a new image with img1 on top and img2 below it.
88
89
Parameters:
90
- img1: First (top) PIL image
91
- img2: Second (bottom) PIL image to concatenate
92
93
Returns:
94
PIL Image with both images concatenated vertically
95
"""
96
97
def get_concat_v_multi(imgs: List[PILImage]) -> PILImage:
98
"""
99
Concatenate multiple images vertically.
100
101
Stacks all images in the list from top to bottom in order.
102
103
Parameters:
104
- imgs: List of PIL images to concatenate
105
106
Returns:
107
PIL Image with all images concatenated vertically
108
"""
109
```
110
111
**Usage Examples:**
112
113
```python
114
from rembg.bg import get_concat_v, get_concat_v_multi
115
from PIL import Image
116
117
# Concatenate two images
118
original = Image.open('original.jpg')
119
processed = Image.open('processed.png')
120
comparison = get_concat_v(original, processed)
121
122
# Concatenate multiple images
123
images = [Image.open(f'step_{i}.png') for i in range(1, 5)]
124
process_steps = get_concat_v_multi(images)
125
```
126
127
### Alpha Matting Operations
128
129
Advanced cutout operations for high-quality edge refinement.
130
131
```python { .api }
132
def alpha_matting_cutout(
133
img: PILImage,
134
mask: PILImage,
135
foreground_threshold: int,
136
background_threshold: int,
137
erode_structure_size: int
138
) -> PILImage:
139
"""
140
Perform alpha matting cutout for smooth, natural edges.
141
142
Uses advanced alpha matting algorithms to create smooth transitions
143
between foreground and background based on trimap generation.
144
145
Parameters:
146
- img: Input PIL image to cut out
147
- mask: Binary mask PIL image indicating foreground/background
148
- foreground_threshold: Pixel values above this are definitely foreground (0-255)
149
- background_threshold: Pixel values below this are definitely background (0-255)
150
- erode_structure_size: Size of erosion structure for trimap refinement
151
152
Returns:
153
PIL Image with refined alpha channel and smooth edges
154
"""
155
156
def naive_cutout(img: PILImage, mask: PILImage) -> PILImage:
157
"""
158
Perform simple cutout using basic image compositing.
159
160
Fast cutout operation that directly applies the mask without
161
edge refinement. Suitable for simple cases or when speed is critical.
162
163
Parameters:
164
- img: Input PIL image to cut out
165
- mask: Binary mask PIL image
166
167
Returns:
168
PIL Image with background removed using simple compositing
169
"""
170
171
def putalpha_cutout(img: PILImage, mask: PILImage) -> PILImage:
172
"""
173
Apply mask directly as the alpha channel of the image.
174
175
Directly assigns the mask as the alpha channel, preserving
176
original pixel values while making background transparent.
177
178
Parameters:
179
- img: Input PIL image
180
- mask: Binary mask PIL image to use as alpha channel
181
182
Returns:
183
PIL Image with mask applied as alpha channel
184
"""
185
```
186
187
**Usage Examples:**
188
189
```python
190
from rembg.bg import alpha_matting_cutout, naive_cutout, putalpha_cutout
191
from PIL import Image
192
193
# Load image and mask
194
image = Image.open('input.jpg')
195
mask = Image.open('mask.png')
196
197
# High-quality cutout with alpha matting
198
refined = alpha_matting_cutout(
199
image, mask,
200
foreground_threshold=240,
201
background_threshold=10,
202
erode_structure_size=5
203
)
204
205
# Fast simple cutout
206
simple = naive_cutout(image, mask)
207
208
# Direct alpha application
209
alpha_applied = putalpha_cutout(image, mask)
210
```
211
212
### Mask Post-Processing
213
214
Improve mask quality through morphological operations and smoothing.
215
216
```python { .api }
217
def post_process(mask: np.ndarray) -> np.ndarray:
218
"""
219
Post-process binary mask for smoother boundaries.
220
221
Applies morphological opening followed by Gaussian blur and
222
re-thresholding to create smoother, more natural mask edges.
223
Based on research for improved boundary quality.
224
225
Parameters:
226
- mask: Binary numpy array representing the mask
227
228
Returns:
229
Processed numpy array with smoother boundaries and reduced noise
230
"""
231
```
232
233
**Usage Example:**
234
235
```python
236
from rembg.bg import post_process
237
import numpy as np
238
from PIL import Image
239
240
# Process a rough mask
241
rough_mask = np.array(Image.open('rough_mask.png'))
242
smooth_mask = post_process(rough_mask)
243
result_image = Image.fromarray(smooth_mask)
244
```
245
246
## Enum Types
247
248
```python { .api }
249
from enum import Enum
250
251
class ReturnType(Enum):
252
"""Enumeration for specifying return type format."""
253
BYTES = 0 # Return as bytes
254
PILLOW = 1 # Return as PIL Image
255
NDARRAY = 2 # Return as numpy array
256
```
257
258
## Integration with Core Functions
259
260
These utilities are used internally by the main `remove()` function but can also be used independently for custom processing workflows:
261
262
```python
263
from rembg import remove, new_session
264
from rembg.bg import fix_image_orientation, apply_background_color, post_process
265
from PIL import Image
266
import numpy as np
267
268
# Custom processing workflow
269
image = Image.open('input.jpg')
270
271
# Fix orientation first
272
image = fix_image_orientation(image)
273
274
# Get mask only
275
session = new_session('u2net')
276
mask_pil = remove(image, session=session, only_mask=True)
277
278
# Post-process mask
279
mask_array = np.array(mask_pil)
280
smooth_mask_array = post_process(mask_array)
281
smooth_mask = Image.fromarray(smooth_mask_array)
282
283
# Apply custom cutout
284
from rembg.bg import naive_cutout
285
cutout = naive_cutout(image, smooth_mask)
286
287
# Apply background color
288
final_result = apply_background_color(cutout, (255, 255, 255, 255))
289
```
290
291
## Performance Notes
292
293
- **fix_image_orientation**: Minimal performance impact, always recommended
294
- **alpha_matting_cutout**: Computationally expensive but highest quality
295
- **naive_cutout**: Fastest cutout method
296
- **post_process**: Moderate cost, significant quality improvement for rough masks
297
- **apply_background_color**: Minimal performance impact