0
# PyTurboJPEG
1

2
A Python wrapper of libjpeg-turbo for decoding and encoding JPEG image. Provides high-performance JPEG operations with comprehensive functionality for image manipulation including direct decoding to BGR/grayscale/YUV arrays, in-place operations for memory efficiency, image scaling with quality control, lossless cropping, and advanced encoding options.
3

4
## Package Information
5

6
- **Package Name**: PyTurboJPEG
7
- **Language**: Python
8
- **Installation**: `pip install git+https://github.com/lilohuang/PyTurboJPEG.git`
9
- **Dependencies**: numpy, libjpeg-turbo (system library)
10

11
## Core Imports
12

13
```python
14
from turbojpeg import TurboJPEG
15
```
16

17
With constants for formats and options:
18

19
```python
20
from turbojpeg import (
21
    TurboJPEG, 
22
    TJPF_BGR, TJPF_RGB, TJPF_GRAY,
23
    TJSAMP_422, TJSAMP_420, TJSAMP_GRAY,
24
    TJFLAG_PROGRESSIVE, TJFLAG_FASTUPSAMPLE, TJFLAG_FASTDCT
25
)
26
```
27

28
## Basic Usage
29

30
```python
31
from turbojpeg import TurboJPEG
32
import numpy as np
33

34
# Initialize the JPEG processor
35
jpeg = TurboJPEG()
36

37
# Decode JPEG from file to numpy array
38
with open('input.jpg', 'rb') as in_file:
39
    bgr_array = jpeg.decode(in_file.read())
40

41
# Encode numpy array to JPEG
42
with open('output.jpg', 'wb') as out_file:
43
    out_file.write(jpeg.encode(bgr_array))
44

45
# Get image dimensions without full decode
46
with open('input.jpg', 'rb') as in_file:
47
    width, height, subsample, colorspace = jpeg.decode_header(in_file.read())
48
    print(f"Image: {width}x{height}")
49
```
50

51
## Architecture
52

53
PyTurboJPEG is organized around a single main class that provides access to libjpeg-turbo functionality:
54

55
- **TurboJPEG Class**: Main wrapper providing all JPEG operations
56
- **Decode Operations**: Methods for decoding JPEG data to various formats (BGR, RGB, YUV, grayscale)
57
- **Encode Operations**: Methods for encoding numpy arrays to JPEG with quality and format options
58
- **Transform Operations**: Lossless crop, scale, and transform operations
59
- **Constants**: Extensive set of format flags, pixel formats, and operation options
60

61
## Capabilities
62

63
### JPEG Decoding
64

65
Core decoding functionality for converting JPEG data to numpy arrays, with support for various pixel formats, scaling factors, and output options including YUV and grayscale formats.
66

67
```python { .api }
68
def decode_header(jpeg_buf: bytes) -> tuple[int, int, int, int]:
69
    """Decode JPEG header returning (width, height, subsample, colorspace)"""
70

71
def decode(
72
    jpeg_buf: bytes, 
73
    pixel_format: int = TJPF_BGR, 
74
    scaling_factor: tuple[int, int] | None = None, 
75
    flags: int = 0, 
76
    dst: np.ndarray | None = None
77
) -> np.ndarray:
78
    """Decode JPEG to numpy array"""
79

80
def decode_to_yuv(
81
    jpeg_buf: bytes, 
82
    scaling_factor: tuple[int, int] | None = None, 
83
    pad: int = 4, 
84
    flags: int = 0
85
) -> tuple[np.ndarray, list[tuple[int, int]]]:
86
    """Decode JPEG to YUV format"""
87
```
88

89
[JPEG Decoding](./decoding.md)
90

91
### JPEG Encoding  
92

93
Encoding functionality for converting numpy arrays to JPEG data with quality control, subsampling options, and various pixel format support including progressive encoding.
94

95
```python { .api }
96
def encode(
97
    img_array: np.ndarray, 
98
    quality: int = 85, 
99
    pixel_format: int = TJPF_BGR, 
100
    jpeg_subsample: int = TJSAMP_422, 
101
    flags: int = 0, 
102
    dst: bytearray | None = None
103
) -> bytes | tuple[bytearray, int]:
104
    """Encode numpy array to JPEG"""
105

106
def encode_from_yuv(
107
    img_array: np.ndarray, 
108
    height: int, 
109
    width: int, 
110
    quality: int = 85, 
111
    jpeg_subsample: int = TJSAMP_420, 
112
    flags: int = 0
113
) -> bytes:
114
    """Encode YUV array to JPEG"""
115
```
116

117
[JPEG Encoding](./encoding.md)
118

119
### Image Transformations
120

121
Lossless transformation operations including cropping, scaling with quality adjustment, multiple crop operations, and background filling for extended crops.
122

123
```python { .api }
124
def crop(
125
    jpeg_buf: bytes, 
126
    x: int, y: int, w: int, h: int, 
127
    preserve: bool = False, 
128
    gray: bool = False, 
129
    copynone: bool = False
130
) -> bytes:
131
    """Lossless crop operation"""
132

133
def crop_multiple(
134
    jpeg_buf: bytes, 
135
    crop_parameters: list[tuple[int, int, int, int]], 
136
    background_luminance: float = 1.0, 
137
    gray: bool = False, 
138
    copynone: bool = False
139
) -> list[bytes]:
140
    """Multiple crop/extend operations"""
141

142
def scale_with_quality(
143
    jpeg_buf: bytes, 
144
    scaling_factor: tuple[int, int] | None = None, 
145
    quality: int = 85, 
146
    flags: int = 0
147
) -> bytes:
148
    """Scale and re-encode with quality"""
149
```
150

151
[Image Transformations](./transformations.md)
152

153
### Utility Functions
154

155
Buffer size calculation and scaling factor information for optimizing memory usage and determining available scaling options.
156

157
```python { .api }
158
def buffer_size(img_array: np.ndarray, jpeg_subsample: int = TJSAMP_422) -> int:
159
    """Calculate maximum buffer size needed for encoding"""
160

161
@property
162
def scaling_factors(self) -> frozenset[tuple[int, int]]:
163
    """Available scaling factors for decode operations"""
164
```
165

166
[Utility Functions](./utilities.md)
167

168
## Types
169

170
```python { .api }
171
class TurboJPEG:
172
    """Main wrapper class for libjpeg-turbo operations"""
173
    def __init__(self, lib_path: str | None = None): ...
174
```