0
# Image Processing
1

2
Advanced image processing operations including upscaling, interrogation, metadata extraction, and batch processing capabilities. These functions provide essential post-processing and analysis tools for generated and existing images.
3

4
## Capabilities
5

6
### Image Upscaling and Enhancement
7

8
High-quality image upscaling and enhancement using various algorithms and models.
9

10
```python { .api }
11
def extra_single_image(
12
    image: Image.Image,
13
    upscaler_1: str = "None",
14
    upscaling_resize: float = 2.0,
15
    upscaling_resize_w: int = 0,
16
    upscaling_resize_h: int = 0,
17
    upscaling_crop: bool = True,
18
    upscaler_2: str = "None",
19
    extras_upscaler_2_visibility: float = 0.0,
20
    gfpgan_visibility: float = 0.0,
21
    codeformer_visibility: float = 0.0,
22
    codeformer_weight: float = 0.0,
23
    **kwargs
24
) -> WebUIApiResult:
25
    """
26
    Upscale and enhance a single image.
27

28
    Parameters:
29
    - image: Input PIL Image to process
30
    - upscaler_1: Primary upscaling algorithm
31
    - upscaling_resize: Resize factor (e.g., 2.0 for 2x)
32
    - upscaling_resize_w: Target width (0 to use resize factor)
33
    - upscaling_resize_h: Target height (0 to use resize factor)
34
    - upscaling_crop: Crop to exact dimensions if needed
35
    - upscaler_2: Secondary upscaling algorithm
36
    - extras_upscaler_2_visibility: Blend factor for second upscaler (0.0-1.0)
37
    - gfpgan_visibility: GFPGAN face restoration strength (0.0-1.0)
38
    - codeformer_visibility: CodeFormer face restoration strength (0.0-1.0)
39
    - codeformer_weight: CodeFormer processing weight (0.0-1.0)
40

41
    Returns:
42
    WebUIApiResult containing the upscaled image
43
    """
44

45
def extra_batch_images(
46
    images: List[Image.Image],
47
    upscaler_1: str = "None",
48
    upscaling_resize: float = 2.0,
49
    upscaling_resize_w: int = 0,
50
    upscaling_resize_h: int = 0,
51
    upscaling_crop: bool = True,
52
    upscaler_2: str = "None",
53
    extras_upscaler_2_visibility: float = 0.0,
54
    gfpgan_visibility: float = 0.0,
55
    codeformer_visibility: float = 0.0,
56
    codeformer_weight: float = 0.0,
57
    **kwargs
58
) -> WebUIApiResult:
59
    """
60
    Upscale and enhance multiple images in batch.
61

62
    Parameters:
63
    - images: List of PIL Images to process
64
    - upscaler_1: Primary upscaling algorithm
65
    - upscaling_resize: Resize factor
66
    - upscaling_resize_w: Target width (0 to use resize factor)
67
    - upscaling_resize_h: Target height (0 to use resize factor)
68
    - upscaling_crop: Crop to exact dimensions
69
    - upscaler_2: Secondary upscaling algorithm
70
    - extras_upscaler_2_visibility: Blend factor for second upscaler
71
    - gfpgan_visibility: GFPGAN face restoration strength
72
    - codeformer_visibility: CodeFormer face restoration strength
73
    - codeformer_weight: CodeFormer processing weight
74

75
    Returns:
76
    WebUIApiResult containing all upscaled images
77
    """
78
```
79

80
### Image Analysis and Interrogation
81

82
Extract information from images including generating prompts and reading metadata.
83

84
```python { .api }
85
def interrogate(
86
    image: Image.Image,
87
    model: str = "clip"
88
) -> str:
89
    """
90
    Generate text description of an image using AI models.
91

92
    Parameters:
93
    - image: PIL Image to analyze
94
    - model: Interrogation model ("clip" or "deepdanbooru")
95

96
    Returns:
97
    Generated text description/tags for the image
98
    """
99

100
def png_info(image: Image.Image) -> Dict:
101
    """
102
    Extract generation parameters from PNG metadata.
103

104
    Parameters:
105
    - image: PIL Image with embedded metadata
106

107
    Returns:
108
    Dictionary containing:
109
    - info: Generation parameters text
110
    - items: Parsed parameter dictionary
111
    """
112
```
113

114
### Utility Functions
115

116
Helper functions for image encoding and conversion operations.
117

118
```python { .api }
119
def b64_img(image: Image.Image) -> str:
120
    """
121
    Convert PIL Image to base64 with data URL header.
122

123
    Parameters:
124
    - image: PIL Image to convert
125

126
    Returns:
127
    Base64-encoded image with data URL prefix (data:image/png;base64,...)
128
    """
129

130
def raw_b64_img(image: Image.Image, format: str = "PNG") -> str:
131
    """
132
    Convert PIL Image to raw base64 encoding without header.
133

134
    Parameters:
135
    - image: PIL Image to convert
136
    - format: Output format ("PNG", "JPEG", "WEBP")
137

138
    Returns:
139
    Raw base64-encoded image data without data URL prefix
140
    """
141
```
142

143
**Usage Examples:**
144

145
```python
146
from PIL import Image
147
import webuiapi
148

149
api = webuiapi.WebUIApi()
150

151
# Single image upscaling
152
input_image = Image.open("low_res_image.jpg")
153

154
# Basic 2x upscaling with ESRGAN
155
result = api.extra_single_image(
156
    image=input_image,
157
    upscaler_1="R-ESRGAN 4x+",
158
    upscaling_resize=2.0
159
)
160

161
upscaled_image = result.image
162
upscaled_image.save("upscaled_2x.png")
163

164
# High-quality upscaling with face restoration
165
result = api.extra_single_image(
166
    image=input_image,
167
    upscaler_1="R-ESRGAN 4x+",
168
    upscaling_resize=4.0,
169
    gfpgan_visibility=0.8,  # Strong face restoration
170
    codeformer_visibility=0.5  # Additional face enhancement
171
)
172

173
enhanced_image = result.image
174
enhanced_image.save("enhanced_4x.png")
175

176
# Dual upscaler blending
177
result = api.extra_single_image(
178
    image=input_image,
179
    upscaler_1="R-ESRGAN 4x+",
180
    upscaler_2="SwinIR 4x",
181
    upscaling_resize=2.0,
182
    extras_upscaler_2_visibility=0.3  # 30% second upscaler
183
)
184

185
# Batch processing multiple images
186
image_list = [
187
    Image.open("image1.jpg"),
188
    Image.open("image2.jpg"),
189
    Image.open("image3.jpg")
190
]
191

192
batch_result = api.extra_batch_images(
193
    images=image_list,
194
    upscaler_1="R-ESRGAN 4x+",
195
    upscaling_resize=2.0,
196
    gfpgan_visibility=0.5
197
)
198

199
# Save all batch results
200
for i, enhanced_img in enumerate(batch_result.images):
201
    enhanced_img.save(f"batch_enhanced_{i}.png")
202

203
# Image interrogation for prompt generation
204
test_image = Image.open("generated_art.png")
205

206
# Generate descriptive prompt using CLIP
207
clip_description = api.interrogate(test_image, model="clip")
208
print(f"CLIP description: {clip_description}")
209

210
# Generate tags using DeepDanbooru (good for anime/art)
211
danbooru_tags = api.interrogate(test_image, model="deepdanbooru")
212
print(f"Danbooru tags: {danbooru_tags}")
213

214
# Extract generation parameters from PNG
215
generated_image = Image.open("stable_diffusion_output.png")
216
metadata = api.png_info(generated_image)
217

218
if metadata.get('info'):
219
    print("Original generation parameters:")
220
    print(metadata['info'])
221
    
222
    # Parse parameters if available
223
    params = metadata.get('items', {})
224
    if params:
225
        print(f"Prompt: {params.get('Prompt', 'N/A')}")
226
        print(f"Steps: {params.get('Steps', 'N/A')}")
227
        print(f"Sampler: {params.get('Sampler', 'N/A')}")
228
        print(f"CFG Scale: {params.get('CFG scale', 'N/A')}")
229
        print(f"Seed: {params.get('Seed', 'N/A')}")
230
```
231

232
## Error Handling
233

234
Image processing operations may fail due to various reasons. Handle common scenarios:
235

236
```python
237
import webuiapi
238
from PIL import Image
239

240
api = webuiapi.WebUIApi()
241

242
try:
243
    image = Image.open("input.jpg")
244
    result = api.extra_single_image(
245
        image=image,
246
        upscaler_1="R-ESRGAN 4x+",
247
        upscaling_resize=4.0
248
    )
249
    
250
    if result.images:
251
        result.image.save("output.png")
252
    else:
253
        print("No images returned")
254
        
255
except Exception as e:
256
    print(f"Processing failed: {e}")
257
    # Handle specific error cases:
258
    # - Invalid upscaler name
259
    # - Out of memory for large images
260
    # - Network connection issues
261
```
262

263
## Types
264

265
```python { .api }
266
class WebUIApiResult:
267
    """Result container for image processing operations."""
268
    images: List[Image.Image]  # Processed images
269
    parameters: Dict  # Processing parameters used
270
    info: Dict  # Processing metadata
271
    json: Dict  # Raw API response
272
    
273
    @property
274
    def image(self) -> Image.Image:
275
        """First processed image (convenience property)."""
276
```