0
# Image Formats and Factories
1

2
Multiple image output formats for QR codes, each with different capabilities, dependencies, and use cases. The qrcode library supports PIL-based images, pure Python PNG, various SVG formats, and advanced styled images.
3

4
## Capabilities
5

6
### PIL Image Factory
7

8
The PIL image factory provides the most flexible image output with support for multiple formats and color modes.
9

10
```python { .api }
11
from qrcode.image.pil import PilImage
12

13
class PilImage:
14
    """
15
    PIL-based image factory supporting multiple formats.
16
    
17
    Requirements:
18
    - pillow package
19
    
20
    Supported formats:
21
    - PNG (default)
22
    - JPEG
23
    - BMP
24
    - GIF
25
    - Any PIL-supported format
26
    """
27
    
28
    kind = "PNG"  # Default format
29
    
30
    def save(self, stream, format=None, **kwargs):
31
        """
32
        Save image to stream or file.
33
        
34
        Parameters:
35
        - stream: File path (str) or file-like object
36
        - format (str or None): Image format override
37
        - **kwargs: Additional PIL save parameters
38
        """
39
```
40

41
**Usage Example:**
42

43
```python
44
import qrcode
45
from qrcode.image.pil import PilImage
46

47
# Use PIL factory explicitly
48
qr = qrcode.QRCode(image_factory=PilImage)
49
qr.add_data('Hello')
50
qr.make()
51

52
# Create image with custom colors
53
img = qr.make_image(fill_color="darkblue", back_color="lightgray")
54
img.save('colored_qr.png')
55

56
# Save as JPEG
57
img.save('qr_code.jpg', format='JPEG', quality=95)
58
```
59

60
### Pure Python PNG Factory
61

62
Pure Python PNG image factory with no external dependencies beyond the built-in pypng library.
63

64
```python { .api }
65
from qrcode.image.pure import PyPNGImage
66

67
class PyPNGImage:
68
    """
69
    Pure Python PNG image factory.
70
    
71
    Requirements:
72
    - pypng package (included with qrcode)
73
    
74
    Features:
75
    - No PIL dependency
76
    - PNG output only
77
    - Grayscale 1-bit output
78
    - Compact file sizes
79
    """
80
    
81
    kind = "PNG"
82
    allowed_kinds = ("PNG",)
83
    
84
    def save(self, stream, kind=None):
85
        """
86
        Save PNG image to stream or file.
87
        
88
        Parameters:
89
        - stream: File path (str) or file-like object
90
        - kind: Must be "PNG" or None
91
        """
92
```
93

94
**Usage Example:**
95

96
```python
97
import qrcode
98
from qrcode.image.pure import PyPNGImage
99

100
# Use pure Python PNG factory
101
qr = qrcode.QRCode(image_factory=PyPNGImage)
102
qr.add_data('Hello')
103
qr.make()
104

105
img = qr.make_image()
106
img.save('pure_python_qr.png')
107

108
# Backward compatibility alias (deprecated)
109
from qrcode.image.pure import PymagingImage
110
```
111

112
### SVG Image Factories
113

114
Multiple SVG image factories providing different SVG output styles and features.
115

116
```python { .api }
117
from qrcode.image.svg import SvgImage, SvgFragmentImage, SvgPathImage, SvgFillImage, SvgPathFillImage
118

119
class SvgImage:
120
    """
121
    Standalone SVG image with full XML declaration.
122
    
123
    Features:
124
    - Complete SVG document
125
    - Scalable vector output
126
    - Custom drawer support
127
    - XML declaration included
128
    """
129
    
130
    kind = "SVG"
131
    drawer_aliases = {
132
        "circle": ("SvgCircleDrawer", {}),
133
        "gapped-circle": ("SvgCircleDrawer", {"size_ratio": 0.8}),
134
        "gapped-square": ("SvgSquareDrawer", {"size_ratio": 0.8}),
135
    }
136

137
class SvgFragmentImage:
138
    """
139
    SVG fragment without XML declaration.
140
    
141
    Features:
142
    - SVG fragment for embedding
143
    - No XML declaration
144
    - Smaller output
145
    """
146

147
class SvgPathImage:
148
    """
149
    SVG with single path element for compact output.
150
    
151
    Features:
152
    - Single <path> element
153
    - Most compact SVG output
154
    - No gaps between modules
155
    """
156

157
class SvgFillImage:
158
    """SVG image with white background fill."""
159
    background = "white"
160

161
class SvgPathFillImage:
162
    """SVG path image with white background fill."""
163
    background = "white"
164
```
165

166
**Usage Example:**
167

168
```python
169
import qrcode
170
from qrcode.image.svg import SvgImage, SvgPathImage, SvgFragmentImage
171

172
# Standard SVG
173
qr = qrcode.QRCode(image_factory=SvgImage)
174
qr.add_data('Hello')
175
qr.make()
176

177
img = qr.make_image()
178
img.save('standard.svg')
179

180
# Path-based SVG (most compact)
181
qr = qrcode.QRCode(image_factory=SvgPathImage)
182
qr.add_data('Hello')
183
qr.make()
184

185
img = qr.make_image()
186
img.save('path.svg')
187

188
# SVG fragment for embedding
189
qr = qrcode.QRCode(image_factory=SvgFragmentImage)
190
qr.add_data('Hello')
191
qr.make()
192

193
fragment = qr.make_image()
194
svg_content = fragment.to_string()
195
```
196

197
### Styled PIL Image Factory
198

199
Advanced PIL image factory with support for custom module shapes, color masks, and embedded images.
200

201
```python { .api }
202
from qrcode.image.styledpil import StyledPilImage
203

204
class StyledPilImage:
205
    """
206
    Advanced styled PIL image factory.
207
    
208
    Features:
209
    - Custom module drawers
210
    - Color masks and gradients
211
    - Embedded images/logos
212
    - Antialiasing support
213
    """
214
    
215
    kind = "PNG"
216
    needs_processing = True
217
    
218
    def __init__(self, *args, module_drawer=None, color_mask=None, 
219
                 embeded_image=None, embeded_image_path=None, 
220
                 embeded_image_resample=None, **kwargs):
221
        """
222
        Initialize styled PIL image.
223
        
224
        Parameters:
225
        - module_drawer: Custom module drawer instance
226
        - color_mask: Color mask for advanced coloring
227
        - embeded_image: PIL Image to embed in center
228
        - embeded_image_path (str): Path to image file to embed
229
        - embeded_image_resample: Resampling filter for embedded image
230
        """
231
```
232

233
**Usage Example:**
234

235
```python
236
import qrcode
237
from qrcode.image.styledpil import StyledPilImage
238
from qrcode.image.styles.moduledrawers import CircleModuleDrawer
239
from qrcode.image.styles.colormasks import SolidFillColorMask
240

241
# Create styled QR code with circular modules
242
qr = qrcode.QRCode(
243
    error_correction=qrcode.constants.ERROR_CORRECT_H,  # High error correction for embedded image
244
    image_factory=StyledPilImage
245
)
246
qr.add_data('Hello Styled World')
247
qr.make()
248

249
img = qr.make_image(
250
    module_drawer=CircleModuleDrawer(),
251
    color_mask=SolidFillColorMask(back_color=(255, 255, 255), front_color=(0, 0, 100)),
252
    embeded_image_path='logo.png'
253
)
254
img.save('styled_qr.png')
255
```
256

257
## Image Factory Selection
258

259
The qrcode library automatically selects the best available image factory based on installed dependencies.
260

261
```python { .api }
262
# Automatic factory selection priority:
263
# 1. PilImage (if pillow is installed)
264
# 2. PyPNGImage (fallback, always available)
265

266
# In make() function and QRCode.make_image():
267
def make_image(self, image_factory=None, **kwargs):
268
    """
269
    Factory selection logic:
270
    
271
    1. Use provided image_factory parameter
272
    2. Use QRCode.image_factory if set
273
    3. Auto-detect: PilImage if available, else PyPNGImage
274
    """
275
```
276

277
**Usage Example:**
278

279
```python
280
import qrcode
281

282
# Automatic selection
283
img = qrcode.make('Hello')
284
print(type(img))  # Shows selected factory type
285

286
# Manual selection
287
from qrcode.image.pure import PyPNGImage
288
img = qrcode.make('Hello', image_factory=PyPNGImage)
289

290
# Per-instance factory
291
qr = qrcode.QRCode(image_factory=PyPNGImage)
292
qr.add_data('Hello')
293
qr.make()
294
img = qr.make_image()  # Uses PyPNGImage
295
```
296

297
## Image Saving and Formats
298

299
Different image factories support different output formats and saving options.
300

301
```python { .api }
302
# Common saving patterns across factories:
303

304
# File path saving
305
img.save('qrcode.png')
306
img.save('qrcode.jpg', format='JPEG')
307

308
# Stream saving
309
with open('qrcode.png', 'wb') as f:
310
    img.save(f)
311

312
# Format-specific options
313
img.save('qrcode.jpg', format='JPEG', quality=95, optimize=True)
314
img.save('qrcode.png', format='PNG', compress_level=9)
315
```
316

317
**SVG-specific methods:**
318

319
```python { .api }
320
# SVG images have additional methods
321
svg_img = qr.make_image()  # Using SVG factory
322

323
# Get SVG as string
324
svg_string = svg_img.to_string()
325

326
# Save with encoding options
327
svg_img.save('qrcode.svg')  # Full XML document
328
```
329

330
## Format Comparison
331

332
| Factory | Dependencies | Formats | File Size | Features |
333
|---------|-------------|---------|-----------|----------|
334
| PilImage | pillow | PNG, JPEG, BMP, GIF, etc. | Medium | Full color support, many formats |
335
| PyPNGImage | pypng (built-in) | PNG only | Small | No external deps, compact |
336
| SvgImage | None | SVG | Smallest | Scalable, text-based |
337
| SvgPathImage | None | SVG | Smallest | Most compact SVG |
338
| StyledPilImage | pillow | PNG, JPEG, etc. | Largest | Advanced styling, logos |