0
# Image Formats
1

2
Image-specific codecs for common formats including JPEG, PNG, TIFF, WebP, and next-generation formats like AVIF, HEIF, and JPEG XL. These codecs are optimized for photographic and graphic content, supporting various color spaces, bit depths, and compression modes.
3

4
## Capabilities
5

6
### JPEG Compression
7

8
Industry-standard lossy compression for photographic images with extensive configuration options and automatic fallback to lossless JPEG for high bit-depth content.
9

10
```python { .api }
11
def jpeg_encode(data, level=None, *, colorspace=None, outcolorspace=None, subsampling=None, optimize=None, smoothing=None, out=None):
12
    """
13
    Return JPEG encoded image with automatic LJPEG fallback for high bit-depth.
14
    
15
    Parameters:
16
    - data: NDArray - Image data to encode (2D grayscale or 3D RGB/RGBA)
17
    - level: int | None - Quality level (0-100, default 75). Higher = better quality
18
    - colorspace: str | None - Input color space ('rgb', 'ycbcr', 'cmyk', 'ycck')
19
    - outcolorspace: str | None - Output color space for encoding
20
    - subsampling: str | None - Chroma subsampling:
21
        '444' = no subsampling, '422' = 2x1, '420' = 2x2, '411' = 4x1
22
    - optimize: bool | None - Optimize Huffman tables (slower, better compression)
23
    - smoothing: int | None - Smoothing factor (0-100)
24
    - out: bytes | bytearray | None - Pre-allocated output buffer
25
    
26
    Returns:
27
    bytes | bytearray: JPEG encoded image data
28
    """
29

30
def jpeg_decode(data, *, tables=None, colorspace=None, outcolorspace=None, shape=None, out=None):
31
    """
32
    Return decoded JPEG image with automatic LJPEG support.
33
    
34
    Parameters:
35
    - data: bytes | bytearray | mmap.mmap - JPEG encoded data
36
    - tables: bytes | None - External Huffman/quantization tables
37
    - colorspace: str | None - Expected input color space
38
    - outcolorspace: str | None - Desired output color space
39
    - shape: tuple | None - Expected output shape for validation
40
    - out: NDArray | None - Pre-allocated output buffer
41
    
42
    Returns:
43
    NDArray: Decoded image array
44
    """
45

46
def jpeg_check(data):
47
    """
48
    Check if data is JPEG encoded.
49
    
50
    Parameters:
51
    - data: bytes | bytearray | mmap.mmap - Data to check
52
    
53
    Returns:
54
    bool: True if JPEG SOI marker detected
55
    """
56
```
57

58
### PNG Compression
59

60
Lossless compression with transparency support, ideal for graphics, screenshots, and images requiring exact pixel reproduction.
61

62
```python { .api }
63
def png_encode(data, level=None, *, strategy=None, filter=None, out=None):
64
    """
65
    Return PNG encoded image.
66
    
67
    Parameters:
68
    - data: NDArray - Image data (grayscale, RGB, or RGBA)
69
    - level: int | None - Compression level (0-9, default 6)
70
    - strategy: str | None - Compression strategy:
71
        'default', 'filtered', 'huffman', 'rle', 'fixed'
72
    - filter: str | None - Row filter type:
73
        'none', 'sub', 'up', 'average', 'paeth', 'auto'
74
    - out: bytes | bytearray | None - Pre-allocated output buffer
75
    
76
    Returns:
77
    bytes | bytearray: PNG encoded image data
78
    """
79

80
def png_decode(data, *, out=None):
81
    """
82
    Return decoded PNG image.
83
    
84
    Parameters:
85
    - data: bytes | bytearray | mmap.mmap - PNG encoded data
86
    - out: NDArray | None - Pre-allocated output buffer
87
    
88
    Returns:
89
    NDArray: Decoded image array
90
    """
91

92
def png_check(data):
93
    """
94
    Check if data is PNG encoded.
95
    
96
    Parameters:
97
    - data: bytes | bytearray | mmap.mmap - Data to check
98
    
99
    Returns:
100
    bool: True if PNG signature detected
101
    """
102
```
103

104
### WebP Compression
105

106
Modern image format supporting both lossy and lossless compression with superior efficiency compared to JPEG and PNG.
107

108
```python { .api }
109
def webp_encode(data, level=None, *, lossless=None, method=None, out=None):
110
    """
111
    Return WebP encoded image.
112
    
113
    Parameters:
114
    - data: NDArray - Image data (RGB or RGBA)
115
    - level: int | None - Quality level (0-100 for lossy, 0-9 for lossless)
116
    - lossless: bool | None - Use lossless compression (default False)
117
    - method: int | None - Compression method (0-6, default 4). Higher = slower, better
118
    - out: bytes | bytearray | None - Pre-allocated output buffer
119
    
120
    Returns:
121
    bytes | bytearray: WebP encoded image data
122
    """
123

124
def webp_decode(data, *, out=None):
125
    """
126
    Return decoded WebP image.
127
    
128
    Parameters:
129
    - data: bytes | bytearray | mmap.mmap - WebP encoded data
130
    - out: NDArray | None - Pre-allocated output buffer
131
    
132
    Returns:
133
    NDArray: Decoded image array
134
    """
135

136
def webp_check(data):
137
    """
138
    Check if data is WebP encoded.
139
    
140
    Parameters:
141
    - data: bytes | bytearray | mmap.mmap - Data to check
142
    
143
    Returns:
144
    bool: True if WebP signature detected
145
    """
146
```
147

148
### AVIF Compression
149

150
Next-generation format based on AV1 video codec, providing excellent compression efficiency for both lossy and lossless modes.
151

152
```python { .api }
153
def avif_encode(data, level=None, *, speed=None, tilelog2=None, bitspersample=None, pixelformat=None, codec=None, numthreads=None, out=None):
154
    """
155
    Return AVIF encoded image.
156
    
157
    Parameters:
158
    - data: NDArray - Image data to encode
159
    - level: int | None - Quality level (0-100, default 50). Higher = better quality
160
    - speed: int | None - Encoding speed (0-10, default 6). Higher = faster, lower quality
161
    - tilelog2: int | None - Tile size as log2 (0-6, default 0=no tiling)
162
    - bitspersample: int | None - Bits per sample (8, 10, 12)
163
    - pixelformat: str | None - Pixel format ('yuv420', 'yuv422', 'yuv444', 'yuv400')
164
    - codec: str | None - AV1 codec implementation ('aom', 'rav1e', 'svt')
165
    - numthreads: int | None - Number of encoding threads
166
    - out: bytes | bytearray | None - Pre-allocated output buffer
167
    
168
    Returns:
169
    bytes | bytearray: AVIF encoded image data
170
    """
171

172
def avif_decode(data, index=None, *, numthreads=None, out=None):
173
    """
174
    Return decoded AVIF image.
175
    
176
    Parameters:
177
    - data: bytes | bytearray | mmap.mmap - AVIF encoded data
178
    - index: int | None - Image index for multi-image files (default 0)
179
    - numthreads: int | None - Number of decoding threads
180
    - out: NDArray | None - Pre-allocated output buffer
181
    
182
    Returns:
183
    NDArray: Decoded image array
184
    """
185

186
def avif_check(data):
187
    """
188
    Check if data is AVIF encoded.
189
    
190
    Parameters:
191
    - data: bytes | bytearray | mmap.mmap - Data to check
192
    
193
    Returns:
194
    bool | None: True if AVIF signature detected
195
    """
196
```
197

198
### JPEG XL Compression
199

200
Next-generation JPEG replacement with superior compression, wide bit-depth support, and advanced features.
201

202
```python { .api }
203
def jpegxl_encode(data, level=None, *, effort=None, distance=None, lossless=None, decodingspeed=None, photometric=None, bitspersample=None, planar=None, usecontainer=None, numthreads=None, out=None):
204
    """
205
    Return JPEG XL encoded image.
206
    
207
    Parameters:
208
    - data: NDArray - Image data to encode
209
    - level: int | None - Quality level (0-100) for lossy mode
210
    - effort: int | None - Encoding effort (1-9, default 7). Higher = slower, better compression
211
    - distance: float | None - Psychovisual distance (0.0-25.0). Lower = better quality
212
    - lossless: bool | None - Use lossless compression (default False)
213
    - decodingspeed: int | None - Decoding speed tier (0-4, default 0)
214
    - photometric: str | None - Color interpretation ('minisblack', 'rgb', 'ycbcr')
215
    - bitspersample: int | None - Bits per sample (1-32, default based on input)
216
    - planar: bool | None - Use planar pixel layout
217
    - usecontainer: bool | None - Use JPEG XL container format
218
    - numthreads: int | None - Number of encoding threads
219
    - out: bytes | bytearray | None - Pre-allocated output buffer
220
    
221
    Returns:
222
    bytes | bytearray: JPEG XL encoded image data
223
    """
224

225
def jpegxl_decode(data, index=None, *, keeporientation=None, numthreads=None, out=None):
226
    """
227
    Return decoded JPEG XL image.
228
    
229
    Parameters:
230
    - data: bytes | bytearray | mmap.mmap - JPEG XL encoded data
231
    - index: int | None - Frame index for animated images (default 0)
232
    - keeporientation: bool | None - Preserve EXIF orientation (default False)
233
    - numthreads: int | None - Number of decoding threads
234
    - out: NDArray | None - Pre-allocated output buffer
235
    
236
    Returns:
237
    NDArray: Decoded image array
238
    """
239

240
def jpegxl_check(data):
241
    """
242
    Check if data is JPEG XL encoded.
243
    
244
    Parameters:
245
    - data: bytes | bytearray | mmap.mmap - Data to check
246
    
247
    Returns:
248
    bool: True if JPEG XL signature detected
249
    """
250
```
251

252
### TIFF Format
253

254
Flexible Tagged Image File Format supporting multiple pages, various compression schemes, and extensive metadata.
255

256
```python { .api }
257
def tiff_encode(data, *, compression=None, level=None, predictor=None, out=None):
258
    """
259
    Return TIFF encoded image.
260
    
261
    Parameters:
262
    - data: NDArray - Image data (supports various dtypes and dimensionalities)
263
    - compression: str | None - Compression scheme:
264
        'none', 'lzw', 'jpeg', 'zlib', 'packbits', 'lzma', 'zstd', 'webp'
265
    - level: int | None - Compression level (codec-dependent)
266
    - predictor: int | None - Predictor for LZW/ZLIB (1=none, 2=horizontal, 3=floating-point)
267
    - out: bytes | bytearray | None - Pre-allocated output buffer
268
    
269
    Returns:
270
    bytes | bytearray: TIFF encoded image data
271
    """
272

273
def tiff_decode(data, *, key=None, out=None):
274
    """
275
    Return decoded TIFF image.
276
    
277
    Parameters:
278
    - data: bytes | bytearray | mmap.mmap - TIFF encoded data
279
    - key: int | None - Page/directory index to decode (default 0)
280
    - out: NDArray | None - Pre-allocated output buffer
281
    
282
    Returns:
283
    NDArray: Decoded image array
284
    """
285

286
def tiff_check(data):
287
    """
288
    Check if data is TIFF encoded.
289
    
290
    Parameters:
291
    - data: bytes | bytearray | mmap.mmap - Data to check
292
    
293
    Returns:
294
    bool: True if TIFF signature detected
295
    """
296
```
297

298
### HEIF/HEIC Format
299

300
High Efficiency Image Format used by Apple devices and modern cameras for superior compression.
301

302
```python { .api }
303
def heif_encode(data, level=None, *, bitspersample=None, photometric=None, out=None):
304
    """
305
    Return HEIF encoded image.
306
    
307
    Parameters:
308
    - data: NDArray - Image data to encode
309
    - level: int | None - Quality level (0-100, default 50)
310
    - bitspersample: int | None - Bits per sample (8, 10, 12)
311
    - photometric: str | None - Color interpretation ('rgb', 'ycbcr')
312
    - out: bytes | bytearray | None - Pre-allocated output buffer
313
    
314
    Returns:
315
    bytes | bytearray: HEIF encoded image data
316
    """
317

318
def heif_decode(data, index=None, *, out=None):
319
    """
320
    Return decoded HEIF image.
321
    
322
    Parameters:
323
    - data: bytes | bytearray | mmap.mmap - HEIF encoded data
324
    - index: int | None - Image index for multi-image files (default 0)
325
    - out: NDArray | None - Pre-allocated output buffer
326
    
327
    Returns:
328
    NDArray: Decoded image array
329
    """
330

331
def heif_check(data):
332
    """
333
    Check if data is HEIF encoded.
334
    
335
    Parameters:
336
    - data: bytes | bytearray | mmap.mmap - Data to check
337
    
338
    Returns:
339
    bool: True if HEIF signature detected
340
    """
341
```
342

343
### GIF Format
344

345
Graphics Interchange Format with palette-based compression and animation support.
346

347
```python { .api }
348
def gif_encode(data, *, interlace=None, out=None):
349
    """
350
    Return GIF encoded image.
351
    
352
    Parameters:
353
    - data: NDArray - Image data (will be quantized to 256 colors)
354
    - interlace: bool | None - Use interlaced encoding
355
    - out: bytes | bytearray | None - Pre-allocated output buffer
356
    
357
    Returns:
358
    bytes | bytearray: GIF encoded image data
359
    """
360

361
def gif_decode(data, index=None, *, out=None):
362
    """
363
    Return decoded GIF image.
364
    
365
    Parameters:
366
    - data: bytes | bytearray | mmap.mmap - GIF encoded data
367
    - index: int | None - Frame index for animated GIFs (default 0)
368
    - out: NDArray | None - Pre-allocated output buffer
369
    
370
    Returns:
371
    NDArray: Decoded image array
372
    """
373

374
def gif_check(data):
375
    """
376
    Check if data is GIF encoded.
377
    
378
    Parameters:
379
    - data: bytes | bytearray | mmap.mmap - Data to check
380
    
381
    Returns:
382
    bool: True if GIF signature detected
383
    """
384
```
385

386
## Usage Examples
387

388
### Quality Comparison
389

390
```python
391
import imagecodecs
392
import numpy as np
393

394
# Create test image
395
image = np.random.randint(0, 256, (512, 512, 3), dtype=np.uint8)
396

397
# Compare different formats at similar quality levels
398
jpeg_data = imagecodecs.jpeg_encode(image, level=85)
399
webp_data = imagecodecs.webp_encode(image, level=85)
400
avif_data = imagecodecs.avif_encode(image, level=85)
401
jpegxl_data = imagecodecs.jpegxl_encode(image, level=85)
402

403
print(f"Original size: {image.nbytes} bytes")
404
print(f"JPEG size: {len(jpeg_data)} bytes ({len(jpeg_data)/image.nbytes:.2%})")
405
print(f"WebP size: {len(webp_data)} bytes ({len(webp_data)/image.nbytes:.2%})")
406
print(f"AVIF size: {len(avif_data)} bytes ({len(avif_data)/image.nbytes:.2%})")
407
print(f"JPEG XL size: {len(jpegxl_data)} bytes ({len(jpegxl_data)/image.nbytes:.2%})")
408
```
409

410
### Lossless Compression
411

412
```python
413
import imagecodecs
414
import numpy as np
415

416
# Graphics with sharp edges (better for lossless)
417
image = np.zeros((256, 256, 3), dtype=np.uint8)
418
image[50:200, 50:200] = [255, 0, 0]  # Red square
419
image[100:150, 100:150] = [0, 255, 0]  # Green square
420

421
# Lossless compression comparison
422
png_data = imagecodecs.png_encode(image, level=9)
423
webp_lossless = imagecodecs.webp_encode(image, lossless=True, level=9)
424
jpegxl_lossless = imagecodecs.jpegxl_encode(image, lossless=True, effort=9)
425

426
print(f"PNG size: {len(png_data)} bytes")
427
print(f"WebP lossless: {len(webp_lossless)} bytes")
428
print(f"JPEG XL lossless: {len(jpegxl_lossless)} bytes")
429

430
# Verify lossless reconstruction
431
png_decoded = imagecodecs.png_decode(png_data)
432
assert np.array_equal(image, png_decoded)
433
```
434

435
### Multi-threaded Encoding
436

437
```python
438
import imagecodecs
439
import numpy as np
440

441
# Large high-resolution image
442
large_image = np.random.randint(0, 256, (4096, 4096, 3), dtype=np.uint8)
443

444
# Multi-threaded encoding for supported formats
445
avif_mt = imagecodecs.avif_encode(large_image, level=50, numthreads=8)
446
jpegxl_mt = imagecodecs.jpegxl_encode(large_image, level=50, numthreads=8)
447

448
print(f"Multi-threaded AVIF: {len(avif_mt)} bytes")
449
print(f"Multi-threaded JPEG XL: {len(jpegxl_mt)} bytes")
450
```
451

452
### Advanced TIFF Usage
453

454
```python
455
import imagecodecs
456
import numpy as np
457

458
# Multi-page TIFF with different compression
459
pages = []
460
for i in range(5):
461
    page = np.random.randint(0, 256, (256, 256), dtype=np.uint16)
462
    pages.append(page)
463

464
# Encode each page with different compression
465
tiff_data = b""
466
for i, page in enumerate(pages):
467
    compression = ['none', 'lzw', 'zlib', 'zstd', 'lzma'][i]
468
    page_data = imagecodecs.tiff_encode(page, compression=compression)
469
    if i == 0:
470
        tiff_data = page_data
471
    # Note: Multi-page TIFF requires specialized handling
472

473
# Read specific page
474
page_0 = imagecodecs.tiff_decode(tiff_data, key=0)
475
```
476

477
## Format Selection Guidelines
478

479
### Photographic Images
480
- **JPEG**: Standard choice, excellent compression for natural images
481
- **AVIF**: Best compression efficiency, modern browsers
482
- **HEIF**: Apple ecosystem, excellent quality
483
- **JPEG XL**: Future-proof, wide bit-depth support
484

485
### Graphics and Screenshots  
486
- **PNG**: Lossless, transparency support, universal compatibility
487
- **WebP**: Better compression than PNG, modern browser support
488
- **JPEG XL**: Excellent lossless compression, advanced features
489

490
### Scientific/Medical Images
491
- **TIFF**: Multi-page support, various data types, extensive metadata
492
- **JPEG 2000**: Wavelet-based, progressive transmission
493
- **JPEG-LS**: Lossless/near-lossless compression
494

495
### Web Usage
496
- **WebP**: Good compression, wide browser support
497
- **AVIF**: Best compression, growing browser support  
498
- **JPEG XL**: Future web standard, excellent features
499

500
## Error Handling
501

502
```python { .api }
503
class JpegError(Exception):
504
    """JPEG codec exception."""
505

506
class PngError(Exception):
507
    """PNG codec exception."""
508

509
class WebpError(Exception):
510
    """WebP codec exception."""
511

512
class AvifError(Exception):
513
    """AVIF codec exception."""
514

515
class JpegxlError(Exception):
516
    """JPEG XL codec exception."""
517

518
class TiffError(Exception):
519
    """TIFF codec exception."""
520

521
class HeifError(Exception):
522
    """HEIF codec exception."""
523

524
class GifError(Exception):
525
    """GIF codec exception."""
526
```
527

528
Common error handling:
529

530
```python
531
import imagecodecs
532

533
try:
534
    encoded = imagecodecs.avif_encode(image, level=50)
535
except imagecodecs.DelayedImportError:
536
    # AVIF codec not available, fallback to WebP
537
    encoded = imagecodecs.webp_encode(image, level=85)
538
except imagecodecs.AvifError as e:
539
    print(f"AVIF encoding failed: {e}")
540
    # Handle encoding error
541
```