0
# Document Rendering
1

2
High-performance rendering of document pages to various image formats with comprehensive control over resolution, color spaces, transformations, and output quality. PyMuPDF provides efficient pixel-level rendering suitable for both display and print applications.
3

4
## Capabilities
5

6
### Page Rendering
7

8
Render document pages to raster images with full control over output parameters.
9

10
```python { .api }
11
class Page:
12
    def get_pixmap(self, matrix: Matrix = None, colorspace: Colorspace = None, 
13
                   clip: Rect = None, alpha: bool = False, annots: bool = True,
14
                   aa: int = 8) -> Pixmap:
15
        """
16
        Render page to Pixmap image.
17
        
18
        Parameters:
19
        - matrix: transformation matrix for scaling/rotation
20
        - colorspace: target color space (csRGB, csGRAY, csCMYK)
21
        - clip: rectangle to limit rendering area
22
        - alpha: include alpha channel for transparency
23
        - annots: include annotations in rendering
24
        - aa: anti-aliasing level (0-8, higher = smoother)
25
        
26
        Returns:
27
        Pixmap object containing rendered page image
28
        """
29
```
30

31
### Pixmap Class
32

33
Raster image representation with comprehensive manipulation capabilities.
34

35
```python { .api }
36
class Pixmap:
37
    def __init__(self, colorspace: Colorspace, bbox: typing.Union[Rect, IRect], 
38
                 alpha: bool = False):
39
        """
40
        Create empty pixmap.
41
        
42
        Parameters:
43
        - colorspace: color space (csRGB, csGRAY, csCMYK)
44
        - bbox: bounding rectangle
45
        - alpha: include alpha channel
46
        """
47
    
48
    def save(self, filename: str, output: str = None, jpg_quality: int = 95) -> None:
49
        """
50
        Save pixmap to file.
51
        
52
        Parameters:
53
        - filename: output file path
54
        - output: format override ("png", "jpg", "pnm", "pam", "psd", "ps")
55
        - jpg_quality: JPEG quality (0-100)
56
        """
57
    
58
    def tobytes(self, output: str = "png", jpg_quality: int = 95) -> bytes:
59
        """
60
        Convert pixmap to bytes.
61
        
62
        Parameters:
63
        - output: output format ("png", "jpg", "pnm", "pam", "psd", "ps")
64
        - jpg_quality: JPEG quality for JPG output
65
        
66
        Returns:
67
        Image data as bytes
68
        """
69
    
70
    def pil_save(self, filename: str, format: str = None, **kwargs) -> None:
71
        """
72
        Save using PIL with additional format support.
73
        
74
        Parameters:
75
        - filename: output file path
76
        - format: PIL format ("PNG", "JPEG", "TIFF", etc.)
77
        - kwargs: additional PIL save parameters
78
        """
79
    
80
    def pil_tobytes(self, format: str = "PNG", **kwargs) -> bytes:
81
        """
82
        Convert to bytes using PIL.
83
        
84
        Parameters:
85
        - format: PIL format ("PNG", "JPEG", "TIFF", etc.)
86
        - kwargs: additional PIL parameters
87
        
88
        Returns:
89
        Image data as bytes
90
        """
91
    
92
    def copy(self) -> Pixmap:
93
        """
94
        Create a copy of the pixmap.
95
        
96
        Returns:
97
        New Pixmap object with identical content
98
        """
99
    
100
    def pixel(self, x: int, y: int) -> list:
101
        """
102
        Get pixel color values at coordinates.
103
        
104
        Parameters:
105
        - x: x coordinate
106
        - y: y coordinate
107
        
108
        Returns:
109
        List of color component values
110
        """
111
    
112
    def set_pixel(self, x: int, y: int, color: typing.Union[list, tuple]) -> None:
113
        """
114
        Set pixel color at coordinates.
115
        
116
        Parameters:
117
        - x: x coordinate
118
        - y: y coordinate  
119
        - color: color values as list/tuple
120
        """
121
    
122
    def invert_irect(self, irect: IRect = None) -> None:
123
        """
124
        Invert colors in rectangle area.
125
        
126
        Parameters:
127
        - irect: rectangle to invert (None for entire pixmap)
128
        """
129
    
130
    def gamma_with(self, gamma: float) -> None:
131
        """
132
        Apply gamma correction.
133
        
134
        Parameters:
135
        - gamma: gamma correction value
136
        """
137
    
138
    def tint_with(self, red: int, green: int, blue: int) -> None:
139
        """
140
        Apply color tint.
141
        
142
        Parameters:
143
        - red: red tint value (0-255)
144
        - green: green tint value (0-255)
145
        - blue: blue tint value (0-255)
146
        """
147
    
148
    def shrink(self, factor: int) -> None:
149
        """
150
        Shrink pixmap by factor.
151
        
152
        Parameters:
153
        - factor: shrink factor (must be > 1)
154
        """
155
    
156
    def set_rect(self, rect: IRect, color: typing.Union[list, tuple]) -> None:
157
        """
158
        Fill rectangle with color.
159
        
160
        Parameters:
161
        - rect: rectangle to fill
162
        - color: fill color values
163
        """
164
    
165
    def clear_with(self, value: int = 255) -> None:
166
        """
167
        Clear pixmap with value.
168
        
169
        Parameters:
170
        - value: clear value for all channels
171
        """
172
    
173
    @property
174
    def width(self) -> int:
175
        """Pixmap width in pixels."""
176
    
177
    @property
178
    def height(self) -> int:
179
        """Pixmap height in pixels."""
180
    
181
    @property
182
    def n(self) -> int:
183
        """Number of color components per pixel."""
184
    
185
    @property
186
    def stride(self) -> int:
187
        """Number of bytes per row."""
188
    
189
    @property
190
    def samples(self) -> bytes:
191
        """Raw pixel data as bytes."""
192
    
193
    @property
194
    def colorspace(self) -> Colorspace:
195
        """Pixmap color space."""
196
    
197
    @property
198
    def alpha(self) -> bool:
199
        """True if pixmap has alpha channel."""
200
    
201
    @property
202
    def size(self) -> int:
203
        """Size of pixel data in bytes."""
204
    
205
    @property
206
    def irect(self) -> IRect:
207
        """Integer rectangle of pixmap bounds."""
208
    
209
    def set_origin(self, x: int, y: int) -> None:
210
        """
211
        Set pixmap origin coordinates.
212
        
213
        Parameters:
214
        - x: x origin
215
        - y: y origin
216
        """
217
```
218

219
### Color Spaces
220

221
Manage color space conversions and properties.
222

223
```python { .api }
224
class Colorspace:
225
    def __init__(self, n: int):
226
        """
227
        Create color space.
228
        
229
        Parameters:
230
        - n: number of color components
231
        """
232
    
233
    @property
234
    def name(self) -> str:
235
        """Color space name."""
236
    
237
    @property
238
    def n(self) -> int:
239
        """Number of color components."""
240

241
# Pre-defined color spaces
242
csRGB: Colorspace      # RGB color space
243
csGRAY: Colorspace     # Grayscale color space  
244
csCMYK: Colorspace     # CMYK color space
245
```
246

247
### Display List Rendering
248

249
Intermediate rendering format for reusable page rendering.
250

251
```python { .api }
252
class DisplayList:
253
    def __init__(self, page: Page):
254
        """
255
        Create display list from page.
256
        
257
        Parameters:
258
        - page: source Page object
259
        """
260
    
261
    def run(self, device, matrix: Matrix, area: Rect) -> None:
262
        """
263
        Run display list through device.
264
        
265
        Parameters:
266
        - device: target device
267
        - matrix: transformation matrix
268
        - area: clipping area
269
        """
270
    
271
    def get_pixmap(self, matrix: Matrix = None, colorspace: Colorspace = None, 
272
                   alpha: bool = False, clip: Rect = None) -> Pixmap:
273
        """
274
        Render display list to pixmap.
275
        
276
        Parameters:
277
        - matrix: transformation matrix
278
        - colorspace: target color space
279
        - alpha: include alpha channel
280
        - clip: clipping rectangle
281
        
282
        Returns:
283
        Rendered Pixmap object
284
        """
285
    
286
    def get_textpage(self, flags: int = 0) -> TextPage:
287
        """
288
        Extract text from display list.
289
        
290
        Parameters:
291
        - flags: text extraction flags
292
        
293
        Returns:
294
        TextPage object
295
        """
296
    
297
    @property
298
    def rect(self) -> Rect:
299
        """Display list bounding rectangle."""
300
```
301

302
## Usage Examples
303

304
### Basic Page Rendering
305

306
```python
307
import pymupdf
308

309
doc = pymupdf.open("document.pdf")
310
page = doc.load_page(0)
311

312
# Render at default resolution
313
pix = page.get_pixmap()
314
pix.save("page_default.png")
315

316
# Render at 2x resolution
317
mat = pymupdf.Matrix(2, 2)  # 2x scale
318
pix_hires = page.get_pixmap(matrix=mat)
319
pix_hires.save("page_hires.png")
320

321
# Render specific area only
322
clip_rect = pymupdf.Rect(100, 100, 400, 400)
323
pix_clip = page.get_pixmap(clip=clip_rect)
324
pix_clip.save("page_clipped.png")
325

326
doc.close()
327
```
328

329
### Different Color Spaces and Formats
330

331
```python
332
import pymupdf
333

334
doc = pymupdf.open("document.pdf")
335
page = doc.load_page(0)
336

337
# RGB rendering (default)
338
pix_rgb = page.get_pixmap()
339
pix_rgb.save("page_rgb.png")
340

341
# Grayscale rendering
342
pix_gray = page.get_pixmap(colorspace=pymupdf.csGRAY)
343
pix_gray.save("page_gray.png")
344

345
# High-quality JPEG output
346
pix_rgb.save("page_quality.jpg", jpg_quality=95)
347

348
# Save as different formats
349
pix_rgb.pil_save("page.tiff", format="TIFF", compression="lzw")
350

351
doc.close()
352
```
353

354
### High-Resolution Rendering
355

356
```python
357
import pymupdf
358

359
doc = pymupdf.open("document.pdf")
360
page = doc.load_page(0)
361

362
# Calculate matrix for specific DPI
363
zoom_x = 300 / 72  # 300 DPI (default is 72 DPI)
364
zoom_y = 300 / 72
365
mat = pymupdf.Matrix(zoom_x, zoom_y)
366

367
# Render with high anti-aliasing
368
pix = page.get_pixmap(matrix=mat, aa=8)
369
pix.save("page_300dpi.png")
370

371
# Check output dimensions
372
print(f"Rendered size: {pix.width} x {pix.height}")
373

374
doc.close()
375
```
376

377
### Pixmap Manipulation
378

379
```python
380
import pymupdf
381

382
doc = pymupdf.open("document.pdf")
383
page = doc.load_page(0)
384

385
# Render page
386
pix = page.get_pixmap()
387

388
# Apply image enhancements
389
pix.gamma_with(1.2)  # Increase gamma
390
pix.tint_with(10, 10, 0)  # Slight yellow tint
391

392
# Get pixel information
393
width, height = pix.width, pix.height
394
print(f"Image size: {width} x {height}")
395
print(f"Color components: {pix.n}")
396
print(f"Has alpha: {pix.alpha}")
397

398
# Access individual pixels
399
center_x, center_y = width // 2, height // 2
400
pixel_color = pix.pixel(center_x, center_y)
401
print(f"Center pixel color: {pixel_color}")
402

403
# Save modified image
404
pix.save("page_enhanced.png")
405

406
doc.close()
407
```
408

409
### Batch Rendering with Progress
410

411
```python
412
import pymupdf
413

414
def render_all_pages(doc_path: str, output_dir: str, dpi: int = 150):
415
    """Render all pages of a document to PNG files."""
416
    import os
417
    
418
    doc = pymupdf.open(doc_path)
419
    zoom = dpi / 72
420
    mat = pymupdf.Matrix(zoom, zoom)
421
    
422
    os.makedirs(output_dir, exist_ok=True)
423
    
424
    for page_num in range(doc.page_count):
425
        page = doc.load_page(page_num)
426
        pix = page.get_pixmap(matrix=mat)
427
        
428
        output_path = os.path.join(output_dir, f"page_{page_num + 1:03d}.png")
429
        pix.save(output_path)
430
        
431
        print(f"Rendered page {page_num + 1}/{doc.page_count}")
432
    
433
    doc.close()
434
    print(f"All pages rendered to {output_dir}")
435

436
# Usage
437
render_all_pages("document.pdf", "output_images", dpi=200)
438
```
439

440
### Using Display Lists for Efficiency
441

442
```python
443
import pymupdf
444

445
doc = pymupdf.open("document.pdf")
446
page = doc.load_page(0)
447

448
# Create display list once
449
display_list = pymupdf.DisplayList(page)
450

451
# Render multiple times with different parameters
452
matrices = [
453
    pymupdf.Matrix(1, 1),    # 1x scale
454
    pymupdf.Matrix(2, 2),    # 2x scale  
455
    pymupdf.Matrix(0.5, 0.5) # 0.5x scale
456
]
457

458
for i, mat in enumerate(matrices):
459
    pix = display_list.get_pixmap(matrix=mat)
460
    pix.save(f"page_scale_{i}.png")
461

462
doc.close()
463
```
464

465
### Rendering with Transparency
466

467
```python
468
import pymupdf
469

470
doc = pymupdf.open("document.pdf")
471
page = doc.load_page(0)
472

473
# Render with alpha channel
474
pix = page.get_pixmap(alpha=True)
475

476
# Save as PNG to preserve transparency
477
pix.save("page_transparent.png")
478

479
# Check if image has transparency
480
if pix.alpha:
481
    print("Image has alpha channel")
482
    
483
    # Create version without alpha
484
    pix_no_alpha = pymupdf.Pixmap(pymupdf.csRGB, pix, 0)  # Drop alpha
485
    pix_no_alpha.save("page_no_alpha.png")
486

487
doc.close()
488
```