pure_jpeg 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 780f932b176fecdb5daab2546909fe2610325e54f7364cf482e3e2652ab614a5
-  data.tar.gz: 1fbc350f25d09b989ee6262e077bb36847c6637db325fb03c29f2083bb0ec973
+  metadata.gz: 81f59b74746cbb7c575aa22e250667b8b126a542613833f2e45b57685fed02c0
+  data.tar.gz: 87fb8c2b6dd5035d93c4326a37fac8e43ade2af88f92a3dd1f7761960f675126
 SHA512:
-  metadata.gz: a385db40804bf4a992d78253ba619e90b147aa5be7808b341398918f5f36c3593fbd1a979aaad9729ad874f2427fe15d31fc9a0413e5f7ea98ee44e43e125f2d
-  data.tar.gz: b9f5581f4c4f27f42460961b3b4231fd94b45be130fbdce74a28bc4888f2a2f3de08fd43b9e3efc782ccb6b4f260aa8484ff7794e7bde1362018dc3deb282b26
+  metadata.gz: 930f8db2b6ab86080c115e77f56e0918853e455dbcd18129daa5aaca77715df198a502010ae218275799e8b364f115232e11139ffcb42ca981c57478ef12b45b
+  data.tar.gz: 54c50b3a2316c6fa0b9db38fcabdd589bcc17d2edfeff653a28ec4054a72c2b5615eef5fd9f123fb31ce56448864495f49942bf63c4536d00c21fd4e7a6eb4f2

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.4.0
+
+Performance:
+
+- Faster Huffman coding and decoding, with scan references resolved once per scan
+- Combined quantization and zigzag passes, including direct reconstruction from progressive coefficient buffers
+- Color encoding downsamples chroma two rows at a time instead of allocating full-resolution chroma images
+- Block-based `RawSource` construction avoids allocating pixels that would immediately be replaced
+- Measured encode/decode times reduced by roughly 12–28% on Ruby 4.0.2 with YJIT; baseline decode allocations fell from 76,994 to 114 on the bundled 1024x1024 benchmark
+- Encoding array storage allocated for that image fell from 29.4 MB to 12.6 MB, with encoded bytes and decoded pixels preserved in equivalence checks
+
+Compatibility and testing:
+
+- Experimental Spinel compatibility, tested at revision `7f08abd9`, with benchmarks and a `rake test:spinel` proof-of-concept runner
+- Spinel currently passes seven of the eight selected RawSource tests; the remaining test fails because `respond_to?` is unavailable on its pixel struct. See `test/SPINEL.md` for details
+- Added regression tests for quantization rounding, progressive coefficient offsets, and chroma downsampling edges
+- Updated performance comparisons for CRuby, TruffleRuby, JRuby, and Spinel
+
+## 0.3.3
+
+New features:
+
+- `PureJPEG.from_chunky_png` accepts `background: [r, g, b]` to composite transparent PNG pixels before JPEG encoding
+
+Fixes:
+
+- Invalid `quality` and `chroma_quality` values now raise clear `ArgumentError`s
+- `Image#[]` and `Image#[]=` now raise `IndexError` for out-of-bounds coordinates
+- Hardened JFIF segment length validation for malformed JPEG input
+
 ## 0.3.2
 
 Performance:

data/README.md

@@ -6,7 +6,7 @@
 
 Convert PNG or other pixel data to JPEG. Or the other way! Implements baseline JPEG encoding (DCT, Huffman, 4:2:0 chroma subsampling) and decodes both baseline and progressive JPEGs. Exposes a variety of encoding options to adjust parts of the JPEG pipeline not normally available (I needed this to recreate the JPEG compression styles of older digital cameras - don't ask..)
 
-It works on CRuby 3.0+, TruffleRuby 33.0, and JRuby 10.0.
+It works on CRuby 3.0+, TruffleRuby 33.0, JRuby 10.0, and [Spinel](https://github.com/matz/spinel) (tested at `7f08abd9`). There's *almost* 100% test coverage - I need to find some "broken" JPEGs to do the rest (hit me up if you have any sources..)
 
 > [!NOTE]
 > Rubyists might find the [AI Disclosure](#ai-disclosure) section below of interest.
@@ -23,7 +23,7 @@ gem "pure_jpeg"
 gem install pure_jpeg
 ```
 
-There are no runtime dependencies. [ChunkyPNG](https://github.com/wvanbergen/chunky_png) is optional (though quite useful) if you want to use `from_chunky_png`. I have a pure PNG encoder/decoder not far behind this that will ultimately plug in nicely too to get 100% pure Ruby graphical bliss ;-)
+There are no runtime dependencies. [ChunkyPNG](https://github.com/wvanbergen/chunky_png) is optional (though quite useful) if you want to use `from_chunky_png`.
 
 `examples/` contains some useful example scripts for basic JPEG to PNG and PNG to JPEG conversion if you want to do some quick tests without writing code.
 
@@ -39,6 +39,13 @@ image = ChunkyPNG::Image.from_file("photo.png")
 PureJPEG.from_chunky_png(image, quality: 80).write("photo.jpg")
 ```
 
+If you want transparent pixels composited against a solid color instead of
+using the PNG's hidden RGB values, pass an RGB background:
+
+```ruby
+PureJPEG.from_chunky_png(image, background: [255, 255, 255], quality: 80).write("photo.jpg")
+```
+
 ### From any pixel source
 
 PureJPEG accepts any object that responds to `width`, `height`, and `[x, y]` (returning an object with `.r`, `.g`, `.b` in 0-255):
@@ -99,7 +106,7 @@ Here's a quick example of sort of the "old digital camera" effect I was looking
 </tr>
 </table>
 
-And here's what happens when you convert a PNG with transparency — JPEG doesn't support alpha, so the hidden RGB data behind transparent pixels bleeds through:
+And here's what happens when you convert a PNG with transparency without a `background:` — JPEG doesn't support alpha, so the hidden RGB data behind transparent pixels bleeds through:
 
 <table>
 <tr>
@@ -112,7 +119,7 @@ And here's what happens when you convert a PNG with transparency — JPEG doesn'
 </tr>
 </table>
 
-I consider this a feature but you may consider it a deficiency and that a default background of white should be applied. This may be something I'll add if anyone wants it!
+Pass `background: [255, 255, 255]` to composite transparent pixels over white, or any other `[r, g, b]` color you prefer.
 
 Note that each stage of the JPEG pipeline is a separate module, so individual components (DCT, quantization, Huffman coding) can be replaced or extended independently which is kinda my plan here as I made this to play around with effects.
 
@@ -198,25 +205,79 @@ Possible future improvements: ICC profile rendering/conversion.
 
 ## Performance
 
-On a 1024x1024 image (Ruby 4.0.2 with YJIT on an M5):
+On the bundled 1024x1024 images (Apple M5, median of 15 runs after 20 seconds of warmup per operation):
+
+| Operation | CRuby 4.0.2 (YJIT) | TruffleRuby 34.0.1 | JRuby 9.4.14.0 | Spinel (`7f08abd9`) |
+|-----------|-------------------|-------------------|---------------|--------------------|
+| Encode (color, q85) | ~0.131s | ~0.088s | ~0.577s | ~0.104s |
+| Decode (baseline) | ~0.112s | ~0.027s | ~0.554s | ~0.078s |
+| Decode (progressive) | ~0.140s | ~0.037s | ~0.617s | ~0.092s |
+
+Inputs were loaded before timing, and encoded output was returned in memory; file I/O and PNG loading are excluded. Runtimes were benchmarked sequentially. JRuby used its default JIT on OpenJDK 21.0.10. Spinel was measured separately with the same inputs and timing protocol, using a portable harness with PNG pixels preloaded; its encoded JPEG and decoded pixels matched CRuby byte-for-byte. Results vary with image content, garbage collection, and JIT warmup.
+
+The encoder and decoder use an integer-scaled AAN (Arai-Agui-Nakajima) DCT with fixed-point arithmetic throughout — no Float operations in the hot path. Color space conversion uses fixed-point integer math, and pixel data is stored as packed integers to avoid per-pixel object allocation. TruffleRuby's Graal JIT compiler can optimize these tight integer loops particularly well once warmed up.
+
+## Example scripts
+
+The `examples/` directory contains ready-to-run scripts. All accept JPEG or PNG input (PNG requires the `chunky_png` gem).
+
+**`png_to_jpeg.rb`** -- Convert a PNG to JPEG.
+
+```
+ruby examples/png_to_jpeg.rb [--grayscale] INPUT.png OUTPUT.jpg [quality]
+```
+
+**`jpeg_to_png.rb`** -- Convert a JPEG to PNG.
+
+```
+ruby examples/jpeg_to_png.rb INPUT.jpg OUTPUT.png
+```
+
+**`kodak.rb`** -- Apply the "scrambled quantization" effect that recreates the gritty look of early digicams like the Casio QV-10. See `CREATIVE.md` for more on this.
 
-| Operation | Time |
-|-----------|------|
-| Encode (color, q85) | ~0.16s |
-| Decode (baseline) | ~0.14s |
-| Decode (progressive) | ~0.18s |
+```
+ruby examples/kodak.rb INPUT.(jpg|png) [OUTPUT.jpg] [quality]
+```
+
+**`lumacrush.rb`** -- Crush luminance while preserving chrominance. Produces a soft, oil-painting quality where detail is blocky but colors remain accurate.
+
+```
+ruby examples/lumacrush.rb INPUT.(jpg|png) [OUTPUT.jpg] [luma_quality] [chroma_quality]
+```
+
+**`chromacrush.rb`** -- The opposite: sharp detail with collapsed, blocky color patches.
+
+```
+ruby examples/chromacrush.rb INPUT.(jpg|png) [OUTPUT.jpg] [luma_quality] [chroma_quality]
+```
 
-The encoder and decoder use an integer-scaled AAN (Arai-Agui-Nakajima) DCT with fixed-point arithmetic throughout — no Float operations in the hot path. Color space conversion uses fixed-point integer math, and pixel data is stored as packed integers to avoid per-pixel object allocation.
+**`loopy.rb`** -- Re-encode a JPEG through multiple passes to see how artifacts accumulate.
+
+```
+ruby examples/loopy.rb INPUT.jpg [quality] [iterations]
+```
 
 ## Some useful `rake` tasks
 
 ```
 bundle install
 rake test        # run the test suite
-rake benchmark   # benchmark encoding and decoding (3 runs each)
+rake benchmark   # basic benchmark of encoding and decoding (5 runs after warmup)
 rake profile     # CPU profile with StackProf (requires the stackprof gem)
 ```
 
+## Full benchmark script
+
+`benchmark/run.rb` is a more thorough benchmark that exercises the encode and decode paths in several ways. It auto-enables YJIT, warms up before measuring, and reports object allocations, throughput (iterations/second via `benchmark-ips`), best-of-N wall-clock times, and a sustained mixed workload across encode (q85, q95 optimized, grayscale) and decode (baseline and progressive).
+
+```
+ruby benchmark/run.rb                  # standard run
+ruby benchmark/run.rb --quick          # single-shot wall-clock + allocations
+ruby benchmark/run.rb --full           # longer run, includes YJIT runtime stats
+ruby benchmark/run.rb --profile        # CPU profile with Vernier (writes JSON to /tmp)
+ruby benchmark/run.rb --profile-alloc  # retained-object profile with Vernier
+```
+
 ## AI Disclosure
 
 **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.*
@@ -236,6 +297,7 @@ rake profile     # CPU profile with StackProf (requires the stackprof gem)
 ## Credits
 
 - [Ufuk Kayserilioglu](https://github.com/paracycle) - Major performance optimizations including integer-scaled AAN DCT, fixed-point color space conversion, and YJIT-targeted improvements.
+- [Keith R. Bennett](https://github.com/keithrbennett) - Coverage testing and adding SimpleCov to the project.
 
 ## License
 

data/lib/pure_jpeg/decoder.rb

@@ -78,9 +78,13 @@ module PureJPEG
 
       # Reusable buffers
       zigzag = Array.new(64, 0)
-      raster = Array.new(64, 0)
       dequant = Array.new(64, 0)
 
+      scan_components = jfif.scan_components.map do |sc|
+        comp, dc_tab, ac_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables)
+        [sc, comp, dc_tab, ac_tab, fetch_quant_table!(jfif, comp), channels[comp.id]]
+      end
+
       mcus_y.times do |mcu_row|
         mcus_x.times do |mcu_col|
           # Handle restart interval
@@ -89,19 +93,14 @@ module PureJPEG
             prev_dc.clear
           end
 
-          jfif.scan_components.each do |sc|
-            comp, dc_tab, ac_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables)
-            qt = fetch_quant_table!(jfif, comp)
-            ch = channels[comp.id]
-
+          scan_components.each do |sc, comp, dc_tab, ac_tab, qt, ch|
             comp.v_sampling.times do |bv|
               comp.h_sampling.times do |bh|
                 # Decode one 8x8 block
                 decode_block(reader, dc_tab, ac_tab, prev_dc, sc.id, zigzag)
 
                 # Inverse pipeline: unzigzag -> dequantize -> IDCT -> level shift
-                Zigzag.unreorder!(zigzag, raster)
-                Quantization.dequantize!(raster, qt, dequant)
+                Quantization.dequantize_zigzag!(zigzag, qt, dequant)
                 DCT.inverse!(dequant)
 
                 # Write block into channel buffer
@@ -191,7 +190,7 @@ module PureJPEG
         end
       end
 
-      # Reconstruct: unzigzag, dequantize, IDCT, write to channel buffers
+      # Reconstruct: unzigzag/dequantize, IDCT, write to channel buffers
       padded_w = mcus_x * mcu_px_w
       padded_h = mcus_y * mcu_px_h
       channels = {}
@@ -201,8 +200,6 @@ module PureJPEG
         channels[c.id] = { data: Array.new(ch_w * ch_h, 0), width: ch_w, height: ch_h }
       end
 
-      zigzag = Array.new(64, 0)
-      raster = Array.new(64, 0)
       dequant = Array.new(64, 0)
 
       jfif.components.each do |c|
@@ -214,10 +211,7 @@ module PureJPEG
         by_count.times do |block_y|
           bx_count.times do |block_x|
             offset = (block_y * bx_count + block_x) * 64
-            64.times { |i| zigzag[i] = coeff_buf[offset + i] }
-
-            Zigzag.unreorder!(zigzag, raster)
-            Quantization.dequantize!(raster, qt, dequant)
+            Quantization.dequantize_zigzag!(coeff_buf, qt, dequant, offset)
             DCT.inverse!(dequant)
             write_block(dequant, ch[:data], ch[:width], block_x * 8, block_y * 8)
           end
@@ -279,6 +273,11 @@ module PureJPEG
       prev_dc = Hash.new(0)
       mcu_count = 0
 
+      scan_components = scan.components.map do |sc|
+        comp, dc_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables, require_ac: false)
+        [sc, comp, dc_tab, coeffs[comp.id], comp_blocks[comp.id][0]]
+      end
+
       mcus_y.times do |mcu_row|
         mcus_x.times do |mcu_col|
           if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
@@ -286,11 +285,7 @@ module PureJPEG
             prev_dc.clear
           end
 
-          scan.components.each do |sc|
-            comp, dc_tab = resolve_scan_references!(sc, comp_info, dc_tables, ac_tables, require_ac: false)
-            coeff_buf = coeffs[comp.id]
-            bx_count = comp_blocks[comp.id][0]
-
+          scan_components.each do |sc, comp, dc_tab, coeff_buf, bx_count|
             comp.v_sampling.times do |bv|
               comp.h_sampling.times do |bh|
                 block_x = mcu_col * comp.h_sampling + bh
@@ -312,7 +307,7 @@ module PureJPEG
     end
 
     def prog_dc_first(reader, dc_tab, prev_dc, coeff_buf, offset, al)
-      cat = dc_tab.decode(reader)
+      cat = dc_tab.decode_symbol(reader)
       diff = reader.receive_extend(cat)
       dc_val = prev_dc + diff
       coeff_buf[offset] = dc_val << al
@@ -328,7 +323,7 @@ module PureJPEG
 
       k = ss
       while k <= se
-        symbol = ac_tab.decode(reader)
+        symbol = ac_tab.decode_symbol(reader)
         run = (symbol >> 4) & 0x0F
         size = symbol & 0x0F
 
@@ -364,7 +359,7 @@ module PureJPEG
 
       k = ss
       while k <= se
-        symbol = ac_tab.decode(reader)
+        symbol = ac_tab.decode_symbol(reader)
         r = (symbol >> 4) & 0x0F
         s = symbol & 0x0F
 
@@ -417,7 +412,7 @@ module PureJPEG
 
     def decode_block(reader, dc_tab, ac_tab, prev_dc, comp_id, out)
       # DC coefficient
-      dc_cat = dc_tab.decode(reader)
+      dc_cat = dc_tab.decode_symbol(reader)
       dc_diff = reader.receive_extend(dc_cat)
       dc_val = prev_dc[comp_id] + dc_diff
       prev_dc[comp_id] = dc_val
@@ -426,7 +421,7 @@ module PureJPEG
       # AC coefficients
       i = 1
       while i < 64
-        symbol = ac_tab.decode(reader)
+        symbol = ac_tab.decode_symbol(reader)
         if symbol == 0x00 # EOB
           while i < 64
             out[i] = 0

data/lib/pure_jpeg/encoder.rb

@@ -42,6 +42,9 @@ module PureJPEG
                    luminance_table: nil, chrominance_table: nil,
                    quantization_modifier: nil, scramble_quantization: false,
                    optimize_huffman: false)
+      validate_quality!(quality, "quality")
+      validate_quality!(chroma_quality, "chroma_quality") if chroma_quality
+
       @source = source
       @quality = quality
       @grayscale = grayscale
@@ -92,6 +95,12 @@ module PureJPEG
       modified
     end
 
+    def validate_quality!(value, name)
+      unless value.is_a?(Integer) && value.between?(1, 100)
+        raise ArgumentError, "#{name} must be an integer between 1 and 100"
+      end
+    end
+
     def validate_qtable!(table, name)
       unless table.respond_to?(:length) && table.respond_to?(:all?)
         raise ArgumentError, "#{name} must be a 64-element array of integers between 1 and 255"
@@ -137,11 +146,9 @@ module PureJPEG
                              lum_dc_bits, lum_dc_values, lum_ac_bits, lum_ac_values)
       else
         chr_qtable = build_chr_qtable
-        y_data, cb_data, cr_data = extract_ycbcr(width, height)
+        y_data, cb_sub, cr_sub = extract_ycbcr420(width, height)
         sub_w = (width + 1) / 2
         sub_h = (height + 1) / 2
-        cb_sub = downsample(cb_data, width, height, sub_w, sub_h)
-        cr_sub = downsample(cr_data, width, height, sub_w, sub_h)
 
         lum_dc_bits, lum_dc_values, lum_ac_bits, lum_ac_values,
           chr_dc_bits, chr_dc_values, chr_ac_bits, chr_ac_values =
@@ -206,13 +213,12 @@ module PureJPEG
       padded_h = (height + 7) & ~7
 
       block = Array.new(64, 0)
-      qbuf  = Array.new(64, 0)
       zbuf  = Array.new(64, 0)
 
       (0...padded_h).step(8) do |by|
         (0...padded_w).step(8) do |bx|
           extract_block_into(y_data, width, height, bx, by, block)
-          yield transform_block(block, qbuf, zbuf, qtable)
+          yield transform_block(block, zbuf, qtable)
         end
       end
     end
@@ -276,28 +282,27 @@ module PureJPEG
       mcu_h = (height + 15) & ~15
 
       block = Array.new(64, 0)
-      qbuf  = Array.new(64, 0)
       zbuf  = Array.new(64, 0)
 
       (0...mcu_h).step(16) do |my|
         (0...mcu_w).step(16) do |mx|
           extract_block_into(y_data, width, height, mx, my, block)
-          yield :y, transform_block(block, qbuf, zbuf, lum_qt)
+          yield :y, transform_block(block, zbuf, lum_qt)
 
           extract_block_into(y_data, width, height, mx + 8, my, block)
-          yield :y, transform_block(block, qbuf, zbuf, lum_qt)
+          yield :y, transform_block(block, zbuf, lum_qt)
 
           extract_block_into(y_data, width, height, mx, my + 8, block)
-          yield :y, transform_block(block, qbuf, zbuf, lum_qt)
+          yield :y, transform_block(block, zbuf, lum_qt)
 
           extract_block_into(y_data, width, height, mx + 8, my + 8, block)
-          yield :y, transform_block(block, qbuf, zbuf, lum_qt)
+          yield :y, transform_block(block, zbuf, lum_qt)
 
           extract_block_into(cb_sub, sub_w, sub_h, mx >> 1, my >> 1, block)
-          yield :cb, transform_block(block, qbuf, zbuf, chr_qt)
+          yield :cb, transform_block(block, zbuf, chr_qt)
 
           extract_block_into(cr_sub, sub_w, sub_h, mx >> 1, my >> 1, block)
-          yield :cr, transform_block(block, qbuf, zbuf, chr_qt)
+          yield :cr, transform_block(block, zbuf, chr_qt)
         end
       end
     end
@@ -322,10 +327,9 @@ module PureJPEG
 
     # --- Shared block pipeline (all buffers pre-allocated) ---
 
-    def transform_block(block, qbuf, zbuf, qtable)
+    def transform_block(block, zbuf, qtable)
       DCT.forward!(block)
-      Quantization.quantize!(block, qtable, qbuf)
-      Zigzag.reorder!(qbuf, zbuf)
+      Quantization.quantize_zigzag!(block, qtable, zbuf)
       zbuf
     end
 
@@ -383,61 +387,65 @@ module PureJPEG
       luminance
     end
 
-    def extract_ycbcr(width, height)
-      size = width * height
-      y_data  = Array.new(size)
-      cb_data = Array.new(size)
-      cr_data = Array.new(size)
+    # Convert RGB in raster order, downsampling chroma after every two rows.
+    # Keeping only two full-resolution chroma rows avoids two image-sized arrays.
+    def extract_ycbcr420(width, height)
+      y_data = Array.new(width * height)
+      sub_w = (width + 1) / 2
+      sub_h = (height + 1) / 2
+      cb_sub = Array.new(sub_w * sub_h)
+      cr_sub = Array.new(sub_w * sub_h)
+      cb_rows = Array.new(width * 2)
+      cr_rows = Array.new(width * 2)
 
       if source.respond_to?(:packed_pixels)
         packed = source.packed_pixels
         r_shift, g_shift, b_shift = packed_shifts
-        i = 0
-        size.times do
-          color = packed[i]
-          r = (color >> r_shift) & 0xFF
-          g = (color >> g_shift) & 0xFF
-          b = (color >> b_shift) & 0xFF
-          y_data[i]  = clamp255((FP_Y_R * r + FP_Y_G * g + FP_Y_B * b + FP_HALF) >> 16)
-          cb_data[i] = clamp255((FP_CB_R * r + FP_CB_G * g + FP_CB_B * b + FP_128 + FP_HALF) >> 16)
-          cr_data[i] = clamp255((FP_CR_R * r + FP_CR_G * g + FP_CR_B * b + FP_128 + FP_HALF) >> 16)
-          i += 1
-        end
-      else
-        height.times do |py|
-          row = py * width
+      end
+
+      height.times do |py|
+        row = py * width
+        chroma_row = (py & 1) * width
+        if packed
+          width.times do |px|
+            color = packed[row + px]
+            r = (color >> r_shift) & 0xFF
+            g = (color >> g_shift) & 0xFF
+            b = (color >> b_shift) & 0xFF
+            y_data[row + px] = clamp255((FP_Y_R * r + FP_Y_G * g + FP_Y_B * b + FP_HALF) >> 16)
+            cb_rows[chroma_row + px] = clamp255((FP_CB_R * r + FP_CB_G * g + FP_CB_B * b + FP_128 + FP_HALF) >> 16)
+            cr_rows[chroma_row + px] = clamp255((FP_CR_R * r + FP_CR_G * g + FP_CR_B * b + FP_128 + FP_HALF) >> 16)
+          end
+        else
           width.times do |px|
             pixel = source[px, py]
             r = pixel.r; g = pixel.g; b = pixel.b
-            i = row + px
-            y_data[i]  = clamp255((FP_Y_R * r + FP_Y_G * g + FP_Y_B * b + FP_HALF) >> 16)
-            cb_data[i] = clamp255((FP_CB_R * r + FP_CB_G * g + FP_CB_B * b + FP_128 + FP_HALF) >> 16)
-            cr_data[i] = clamp255((FP_CR_R * r + FP_CR_G * g + FP_CR_B * b + FP_128 + FP_HALF) >> 16)
+            y_data[row + px] = clamp255((FP_Y_R * r + FP_Y_G * g + FP_Y_B * b + FP_HALF) >> 16)
+            cb_rows[chroma_row + px] = clamp255((FP_CB_R * r + FP_CB_G * g + FP_CB_B * b + FP_128 + FP_HALF) >> 16)
+            cr_rows[chroma_row + px] = clamp255((FP_CR_R * r + FP_CR_G * g + FP_CR_B * b + FP_128 + FP_HALF) >> 16)
           end
         end
+
+        if py.odd? || py == height - 1
+          # For odd image heights, use row zero twice at the bottom edge.
+          downsample_chroma_rows(cb_rows, cr_rows, width, chroma_row,
+                                 cb_sub, cr_sub, sub_w, (py >> 1) * sub_w)
+        end
       end
 
-      [y_data, cb_data, cr_data]
+      [y_data, cb_sub, cr_sub]
     end
 
-    def downsample(data, src_w, src_h, dst_w, dst_h)
-      out = Array.new(dst_w * dst_h)
-      max_x = src_w - 1
-      max_y = src_h - 1
-      dst_h.times do |dy|
-        sy = dy << 1
-        y1 = sy < max_y ? sy + 1 : max_y
-        row0 = sy * src_w
-        row1 = y1 * src_w
-        dst_row = dy * dst_w
-        dst_w.times do |dx|
-          sx = dx << 1
-          x1 = sx < max_x ? sx + 1 : max_x
-          out[dst_row + dx] = ((data[row0 + sx] + data[row0 + x1] +
-                                data[row1 + sx] + data[row1 + x1]) >> 2)
-        end
+    def downsample_chroma_rows(cb_rows, cr_rows, width, row1, cb_sub, cr_sub, sub_w, dst_row)
+      max_x = width - 1
+      sub_w.times do |dx|
+        sx = dx << 1
+        x1 = sx < max_x ? sx + 1 : max_x
+        cb_sub[dst_row + dx] = (cb_rows[sx] + cb_rows[x1] +
+                                cb_rows[row1 + sx] + cb_rows[row1 + x1]) >> 2
+        cr_sub[dst_row + dx] = (cr_rows[sx] + cr_rows[x1] +
+                                cr_rows[row1 + sx] + cr_rows[row1 + x1]) >> 2
       end
-      out
     end
 
     # Extract an 8x8 block into a pre-allocated array, level-shifted by -128.

data/lib/pure_jpeg/huffman/decoder.rb

@@ -25,13 +25,15 @@ module PureJPEG
       end
 
       # Decode one Huffman symbol from the bit reader.
-      def decode(reader)
+      def decode_symbol(reader)
         code = 0
-        1.upto(16) do |len|
+        len = 1
+        while len <= 16
           code = (code << 1) | reader.read_bit
           if @max_code[len] >= 0 && code <= @max_code[len]
             return @values[@val_ptr[len] + code - @min_code[len]]
           end
+          len += 1
         end
         raise PureJPEG::DecodeError, "Invalid Huffman code"
       end

data/lib/pure_jpeg/huffman/encoder.rb

@@ -6,14 +6,7 @@ module PureJPEG
       # Return the Huffman category (bit length) for a value.
       # Avoids Array allocation compared to the combined category_and_bits.
       def self.category(value)
-        return 0 if value == 0
-        v = value.abs
-        cat = 0
-        while v > 0
-          cat += 1
-          v >>= 1
-        end
-        cat
+        value.abs.bit_length
       end
 
       # Return the extra bits to encode for a value with the given category.
@@ -50,6 +43,7 @@ module PureJPEG
         end
 
         yield 0x00, 0 if last_nonzero < 63
+        nil
       end
 
       def self.each_ac_symbol(zigzag)
@@ -85,12 +79,12 @@ module PureJPEG
       end
 
       def encode_ac(zigzag, writer)
-        self.class.each_ac_item(zigzag) do |symbol, value|
+        PureJPEG::Huffman::Encoder.each_ac_item(zigzag) do |symbol, value|
           code, length = @ac_table[symbol]
           writer.write_bits(code, length)
           next if symbol == 0x00 || symbol == 0xF0
 
-          cat = self.class.category(value)
+          cat = symbol & 0x0F
           writer.write_bits(self.class.value_bits(value, cat), cat)
         end
       end

data/lib/pure_jpeg/image.rb

@@ -38,6 +38,7 @@ module PureJPEG
     # @param y [Integer] row (0-based)
     # @return [Source::Pixel] pixel with +.r+, +.g+, +.b+ in 0-255
     def [](x, y)
+      validate_coordinates!(x, y)
       color = @packed_pixels[y * @width + x]
       Source::Pixel.new((color >> 16) & 0xFF, (color >> 8) & 0xFF, color & 0xFF)
     end
@@ -49,6 +50,7 @@ module PureJPEG
     # @param pixel [Source::Pixel] replacement pixel
     # @return [Source::Pixel]
     def []=(x, y, pixel)
+      validate_coordinates!(x, y)
       @packed_pixels[y * @width + x] = (pixel.r << 16) | (pixel.g << 8) | pixel.b
       pixel
     end
@@ -85,5 +87,13 @@ module PureJPEG
         end
       end
     end
+
+    private
+
+    def validate_coordinates!(x, y)
+      unless x.is_a?(Integer) && y.is_a?(Integer) && x >= 0 && y >= 0 && x < @width && y < @height
+        raise IndexError, "Pixel coordinate out of bounds: #{x.inspect}, #{y.inspect}"
+      end
+    end
   end
 end

data/lib/pure_jpeg/jfif_reader.rb

@@ -101,10 +101,9 @@ module PureJPEG
     ICC_PROFILE_SIG = "ICC_PROFILE\0".b
 
     def parse_app2
-      length = read_u16
-      end_pos = @pos + length - 2
+      end_pos = read_segment_end
 
-      if length >= 16 && @data[@pos, 12] == ICC_PROFILE_SIG
+      if (end_pos - @pos) >= 14 && @data[@pos, 12] == ICC_PROFILE_SIG
         @pos += 12
         seq_no = read_byte
         _total = read_byte
@@ -121,18 +120,18 @@ module PureJPEG
     end
 
     def skip_segment
-      length = read_u16
-      @pos += length - 2
+      @pos = read_segment_end
     end
 
     def parse_dqt
-      length = read_u16
-      end_pos = @pos + length - 2
+      end_pos = read_segment_end
 
       while @pos < end_pos
         info = read_byte
         precision = (info >> 4) & 0x0F  # 0 = 8-bit, 1 = 16-bit
         table_id = info & 0x0F
+        bytes_per_value = precision == 0 ? 1 : 2
+        ensure_remaining_in_segment!(end_pos, 64 * bytes_per_value, "DQT")
 
         zigzag_table = Array.new(64)
         64.times do |i|
@@ -146,16 +145,17 @@ module PureJPEG
     end
 
     def parse_dht
-      length = read_u16
-      end_pos = @pos + length - 2
+      end_pos = read_segment_end
 
       while @pos < end_pos
+        ensure_remaining_in_segment!(end_pos, 17, "DHT")
         info = read_byte
         table_class = (info >> 4) & 0x0F  # 0 = DC, 1 = AC
         table_id = info & 0x0F
 
         bits = Array.new(16) { read_byte }
         total = bits.sum
+        ensure_remaining_in_segment!(end_pos, total, "DHT")
         values = Array.new(total) { read_byte }
 
         @huffman_tables[[table_class, table_id]] = { bits: bits, values: values }
@@ -163,11 +163,13 @@ module PureJPEG
     end
 
     def parse_sof0
-      read_u16 # length
+      end_pos = read_segment_end
+      ensure_remaining_in_segment!(end_pos, 6, "SOF")
       read_byte # precision (always 8 for baseline)
       @height = read_u16
       @width = read_u16
       num_components = read_byte
+      ensure_remaining_in_segment!(end_pos, num_components * 3, "SOF")
 
       @components = Array.new(num_components) do
         id = read_byte
@@ -177,11 +179,14 @@ module PureJPEG
         qt_id = read_byte
         Component.new(id, h, v, qt_id)
       end
+      @pos = end_pos
     end
 
     def parse_sos
-      read_u16 # length
+      end_pos = read_segment_end
+      ensure_remaining_in_segment!(end_pos, 1, "SOS")
       num_components = read_byte
+      ensure_remaining_in_segment!(end_pos, num_components * 2 + 3, "SOS")
 
       components = Array.new(num_components) do
         id = read_byte
@@ -196,12 +201,33 @@ module PureJPEG
       ahl = read_byte # successive approximation
       ah = (ahl >> 4) & 0x0F
       al = ahl & 0x0F
+      @pos = end_pos
       Scan.new(components, ss, se, ah, al, nil)
     end
 
     def parse_dri
-      read_u16 # length
+      end_pos = read_segment_end
+      ensure_remaining_in_segment!(end_pos, 2, "DRI")
       @restart_interval = read_u16
+      @pos = end_pos
+    end
+
+    def read_segment_end
+      length = read_u16
+      raise PureJPEG::DecodeError, "Invalid JPEG segment length: #{length}" if length < 2
+
+      end_pos = @pos + length - 2
+      if end_pos > @data.bytesize
+        raise PureJPEG::DecodeError, "JPEG segment length exceeds available data"
+      end
+
+      end_pos
+    end
+
+    def ensure_remaining_in_segment!(end_pos, byte_count, segment_name)
+      return if @pos + byte_count <= end_pos
+
+      raise PureJPEG::DecodeError, "Truncated #{segment_name} segment"
     end
 
     # Extract entropy-coded scan data (everything from current position to EOI marker).

data/lib/pure_jpeg/quantization.rb

@@ -58,5 +58,33 @@ module PureJPEG
       64.times { |i| out[i] = block[i] * table[i] }
       out
     end
+
+    # Quantize raster-order coefficients directly into zigzag order.
+    def self.quantize_zigzag!(block, table, out)
+      order = Zigzag::ORDER
+      i = 0
+      while i < 64
+        j = order[i]
+        v = block[j]; t = table[j]
+        out[i] = if v >= 0
+                   (v + (t >> 1)) / t
+                 else
+                   -((-v + (t >> 1)) / t)
+                 end
+        i += 1
+      end
+      out
+    end
+
+    # Dequantize zigzag coefficients directly into raster order. The offset
+    # allows progressive decoding to read from its full coefficient buffer.
+    def self.dequantize_zigzag!(block, table, out, offset = 0)
+      order = Zigzag::ORDER
+      64.times do |i|
+        j = order[i]
+        out[j] = block[offset + i] * table[j]
+      end
+      out
+    end
   end
 end

data/lib/pure_jpeg/source/chunky_png_source.rb

@@ -18,10 +18,16 @@ module PureJPEG
       attr_reader :height
 
       # @param image [ChunkyPNG::Image] the source PNG image
-      def initialize(image)
+      # @param background [Array<Integer>, nil] optional [r, g, b] background
+      #   color to composite transparent pixels against before encoding
+      def initialize(image, background: nil)
         @width = image.width
         @height = image.height
-        @packed_pixels = image.pixels
+        @packed_pixels = if background.nil?
+                           image.pixels
+                         else
+                           composite_pixels(image.pixels, background)
+                         end
       end
 
       # @return [Array<Integer>] flat row-major array of packed RGBA integers
@@ -40,6 +46,37 @@ module PureJPEG
           (color >> 8) & 0xFF
         )
       end
+
+      private
+
+      def composite_pixels(pixels, background)
+        bg_r, bg_g, bg_b = validate_background!(background)
+
+        pixels.map do |color|
+          alpha = color & 0xFF
+          next color if alpha == 255
+
+          src_r = (color >> 24) & 0xFF
+          src_g = (color >> 16) & 0xFF
+          src_b = (color >> 8) & 0xFF
+          inv_alpha = 255 - alpha
+
+          r = ((src_r * alpha) + (bg_r * inv_alpha) + 127) / 255
+          g = ((src_g * alpha) + (bg_g * inv_alpha) + 127) / 255
+          b = ((src_b * alpha) + (bg_b * inv_alpha) + 127) / 255
+
+          (r << 24) | (g << 16) | (b << 8) | 255
+        end
+      end
+
+      def validate_background!(background)
+        unless background.respond_to?(:length) && background.length == 3 &&
+               background.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }
+          raise ArgumentError, "background must be an [r, g, b] array of integers between 0 and 255"
+        end
+
+        background
+      end
     end
   end
 end

data/lib/pure_jpeg/source/raw_source.rb

@@ -27,15 +27,16 @@ module PureJPEG
       def initialize(width, height, &block)
         @width = width
         @height = height
-        @pixels = Array.new(width * height) { Pixel.new(0, 0, 0) }
-
         if block
+          @pixels = Array.new(width * height)
           height.times do |y|
             width.times do |x|
               r, g, b = block.call(x, y)
               @pixels[y * width + x] = Pixel.new(r, g, b)
             end
           end
+        else
+          @pixels = Array.new(width * height) { Pixel.new(0, 0, 0) }
         end
       end
 

data/lib/pure_jpeg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PureJPEG
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/pure_jpeg.rb

@@ -50,10 +50,12 @@ module PureJPEG
   # and passes it to {.encode}.
   #
   # @param image [ChunkyPNG::Image] the source image
+  # @param background [Array<Integer>, nil] optional [r, g, b] background
+  #   color to composite transparent pixels against before encoding
   # @param opts [Hash] encoding options passed to {Encoder#initialize}
   # @return [Encoder]
-  def self.from_chunky_png(image, **opts)
-    source = Source::ChunkyPNGSource.new(image)
+  def self.from_chunky_png(image, background: nil, **opts)
+    source = Source::ChunkyPNGSource.new(image, background: background)
     Encoder.new(source, **opts)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pure_jpeg
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Peter Cooper
@@ -86,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Pure Ruby JPEG encoder and decoder
 test_files: []