0
# JPEG Decoding
1

2
Core decoding functionality for converting JPEG data to numpy arrays, with support for various pixel formats, scaling factors, direct rescaling during decode, YUV output formats, and in-place decoding for memory efficiency.
3

4
## Capabilities
5

6
### Header Decoding
7

8
Decode JPEG header information without full image decompression to get image properties and metadata.
9

10
```python { .api }
11
def decode_header(jpeg_buf: bytes) -> tuple[int, int, int, int]:
12
    """
13
    Decode JPEG header and return image properties.
14
    
15
    Args:
16
        jpeg_buf: JPEG data as bytes
17
    
18
    Returns:
19
        tuple: (width, height, jpeg_subsample, jpeg_colorspace)
20
            - width: Image width in pixels
21
            - height: Image height in pixels  
22
            - jpeg_subsample: Subsampling type (TJSAMP_* constants)
23
            - jpeg_colorspace: Color space (TJCS_* constants)
24
    """
25
```
26

27
### Standard Decoding
28

29
Decode JPEG data to numpy arrays with various pixel format options, scaling, and performance flags.
30

31
```python { .api }
32
def decode(
33
    jpeg_buf: bytes, 
34
    pixel_format: int = TJPF_BGR, 
35
    scaling_factor: tuple[int, int] | None = None, 
36
    flags: int = 0, 
37
    dst: np.ndarray | None = None
38
) -> np.ndarray:
39
    """
40
    Decode JPEG memory buffer to numpy array.
41
    
42
    Args:
43
        jpeg_buf: JPEG data as bytes
44
        pixel_format: Output pixel format (TJPF_* constants)
45
        scaling_factor: Optional scaling as (numerator, denominator) tuple
46
        flags: Decoding flags (TJFLAG_* constants)
47
        dst: Optional pre-allocated output array for in-place decoding
48
    
49
    Returns:
50
        np.ndarray: Decoded image array with shape (height, width, channels)
51
    """
52
```
53

54
### YUV Decoding
55

56
Decode JPEG directly to YUV format, useful for video processing and when avoiding color space conversion.
57

58
```python { .api }
59
def decode_to_yuv(
60
    jpeg_buf: bytes, 
61
    scaling_factor: tuple[int, int] | None = None, 
62
    pad: int = 4, 
63
    flags: int = 0
64
) -> tuple[np.ndarray, list[tuple[int, int]]]:
65
    """
66
    Decode JPEG memory buffer to YUV array.
67
    
68
    Args:
69
        jpeg_buf: JPEG data as bytes
70
        scaling_factor: Optional scaling as (numerator, denominator) tuple
71
        pad: Padding bytes for YUV planes
72
        flags: Decoding flags (TJFLAG_* constants)
73
    
74
    Returns:
75
        tuple: (buffer_array, plane_sizes)
76
            - buffer_array: YUV data as numpy array
77
            - plane_sizes: List of (height, width) tuples for each plane
78
    """
79

80
def decode_to_yuv_planes(
81
    jpeg_buf: bytes, 
82
    scaling_factor: tuple[int, int] | None = None, 
83
    strides: tuple[int, int, int] = (0, 0, 0), 
84
    flags: int = 0
85
) -> list[np.ndarray]:
86
    """
87
    Decode JPEG memory buffer to separate YUV planes.
88
    
89
    Args:
90
        jpeg_buf: JPEG data as bytes
91
        scaling_factor: Optional scaling as (numerator, denominator) tuple
92
        strides: Stride values for each plane (0 = automatic)
93
        flags: Decoding flags (TJFLAG_* constants)
94
    
95
    Returns:
96
        list[np.ndarray]: List of YUV planes as separate arrays
97
    """
98
```
99

100
## Constants
101

102
### Pixel Formats
103

104
```python { .api }
105
TJPF_RGB: int      # RGB pixel format
106
TJPF_BGR: int      # BGR pixel format (default)
107
TJPF_RGBX: int     # RGBX pixel format  
108
TJPF_BGRX: int     # BGRX pixel format
109
TJPF_XBGR: int     # XBGR pixel format
110
TJPF_XRGB: int     # XRGB pixel format
111
TJPF_GRAY: int     # Grayscale pixel format
112
TJPF_RGBA: int     # RGBA pixel format
113
TJPF_BGRA: int     # BGRA pixel format
114
TJPF_ABGR: int     # ABGR pixel format
115
TJPF_ARGB: int     # ARGB pixel format
116
TJPF_CMYK: int     # CMYK pixel format
117
```
118

119
### Color Spaces
120

121
```python { .api }
122
TJCS_RGB: int      # RGB color space
123
TJCS_YCbCr: int    # YCbCr color space
124
TJCS_GRAY: int     # Grayscale color space
125
TJCS_CMYK: int     # CMYK color space
126
TJCS_YCCK: int     # YCCK color space
127
```
128

129
### Decoding Flags
130

131
```python { .api }
132
TJFLAG_BOTTOMUP: int       # Bottom-up pixel order
133
TJFLAG_FASTUPSAMPLE: int   # Fast upsampling (lower quality)
134
TJFLAG_FASTDCT: int        # Fast DCT (lower quality)
135
TJFLAG_ACCURATEDCT: int    # Accurate DCT (higher quality)
136
TJFLAG_STOPONWARNING: int  # Stop on warning
137
TJFLAG_LIMITSCANS: int     # Limit progressive scans
138
```
139

140
### Subsampling Constants
141

142
```python { .api }
143
TJSAMP_444: int    # 4:4:4 subsampling (no subsampling)
144
TJSAMP_422: int    # 4:2:2 subsampling
145
TJSAMP_420: int    # 4:2:0 subsampling
146
TJSAMP_GRAY: int   # Grayscale
147
TJSAMP_440: int    # 4:4:0 subsampling
148
TJSAMP_411: int    # 4:1:1 subsampling
149
TJSAMP_441: int    # 4:4:1 subsampling
150
```
151

152
## Usage Examples
153

154
### Basic Decoding
155

156
```python
157
from turbojpeg import TurboJPEG, TJPF_RGB
158

159
jpeg = TurboJPEG()
160

161
# Decode to BGR (default)
162
with open('image.jpg', 'rb') as f:
163
    bgr_image = jpeg.decode(f.read())
164

165
# Decode to RGB  
166
with open('image.jpg', 'rb') as f:
167
    rgb_image = jpeg.decode(f.read(), pixel_format=TJPF_RGB)
168

169
# Decode to grayscale
170
with open('image.jpg', 'rb') as f:
171
    gray_image = jpeg.decode(f.read(), pixel_format=TJPF_GRAY)
172
```
173

174
### Scaled Decoding
175

176
```python
177
# Decode at half resolution
178
with open('image.jpg', 'rb') as f:
179
    half_image = jpeg.decode(f.read(), scaling_factor=(1, 2))
180

181
# Check available scaling factors
182
print("Available scaling factors:", jpeg.scaling_factors)
183
```
184

185
### Fast Decoding
186

187
```python
188
from turbojpeg import TJFLAG_FASTUPSAMPLE, TJFLAG_FASTDCT
189

190
# Fast decoding (lower quality, higher speed)
191
with open('image.jpg', 'rb') as f:
192
    fast_image = jpeg.decode(
193
        f.read(), 
194
        flags=TJFLAG_FASTUPSAMPLE|TJFLAG_FASTDCT
195
    )
196
```
197

198
### In-Place Decoding
199

200
```python
201
import numpy as np
202

203
# Pre-allocate array for in-place decoding
204
with open('image.jpg', 'rb') as f:
205
    # Get dimensions first
206
    width, height, _, _ = jpeg.decode_header(f.read())
207
    
208
    # Create pre-allocated array
209
    f.seek(0)
210
    img_array = np.empty((height, width, 3), dtype=np.uint8)
211
    
212
    # Decode in-place
213
    result = jpeg.decode(f.read(), dst=img_array)
214
    assert result is img_array  # Same object
215
```
216

217
### YUV Decoding
218

219
```python
220
# Decode to YUV buffer
221
with open('image.jpg', 'rb') as f:
222
    yuv_buffer, plane_sizes = jpeg.decode_to_yuv(f.read())
223
    print("YUV buffer size:", yuv_buffer.size)
224
    print("Plane sizes:", plane_sizes)
225

226
# Decode to separate YUV planes
227
with open('image.jpg', 'rb') as f:
228
    yuv_planes = jpeg.decode_to_yuv_planes(f.read())
229
    print("Y plane shape:", yuv_planes[0].shape)
230
    print("U plane shape:", yuv_planes[1].shape)  
231
    print("V plane shape:", yuv_planes[2].shape)
232
```