pure_jpeg 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 41b11ef04efbfb35b257ce2e93e40ae4b4fd07fec3fd05918b87eacba9a517eb
4
- data.tar.gz: 460755287366135f012fca8975822c9c50b52fa9e55144c3d1afc3c00538af37
3
+ metadata.gz: a7cba14f204519502a426b6280fa399e807bd00c8fa076c3575ef2d6eeb6063a
4
+ data.tar.gz: d2c2034fdc8d6e80cb9e457d851844647ef22ac4df0ea9cf627f360138af8efb
5
5
  SHA512:
6
- metadata.gz: 2d9c6cb32fb7197cd2fb78bf391e970729036aab6c37b4215c8fca9aef687ca2079d209367956618e6951aaf9f6e809030a64e724b8bc34c070f0de1ad373680
7
- data.tar.gz: 9d88a0c1e1d15068afe4827f838fa6736c1fde4403720edb32ac4c6e840619ccacf9ac7788e6b1ebe9df6dd8b61cc096bcac07424cd03b8ce9e89f9770ad1977
6
+ metadata.gz: 1a8da9b85c8360ff8511491b6142b0973512e771174efac2656490d446a1551bb761cce4f470bfb52bc2718cc118a2a9eb11cff8d9b114e8b2d1045718098279
7
+ data.tar.gz: b9cb05d197d502c918fb13e7d021a00093e5156b249eb81aa1be5702e8e52d5d8dc2fa9b051135bc5c049975d1391dda4f19641b958015a9a73455ebe3b1a229
data/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.0 (The big memory usage reduction release)
4
+
5
+ Big release for memory usage! An 8 megapixel JPEG was using nearly half a gig to decode 😂 The progressive decoder was hanging on to every block's DCT coefficients while it put together the full image, but it can now finish a row of blocks and reuse that space for the next row. Baseline JPEGs get the same treatment.
6
+
7
+ One thing to watch when upgrading from 0.4.1. The default decode limit is now 8,000,000 pixels, so a 4000×3000 photo will raise `PureJPEG::DecodeError`. If you meant to read a photo that big, pass the limit on that call, as so:
8
+
9
+ ```ruby
10
+ PureJPEG.read("photo.jpg", max_pixels: 12_000_000)
11
+ ```
12
+
13
+ `Decoder.new` and `Decoder.decode` take `max_pixels:` as well. A 8192 pixel limit on width and height still applies. If all you need is the size, `PureJPEG.info(path)` works above the pixel limit and now stops reading the file when it reaches the first scan marker.
14
+
3
15
  ## 0.4.1
4
16
 
5
17
  This is a robustness and compatibility release. It makes decoding more reliable
data/README.md CHANGED
@@ -152,6 +152,23 @@ pixel.b # => 97
152
152
  image = PureJPEG.read(jpeg_bytes)
153
153
  ```
154
154
 
155
+ ### Decode size limit
156
+
157
+ Starting in 0.5.0, decoding defaults to a maximum of **8,000,000 pixels** (`width * height`).
158
+ Larger images raise `PureJPEG::DecodeError` as soon as their dimensions are read,
159
+ before scan data is collected or image buffers are allocated. Set a positive
160
+ integer `max_pixels:` to lower or raise the limit for an individual decode:
161
+
162
+ ```ruby
163
+ image = PureJPEG.read("photo.jpg", max_pixels: 20_000_000)
164
+ image = PureJPEG.read(jpeg_bytes, max_pixels: 1_000_000)
165
+ ```
166
+
167
+ `PureJPEG::Decoder.decode` and `PureJPEG::Decoder.new` accept the same option.
168
+ The 8192-pixel limit on each axis still applies. Raising `max_pixels:` permits
169
+ higher memory use; the pixel limit is not a hard process-memory limit.
170
+ `PureJPEG.info` can inspect larger images without decoding their pixels.
171
+
155
172
  ### Read dimensions and metadata only
156
173
 
157
174
  ```ruby
@@ -214,9 +231,12 @@ Decoding:
214
231
  - Restart markers (DRI/RST)
215
232
  - Separate component scans in baseline JPEGs
216
233
 
217
- Encoding and decoding allow dimensions up to 8192 pixels on each axis. The
218
- decoder allocates whole-image buffers; this dimension limit is not a memory
219
- budget. `PureJPEG.info` can inspect dimensions without allocating pixel buffers.
234
+ Encoding and decoding allow dimensions up to 8192 pixels on each axis. Decoding
235
+ also limits image area to 8,000,000 pixels by default, configurable with
236
+ `max_pixels:`. The decoder keeps the compressed scans and the final packed
237
+ RGB image in memory. It reuses one MCU row of sample and coefficient buffers
238
+ across the image, including for progressive JPEGs. `PureJPEG.info` can inspect
239
+ dimensions without allocating pixel buffers and does not apply the decode pixel limit.
220
240
  Invalid or unsupported JPEG data raises `PureJPEG::DecodeError`.
221
241
 
222
242
  Not supported: arithmetic coding, 12-bit precision, RGB/CMYK JPEG color spaces,
@@ -314,6 +334,14 @@ ruby benchmark/run.rb --profile # CPU profile with Vernier (writes JSON t
314
334
  ruby benchmark/run.rb --profile-alloc # retained-object profile with Vernier
315
335
  ```
316
336
 
337
+ To measure decoder peak resident memory on macOS or Linux with GNU time,
338
+ run the following command. Each JPEG gets a fresh Ruby process. Omit the
339
+ paths to measure the bundled baseline and progressive images.
340
+
341
+ ```sh
342
+ ruby benchmark/decode_memory.rb photo.jpg progressive.jpg
343
+ ```
344
+
317
345
  ## AI Disclosure
318
346
 
319
347
  **Claude Code did the majority of the work.** The math of JPEG encoding/decoding is beyond me, except 'getting it' at a high level. I understand it like I understand the engine in my car :-) *Later update: OpenAI Codex is also reviewing and adding features now. It feels stronger in many areas.*
@@ -11,107 +11,164 @@ module PureJPEG
11
11
  # Decode a JPEG from a file path or binary string.
12
12
  #
13
13
  # @param path_or_data [String] a file path or raw JPEG bytes
14
+ # @param max_pixels [Integer] positive maximum image area
14
15
  # @return [Image] decoded image with pixel access
15
- def self.decode(path_or_data)
16
+ def self.decode(path_or_data, max_pixels: MAX_PIXELS)
16
17
  data = if path_or_data.is_a?(String) && !path_or_data.b.include?("\0") && !path_or_data.b.start_with?("\xFF\xD8".b) && File.exist?(path_or_data)
17
18
  File.binread(path_or_data)
18
19
  else
19
20
  path_or_data.b
20
21
  end
21
- new(data).decode
22
+ new(data, max_pixels: max_pixels).decode
22
23
  end
23
24
 
24
- def initialize(data)
25
+ def initialize(data, max_pixels: MAX_PIXELS)
26
+ unless max_pixels.is_a?(Integer) && max_pixels > 0
27
+ raise ArgumentError, "max_pixels must be a positive Integer"
28
+ end
25
29
  @data = data
30
+ @max_pixels = max_pixels
26
31
  end
27
32
 
28
- def decode
29
- jfif = JFIFReader.new(@data)
30
- @icc_profile = jfif.icc_profile
31
- validate_dimensions!(jfif.width, jfif.height)
32
- validate_frame_and_scans!(jfif)
33
- return decode_progressive(jfif) if jfif.progressive
33
+ # Each component holds one frame MCU row of samples (and, for progressive
34
+ # scans, coefficients). Each scan keeps its own entropy position across rows.
35
+ ComponentStrip = Struct.new(:component, :block_columns, :scan_columns, :scan_rows,
36
+ :quant_table, :samples, :coefficients)
37
+ ScanState = Struct.new(:scan, :reader, :mcu_blocks, :prev_dc, :mcu_count, :eobrun)
38
+ private_constant :ComponentStrip, :ScanState
34
39
 
40
+ def decode
41
+ jfif = JFIFReader.new(@data, max_pixels: @max_pixels)
35
42
  width = jfif.width
36
43
  height = jfif.height
44
+ validate_dimensions!(width, height)
45
+ validate_frame_and_scans!(jfif)
37
46
 
38
- comp_info = {}
39
- jfif.components.each { |c| comp_info[c.id] = c }
40
47
  max_h = jfif.components.map(&:h_sampling).max
41
48
  max_v = jfif.components.map(&:v_sampling).max
42
- mcu_px_w = max_h * 8
43
- mcu_px_h = max_v * 8
44
- mcus_x = (width + mcu_px_w - 1) / mcu_px_w
45
- mcus_y = (height + mcu_px_h - 1) / mcu_px_h
46
-
47
- channels = {}
48
- jfif.components.each do |c|
49
- ch_w = mcus_x * c.h_sampling * 8
50
- ch_h = mcus_y * c.v_sampling * 8
51
- channels[c.id] = { data: Array.new(ch_w * ch_h, 0), width: ch_w, height: ch_h }
49
+ mcu_width = max_h * 8
50
+ strip_height = max_v * 8
51
+ mcu_columns = (width + mcu_width - 1) / mcu_width
52
+ strips = {}
53
+ jfif.components.each do |comp|
54
+ block_columns = mcu_columns * comp.h_sampling
55
+ size = block_columns * comp.v_sampling * 64
56
+ scan_columns = (width * comp.h_sampling + mcu_width - 1) / mcu_width
57
+ scan_rows = (height * comp.v_sampling + strip_height - 1) / strip_height
58
+ coeffs = Array.new(size, 0) if jfif.progressive
59
+ strips[comp.id] = ComponentStrip.new(comp, block_columns, scan_columns, scan_rows,
60
+ fetch_quant_table!(jfif, comp), Array.new(size, 0), coeffs)
52
61
  end
62
+ ordered_strips = resolve_color_components(jfif.components).map { |comp| strips[comp.id] }
63
+ states = jfif.scans.map { |scan| build_scan_state(scan, strips, jfif.progressive) }
64
+ pixels = Array.new(width * height, 0)
53
65
  zigzag = Array.new(64, 0)
54
66
  dequant = Array.new(64, 0)
55
67
 
56
- jfif.scans.each do |scan|
57
- dc_tables, ac_tables = build_decode_tables(scan)
58
- reader = BitReader.new(scan.data)
59
- prev_dc = Hash.new(0)
60
- restart_interval = scan.restart_interval
61
- mcu_count = 0
62
- interleaved = scan.components.length > 1
63
- scan_components = scan.components.map do |sc|
64
- comp, dc_tab, ac_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables)
65
- [sc, comp, dc_tab, ac_tab, fetch_quant_table!(jfif, comp), channels[comp.id]]
68
+ # Scans refine the same blocks in file order. Predictors, restart counts,
69
+ # and EOB runs belong to their scan and continue into the next strip.
70
+ (0...height).step(strip_height) do |top|
71
+ states.each do |state|
72
+ decode_scan_strip(state, top / strip_height, mcu_columns, jfif.progressive, zigzag, dequant)
66
73
  end
67
- if interleaved
68
- scan_width = mcus_x
69
- scan_height = mcus_y
74
+ if jfif.progressive
75
+ ordered_strips.each { |strip| reconstruct_strip(strip, dequant) }
76
+ end
77
+ rows = [strip_height, height - top].min
78
+ if ordered_strips.length == 1
79
+ assemble_grayscale(pixels, width, top, rows, ordered_strips.first)
70
80
  else
71
- comp = scan_components[0][1]
72
- scan_width = (width * comp.h_sampling + mcu_px_w - 1) / mcu_px_w
73
- scan_height = (height * comp.v_sampling + mcu_px_h - 1) / mcu_px_h
81
+ assemble_color(pixels, width, top, rows, ordered_strips, max_h, max_v)
82
+ end
83
+ end
84
+ states.each do |state|
85
+ raise DecodeError, "Progressive EOB run exceeds scan" if state.eobrun > 0
86
+ state.reader.finish_scan!
87
+ end
88
+ Image.new(width, height, pixels, icc_profile: jfif.icc_profile)
89
+ end
90
+
91
+ private
92
+
93
+ def build_scan_state(scan, strips, progressive)
94
+ dc_tables, ac_tables = build_decode_tables(scan)
95
+ require_dc = !progressive || (scan.spectral_start == 0 && scan.successive_high == 0)
96
+ require_ac = !progressive || scan.spectral_start > 0
97
+ interleaved = scan.components.length > 1
98
+ blocks = []
99
+ scan.components.each do |sc|
100
+ strip = strips.fetch(sc.id)
101
+ dc = dc_tables[sc.dc_table_id]
102
+ ac = ac_tables[sc.ac_table_id]
103
+ if require_dc && !dc
104
+ raise DecodeError, "Component #{sc.id} references missing DC Huffman table #{sc.dc_table_id}"
105
+ end
106
+ if require_ac && !ac
107
+ raise DecodeError, "Component #{sc.id} references missing AC Huffman table #{sc.ac_table_id}"
108
+ end
109
+ # Precompute the block layout of an MCU once for this scan.
110
+ h_blocks = interleaved ? strip.component.h_sampling : 1
111
+ v_blocks = interleaved ? strip.component.v_sampling : 1
112
+ v_blocks.times do |dy|
113
+ h_blocks.times { |dx| blocks << [strip, dc, ac, h_blocks, dx, dy] }
74
114
  end
115
+ end
116
+ ScanState.new(scan, BitReader.new(scan.data), blocks, Hash.new(0), 0, 0)
117
+ end
75
118
 
76
- scan_height.times do |mcu_row|
77
- scan_width.times do |mcu_col|
78
- if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
79
- reader.read_restart((mcu_count / restart_interval - 1) % 8)
80
- prev_dc.clear
81
- end
82
- scan_components.each do |sc, comp, dc_tab, ac_tab, qt, ch|
83
- block_rows = interleaved ? comp.v_sampling : 1
84
- block_cols = interleaved ? comp.h_sampling : 1
85
- block_rows.times do |bv|
86
- block_cols.times do |bh|
87
- decode_block(reader, dc_tab, ac_tab, prev_dc, sc.id, zigzag)
88
- Quantization.dequantize_zigzag!(zigzag, qt, dequant)
89
- DCT.inverse!(dequant)
90
- bx = (mcu_col * block_cols + bh) * 8
91
- by = (mcu_row * block_rows + bv) * 8
92
- write_block(dequant, ch[:data], ch[:width], bx, by)
93
- end
119
+ def decode_scan_strip(state, strip_index, mcu_columns, progressive, zigzag, dequant)
120
+ scan = state.scan
121
+ reader = state.reader
122
+ interval = scan.restart_interval
123
+ blocks = state.mcu_blocks
124
+ columns = mcu_columns
125
+ rows = 1
126
+ if scan.components.length == 1
127
+ # A non-interleaved MCU is one block. Omit the frame's padding blocks
128
+ # at the right and bottom edges while keeping the padded storage stride.
129
+ strip = blocks.first[0]
130
+ v = strip.component.v_sampling
131
+ columns = strip.scan_columns
132
+ rows = [v, strip.scan_rows - strip_index * v].min
133
+ return decode_ac_strip(state, rows, columns) if scan.spectral_start > 0
134
+ end
135
+
136
+ count = state.mcu_count
137
+ rows.times do |row|
138
+ columns.times do |col|
139
+ if interval > 0 && count > 0 && (count % interval) == 0
140
+ reader.read_restart((count / interval - 1) % 8)
141
+ state.prev_dc.clear
142
+ end
143
+ # An indexed loop avoids a per-MCU closure allocation on Spinel.
144
+ index = 0
145
+ while index < blocks.length
146
+ strip, dc, ac, h_blocks, dx, dy = blocks[index]
147
+ index += 1
148
+ bx = col * h_blocks + dx
149
+ by = row + dy
150
+ if progressive
151
+ offset = (by * strip.block_columns + bx) * 64
152
+ coeffs = strip.coefficients
153
+ if scan.successive_high == 0
154
+ id = strip.component.id
155
+ state.prev_dc[id] = prog_dc_first(reader, dc, state.prev_dc[id], coeffs, offset, scan.successive_low)
156
+ else
157
+ prog_dc_refine(reader, coeffs, offset, scan.successive_low)
94
158
  end
159
+ else
160
+ decode_block(reader, dc, ac, state.prev_dc, strip.component.id, zigzag)
161
+ Quantization.dequantize_zigzag!(zigzag, strip.quant_table, dequant)
162
+ DCT.inverse!(dequant)
163
+ write_block(dequant, strip.samples, strip.block_columns * 8, bx * 8, by * 8)
95
164
  end
96
- mcu_count += 1
97
165
  end
166
+ count += 1
98
167
  end
99
- reader.finish_scan!
100
- end
101
-
102
- # Assemble pixels
103
- num_components = jfif.components.length
104
- if num_components == 1
105
- assemble_grayscale(width, height, channels, jfif.components[0])
106
- elsif num_components == 3
107
- assemble_color(width, height, channels, jfif.components, max_h, max_v)
108
- else
109
- raise DecodeError, "Unsupported number of components: #{num_components}"
110
168
  end
169
+ state.mcu_count = count
111
170
  end
112
171
 
113
- private
114
-
115
172
  def build_decode_tables(scan)
116
173
  dc_tables = {}
117
174
  ac_tables = {}
@@ -197,183 +254,52 @@ module PureJPEG
197
254
 
198
255
  # --- Progressive JPEG decoding ---
199
256
 
200
- def decode_progressive(jfif)
201
- width = jfif.width
202
- height = jfif.height
203
-
204
- comp_info = {}
205
- jfif.components.each { |c| comp_info[c.id] = c }
206
-
207
- max_h = jfif.components.map(&:h_sampling).max
208
- max_v = jfif.components.map(&:v_sampling).max
209
-
210
- mcu_px_w = max_h * 8
211
- mcu_px_h = max_v * 8
212
- mcus_x = (width + mcu_px_w - 1) / mcu_px_w
213
- mcus_y = (height + mcu_px_h - 1) / mcu_px_h
214
-
215
- # Coefficient buffers per component (zigzag order, pre-dequantization)
216
- coeffs = {}
217
- comp_blocks = {}
218
- jfif.components.each do |c|
219
- bx = mcus_x * c.h_sampling
220
- by = mcus_y * c.v_sampling
221
- coeffs[c.id] = Array.new(bx * by * 64, 0)
222
- actual_bx = (width * c.h_sampling + mcu_px_w - 1) / mcu_px_w
223
- actual_by = (height * c.v_sampling + mcu_px_h - 1) / mcu_px_h
224
- # Interleaved scans include MCU padding; single-component scans do not.
225
- # Keep the storage stride separate from the actual scan dimensions.
226
- comp_blocks[c.id] = [bx, by, actual_bx, actual_by]
227
- end
228
-
229
- jfif.scans.each do |scan|
230
- restart_interval = scan.restart_interval
231
- # Build Huffman tables from this scan's snapshot (tables change between scans)
232
- dc_tables = {}
233
- ac_tables = {}
234
- scan.huffman_tables.each do |(table_class, table_id), info|
235
- table = Huffman::DecodeTable.new(info[:bits], info[:values])
236
- if table_class == 0
237
- dc_tables[table_id] = table
238
- else
239
- ac_tables[table_id] = table
240
- end
241
- end
242
-
243
- reader = BitReader.new(scan.data)
244
- ss = scan.spectral_start
245
- se = scan.spectral_end
246
- ah = scan.successive_high
247
- al = scan.successive_low
248
-
249
- if scan.components.length == 1
250
- prog_scan_non_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
251
- coeffs, comp_blocks, restart_interval, ss, se, ah, al)
252
- else
253
- prog_scan_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
254
- coeffs, comp_blocks, mcus_x, mcus_y, restart_interval, ss, se, ah, al)
255
- end
256
- reader.finish_scan!
257
- end
258
-
259
- # Reconstruct: unzigzag/dequantize, IDCT, write to channel buffers
260
- padded_w = mcus_x * mcu_px_w
261
- padded_h = mcus_y * mcu_px_h
262
- channels = {}
263
- jfif.components.each do |c|
264
- ch_w = (padded_w * c.h_sampling) / max_h
265
- ch_h = (padded_h * c.v_sampling) / max_v
266
- channels[c.id] = { data: Array.new(ch_w * ch_h, 0), width: ch_w, height: ch_h }
267
- end
268
-
269
- dequant = Array.new(64, 0)
270
-
271
- jfif.components.each do |c|
272
- qt = fetch_quant_table!(jfif, c)
273
- ch = channels[c.id]
274
- coeff_buf = coeffs[c.id]
275
- bx_count, by_count = comp_blocks[c.id]
276
-
277
- by_count.times do |block_y|
278
- bx_count.times do |block_x|
279
- offset = (block_y * bx_count + block_x) * 64
280
- Quantization.dequantize_zigzag!(coeff_buf, qt, dequant, offset)
281
- DCT.inverse!(dequant)
282
- write_block(dequant, ch[:data], ch[:width], block_x * 8, block_y * 8)
283
- end
284
- end
285
- end
286
-
287
- num_components = jfif.components.length
288
- if num_components == 1
289
- assemble_grayscale(width, height, channels, jfif.components[0])
290
- elsif num_components == 3
291
- assemble_color(width, height, channels, jfif.components, max_h, max_v)
292
- else
293
- raise DecodeError, "Unsupported number of components: #{num_components}"
294
- end
295
- end
296
-
297
- def prog_scan_non_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
298
- coeffs, comp_blocks, restart_interval, ss, se, ah, al)
299
- sc = scan.components[0]
300
- comp, dc_tab, ac_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables,
301
- require_dc: ss == 0 && ah == 0, require_ac: ss > 0)
302
- coeff_buf = coeffs[comp.id]
303
- bx_count, _by_count, actual_bx, actual_by = comp_blocks[comp.id]
304
-
305
- prev_dc = 0
306
- eobrun = 0
307
- mcu_count = 0
308
-
309
- actual_by.times do |block_y|
310
- actual_bx.times do |block_x|
311
- if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
257
+ # Progressive AC scans always visit one block per MCU. An EOB run may
258
+ # span several rows, including the boundary between two strips.
259
+ def decode_ac_strip(state, rows, columns)
260
+ strip, _dc, ac = state.mcu_blocks.first
261
+ coeffs = strip.coefficients
262
+ scan = state.scan
263
+ reader = state.reader
264
+ ss = scan.spectral_start
265
+ se = scan.spectral_end
266
+ al = scan.successive_low
267
+ first = scan.successive_high == 0
268
+ interval = scan.restart_interval
269
+ count = state.mcu_count
270
+ eobrun = state.eobrun
271
+ rows.times do |row|
272
+ offset = row * strip.block_columns * 64
273
+ columns.times do
274
+ if interval > 0 && count > 0 && (count % interval) == 0
312
275
  raise DecodeError, "Progressive EOB run crosses restart boundary" if eobrun > 0
313
- reader.read_restart((mcu_count / restart_interval - 1) % 8)
314
- prev_dc = 0
315
- eobrun = 0
276
+ reader.read_restart((count / interval - 1) % 8)
316
277
  end
317
-
318
- offset = (block_y * bx_count + block_x) * 64
319
-
320
- if ss == 0
321
- if ah == 0
322
- prev_dc = prog_dc_first(reader, dc_tab, prev_dc, coeff_buf, offset, al)
323
- else
324
- prog_dc_refine(reader, coeff_buf, offset, al)
325
- end
278
+ if first
279
+ eobrun = prog_ac_first(reader, ac, coeffs, offset, ss, se, al, eobrun)
326
280
  else
327
- if ah == 0
328
- eobrun = prog_ac_first(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
329
- else
330
- eobrun = prog_ac_refine(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
331
- end
281
+ eobrun = prog_ac_refine(reader, ac, coeffs, offset, ss, se, al, eobrun)
332
282
  end
333
-
334
- mcu_count += 1
283
+ count += 1
284
+ offset += 64
335
285
  end
336
286
  end
337
- raise DecodeError, "Progressive EOB run exceeds scan" if eobrun > 0
287
+ state.mcu_count = count
288
+ state.eobrun = eobrun
338
289
  end
339
290
 
340
- def prog_scan_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
341
- coeffs, comp_blocks, mcus_x, mcus_y, restart_interval, ss, se, ah, al)
342
- prev_dc = Hash.new(0)
343
- mcu_count = 0
344
-
345
- scan_components = scan.components.map do |sc|
346
- comp, dc_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables,
347
- require_dc: ah == 0, require_ac: false)
348
- [sc, comp, dc_tab, coeffs[comp.id], comp_blocks[comp.id][0]]
349
- end
350
-
351
- mcus_y.times do |mcu_row|
352
- mcus_x.times do |mcu_col|
353
- if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
354
- reader.read_restart((mcu_count / restart_interval - 1) % 8)
355
- prev_dc.clear
356
- end
357
-
358
- scan_components.each do |sc, comp, dc_tab, coeff_buf, bx_count|
359
- comp.v_sampling.times do |bv|
360
- comp.h_sampling.times do |bh|
361
- block_x = mcu_col * comp.h_sampling + bh
362
- block_y = mcu_row * comp.v_sampling + bv
363
- offset = (block_y * bx_count + block_x) * 64
364
-
365
- if ah == 0
366
- prev_dc[sc.id] = prog_dc_first(reader, dc_tab, prev_dc[sc.id], coeff_buf, offset, al)
367
- else
368
- prog_dc_refine(reader, coeff_buf, offset, al)
369
- end
370
- end
371
- end
372
- end
373
-
374
- mcu_count += 1
291
+ def reconstruct_strip(strip, dequant)
292
+ coeffs = strip.coefficients
293
+ columns = strip.block_columns
294
+ strip.component.v_sampling.times do |by|
295
+ columns.times do |bx|
296
+ offset = (by * columns + bx) * 64
297
+ Quantization.dequantize_zigzag!(coeffs, strip.quant_table, dequant, offset)
298
+ DCT.inverse!(dequant)
299
+ write_block(dequant, strip.samples, columns * 8, bx * 8, by * 8)
375
300
  end
376
301
  end
302
+ coeffs.fill(0)
377
303
  end
378
304
 
379
305
  def prog_dc_first(reader, dc_tab, prev_dc, coeff_buf, offset, al)
@@ -541,23 +467,6 @@ module PureJPEG
541
467
  end
542
468
  end
543
469
 
544
- def resolve_scan_references!(scan_component, comp_info, dc_tables, ac_tables, require_dc: true, require_ac: true)
545
- comp = comp_info[scan_component.id]
546
- raise DecodeError, "Scan references unknown component id #{scan_component.id}" unless comp
547
-
548
- dc_tab = dc_tables[scan_component.dc_table_id]
549
- if require_dc && !dc_tab
550
- raise DecodeError, "Component #{scan_component.id} references missing DC Huffman table #{scan_component.dc_table_id}"
551
- end
552
-
553
- if require_ac
554
- ac_tab = ac_tables[scan_component.ac_table_id]
555
- raise DecodeError, "Component #{scan_component.id} references missing AC Huffman table #{scan_component.ac_table_id}" unless ac_tab
556
- end
557
-
558
- [comp, dc_tab, ac_tab]
559
- end
560
-
561
470
  def fetch_quant_table!(jfif, comp)
562
471
  qt = jfif.component_quant_tables[comp.id]
563
472
  raise DecodeError, "Component #{comp.id} references missing quantization table #{comp.qt_id}" unless qt
@@ -565,20 +474,17 @@ module PureJPEG
565
474
  qt
566
475
  end
567
476
 
568
- def assemble_grayscale(width, height, channels, comp)
569
- ch = channels[comp.id]
570
- ch_data = ch[:data]
571
- ch_width = ch[:width]
572
- pixels = Array.new(width * height)
477
+ def assemble_grayscale(pixels, width, top, height, strip)
478
+ ch_data = strip.samples
479
+ ch_width = strip.block_columns * 8
573
480
  height.times do |y|
574
481
  src_row = y * ch_width
575
- dst_row = y * width
482
+ dst_row = (top + y) * width
576
483
  width.times do |x|
577
484
  v = ch_data[src_row + x]
578
485
  pixels[dst_row + x] = (v << 16) | (v << 8) | v
579
486
  end
580
487
  end
581
- Image.new(width, height, pixels, icc_profile: @icc_profile)
582
488
  end
583
489
 
584
490
  # Fixed-point coefficients (scaled by 2^16) for YCbCr→RGB.
@@ -588,31 +494,23 @@ module PureJPEG
588
494
  FP_B_CB = 116130 # 1.772 * 65536
589
495
  FP_HALF = 32768 # rounding bias
590
496
 
591
- def assemble_color(width, height, channels, components, max_h, max_v)
592
- # Upsample chroma channels if needed and convert YCbCr to RGB
593
- y_comp, cb_comp, cr_comp = resolve_color_components(components)
594
-
595
- y_ch = channels[y_comp.id]
596
- cb_ch = channels[cb_comp.id]
597
- cr_ch = channels[cr_comp.id]
598
-
599
- y_data = y_ch[:data]
600
- cb_data = cb_ch[:data]
601
- cr_data = cr_ch[:data]
602
- y_stride = y_ch[:width]
603
- y_h = y_comp.h_sampling
604
- y_v = y_comp.v_sampling
605
- cb_stride = cb_ch[:width]
606
- cr_stride = cr_ch[:width]
607
- cb_h = cb_comp.h_sampling
608
- cb_v = cb_comp.v_sampling
609
- cr_h = cr_comp.h_sampling
610
- cr_v = cr_comp.v_sampling
611
-
612
- pixels = Array.new(width * height)
497
+ def assemble_color(pixels, width, top, height, strips, max_h, max_v)
498
+ y_ch, cb_ch, cr_ch = strips
499
+ y_data = y_ch.samples
500
+ cb_data = cb_ch.samples
501
+ cr_data = cr_ch.samples
502
+ y_stride = y_ch.block_columns * 8
503
+ y_h = y_ch.component.h_sampling
504
+ y_v = y_ch.component.v_sampling
505
+ cb_stride = cb_ch.block_columns * 8
506
+ cr_stride = cr_ch.block_columns * 8
507
+ cb_h = cb_ch.component.h_sampling
508
+ cb_v = cb_ch.component.v_sampling
509
+ cr_h = cr_ch.component.h_sampling
510
+ cr_v = cr_ch.component.v_sampling
613
511
 
614
512
  height.times do |py|
615
- dst_row = py * width
513
+ dst_row = (top + py) * width
616
514
  y_row = ((py * y_v) / max_v) * y_stride
617
515
 
618
516
  # Chroma coordinates (nearest-neighbor upsampling)
@@ -639,8 +537,6 @@ module PureJPEG
639
537
  pixels[dst_row + px] = (r << 16) | (g << 8) | b
640
538
  end
641
539
  end
642
-
643
- Image.new(width, height, pixels, icc_profile: @icc_profile)
644
540
  end
645
541
 
646
542
  def resolve_color_components(components)
@@ -12,10 +12,16 @@ module PureJPEG
12
12
  attr_accessor :restart_interval
13
13
  end
14
14
 
15
- def initialize(data, stop_after_frame: false, metadata_only: false)
16
- @data = data.b
15
+ def initialize(data, stop_after_frame: false, metadata_only: false, max_pixels: nil)
16
+ if metadata_only && !data.is_a?(String)
17
+ @header_io = data
18
+ @data = "".b
19
+ else
20
+ @data = data.b
21
+ end
17
22
  @stop_after_frame = stop_after_frame
18
23
  @metadata_only = metadata_only
24
+ @max_pixels = max_pixels
19
25
  @pos = 0
20
26
  @quant_tables = {}
21
27
  @huffman_tables = {}
@@ -44,8 +50,8 @@ module PureJPEG
44
50
 
45
51
  loop do
46
52
  # Header-only input is useful for metadata queries, even without SOS.
47
- return if @metadata_only && @width && @pos == @data.bytesize
48
- marker = read_marker
53
+ marker = read_marker(@metadata_only && @width)
54
+ return if marker.nil?
49
55
  case marker
50
56
  when 0xE2 # APP2 (may contain ICC profile)
51
57
  parse_app2
@@ -95,19 +101,26 @@ module PureJPEG
95
101
  end
96
102
  end
97
103
 
98
- def read_byte
99
- raise PureJPEG::DecodeError, "Unexpected end of JPEG data" if @pos >= @data.bytesize
100
- byte = @data.getbyte(@pos)
101
- @pos += 1
102
- byte
104
+ def read_byte(allow_eof = false)
105
+ if @pos < @data.bytesize
106
+ byte = @data.getbyte(@pos)
107
+ @pos += 1
108
+ return byte
109
+ end
110
+ if @header_io
111
+ byte = @header_io.read(1)&.getbyte(0)
112
+ return byte if byte
113
+ end
114
+ raise PureJPEG::DecodeError, "Unexpected end of JPEG data" unless allow_eof
103
115
  end
104
116
 
105
117
  def read_u16
106
118
  (read_byte << 8) | read_byte
107
119
  end
108
120
 
109
- def read_marker
110
- byte = read_byte
121
+ def read_marker(allow_eof = false)
122
+ byte = read_byte(allow_eof)
123
+ return if byte.nil?
111
124
  raise PureJPEG::DecodeError, "Expected 0xFF, got 0x#{byte.to_s(16)}" unless byte == 0xFF
112
125
  # Skip padding 0xFF bytes
113
126
  code = read_byte
@@ -213,6 +226,10 @@ module PureJPEG
213
226
  @precision = read_byte
214
227
  @height = read_u16
215
228
  @width = read_u16
229
+ # Reject oversized decodes before collecting scans or allocating image buffers.
230
+ if @max_pixels && @width * @height > @max_pixels
231
+ raise DecodeError, "Image too large: #{@width}x#{@height} (max #{@max_pixels} pixels)"
232
+ end
216
233
  num_components = read_byte
217
234
  ensure_remaining_in_segment!(end_pos, num_components * 3, "SOF")
218
235
 
@@ -268,6 +285,12 @@ module PureJPEG
268
285
  length = read_u16
269
286
  raise PureJPEG::DecodeError, "Invalid JPEG segment length: #{length}" if length < 2
270
287
 
288
+ # File metadata queries buffer one segment at a time. Its parser uses
289
+ # the same offsets and truncation checks as it does for in-memory data.
290
+ if @header_io
291
+ @data = @header_io.read(length - 2) || "".b
292
+ @pos = 0
293
+ end
271
294
  end_pos = @pos + length - 2
272
295
  if end_pos > @data.bytesize
273
296
  raise PureJPEG::DecodeError, "JPEG segment length exceeds available data"
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module PureJPEG
4
- VERSION = "0.4.1"
4
+ VERSION = "0.5.0"
5
5
  end
data/lib/pure_jpeg.rb CHANGED
@@ -31,6 +31,9 @@ module PureJPEG
31
31
  # Maximum image dimension (width or height) allowed for encoding and decoding.
32
32
  MAX_DIMENSION = 8192
33
33
 
34
+ # Default maximum decoded image area. Override per read with +max_pixels:+.
35
+ MAX_PIXELS = 8_000_000
36
+
34
37
  # Encode a pixel source as a JPEG.
35
38
  #
36
39
  # @param source [#width, #height, #[]] any object responding to +width+,
@@ -61,9 +64,10 @@ module PureJPEG
61
64
  # Decode a JPEG from a file path or binary string.
62
65
  #
63
66
  # @param path_or_data [String] a file path or raw JPEG bytes
67
+ # @param max_pixels [Integer] positive maximum image area (default: 8,000,000)
64
68
  # @return [Image] decoded image with pixel access
65
- def self.read(path_or_data)
66
- Decoder.decode(path_or_data)
69
+ def self.read(path_or_data, max_pixels: MAX_PIXELS)
70
+ Decoder.decode(path_or_data, max_pixels: max_pixels)
67
71
  end
68
72
 
69
73
  # Read JPEG dimensions and basic frame metadata without decoding scan data.
@@ -71,13 +75,12 @@ module PureJPEG
71
75
  # @param path_or_data [String] a file path or raw JPEG bytes
72
76
  # @return [Info] frame metadata and complete ICC profile from headers before SOS
73
77
  def self.info(path_or_data)
74
- data = if path_or_data.is_a?(String) && !path_or_data.b.include?("\0") && !path_or_data.b.start_with?("\xFF\xD8".b) && File.exist?(path_or_data)
75
- File.binread(path_or_data)
78
+ jfif = if path_or_data.is_a?(String) && !path_or_data.b.start_with?("\xFF\xD8".b) && !path_or_data.b.include?("\0") && File.exist?(path_or_data)
79
+ File.open(path_or_data, "rb") { |file| JFIFReader.new(file, metadata_only: true) }
76
80
  else
77
- path_or_data.b
81
+ JFIFReader.new(path_or_data.b, metadata_only: true)
78
82
  end
79
83
 
80
- jfif = JFIFReader.new(data, metadata_only: true)
81
84
  raise DecodeError, "JPEG frame header not found" unless jfif.width && jfif.height
82
85
 
83
86
  Info.new(
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pure_jpeg
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.1
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Peter Cooper