pure_jpeg 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e09848a734582d7635ff6a8c3d85b166da4f2c5b496d5c4f4e30105af4834e33
-  data.tar.gz: 052b8e0a21d58eb9aa9e169e06b7cfbde44f3610775da6fed86e05875dceaea3
+  metadata.gz: 6eacb8a616f95a52625f6f5acb3c8c137306c5dcf3636e93e2e715287b429655
+  data.tar.gz: dade5c2d3b9603bb7089635977ea2e38827da1a3912c820152367f3ca643c5f9
 SHA512:
-  metadata.gz: 750ea3d65bf2ae6c272998b2ef7b814954eb1b576f6df83036d931543f30b99481281e8a12ef63fc388fdc60db0c54815fc8219b66782415844b3ed8721a5975
-  data.tar.gz: 16475c5174b009a7a45eec5ee288799ea7965e4e10ed02ab20d55b15de5ebbdf92e9c0196d58053b6539dfea4601d7e22016c636ee471d2e73300feb86d97f07
+  metadata.gz: ccf7a06b88c08f14ca70d944ddcc753795217e3bfbca00874484ee6f3c2a360d8cede768c4469f5b92d2789bf7bcc71d61b22f67d76fb98774af28f88132c248
+  data.tar.gz: d868a5d4f7db3b20a504bc09f9908169fd35c269b511e619e083957fd6b4bf90a3cf22985a5e6d81289a02306ba75677b94b8ff9f6d741acc7b2047979d0f2c6

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.0
+
+New features:
+
+- Progressive JPEG decoding (SOF2) with spectral selection and successive approximation
+- `Image#each_rgb` for iterating pixels without per-pixel struct allocation
+- `PureJPEG::DecodeError` exception class for all decoding errors
+- Validation of custom quantization tables (length and value range)
+
+Performance:
+
+- Packed integer pixel storage in `Image` eliminates per-pixel object allocation on decode (~6x faster decode)
+- Fast path for encoder pixel extraction from packed sources (`ChunkyPNGSource`, `Image`)
+- `BitReader#read_bits` fast path when buffer already has enough bits
+- `BitWriter` builds a `String` directly instead of `Array` + `pack`
+- `Huffman.build_table` returns an `Array` for O(1) lookup instead of `Hash`
+- Faster scan data extraction using `String#index`
+
+Fixes:
+
+- JPEG data detection uses SOI marker check instead of null-byte heuristic
+- `RawSource` pixels default to black instead of `nil`
+- `BitReader` bounds check for truncated 0xFF sequences
+- `JFIFReader` bounds check when reading past end of data
+- Fixed dead tautological check in AC encoding EOB logic
+
 ## 0.1.0
 
 Initial release.

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Peter Cooper
+Copyright (c) 2026 Peter Cooper
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,15 @@
-# PureJPEG
+<p align="center">
+  <img src="purejpeg.jpg" width="480" alt="PureJPEG">
+</p>
 
-Pure Ruby JPEG encoder and decoder. Implements baseline JPEG (DCT, Huffman, 4:2:0 chroma subsampling) and 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..)
+# PureJPEG - Pure Ruby JPEG encoder and decoder library
+
+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.
+
+> [!NOTE]
+> Rubyists might find the [AI Disclosure](#ai-disclosure) section below of interest.
 
 ## Installation
 
@@ -14,7 +23,7 @@ gem "pure_jpeg"
 gem install pure_jpeg
 ```
 
-There are no runtime dependencies. [ChunkyPNG](https://github.com/wvanbergen/chunky_png) is optional and for 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 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`. 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 ;-)
 
 `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.
 
@@ -76,7 +85,35 @@ PureJPEG.encode(source,
 
 See [CREATIVE.md](CREATIVE.md) for detailed examples of the creative encoding options.
 
-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.
+Here's a quick example of sort of the "old digital camera" effect I was looking for though:
+
+<table>
+<tr>
+<td align="center"><strong>Normal</strong></td>
+<td align="center"><strong>Scrambled quantization</strong></td>
+</tr>
+<tr>
+<td><img src="examples/peppers.jpg" width="360"></td>
+<td><img src="examples/peppers-funky.jpg" width="360"></td>
+</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:
+
+<table>
+<tr>
+<td align="center"><strong>PNG with transparency</strong></td>
+<td align="center"><strong>Converted to JPEG</strong></td>
+</tr>
+<tr>
+<td><img src="examples/dice.png" width="360"></td>
+<td><img src="examples/dice.jpg" width="360"></td>
+</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!
+
+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.
 
 ## Decoding (reading JPEGs!)
 
@@ -137,24 +174,24 @@ Encoding:
 - Standard Huffman tables (Annex K)
 
 Decoding:
-- Baseline DCT (SOF0)
+- Baseline DCT (SOF0) and Progressive DCT (SOF2)
 - 8-bit precision
 - 1-component (grayscale) and 3-component (YCbCr) images
 - Any chroma subsampling factor (4:4:4, 4:2:2, 4:2:0, etc.)
 - Restart markers (DRI/RST)
 
-Not supported: progressive JPEG (SOF2), arithmetic coding, 12-bit precision, multi-scan, EXIF/ICC profile preservation. Largely because I don't need these, but they are all do-able, especially with how loosely coupled this library is internally. Raise an issue if you really care about them!
+Not supported: arithmetic coding, 12-bit precision, EXIF/ICC profile preservation, adding a default background for transparent sources (see what happens above!). Largely because I don't need these, but they are all do-able, especially with how loosely coupled this library is internally. Raise an issue if you really care about them!
 
 ## Performance
 
-On a 1024x1024 image (Ruby 3.4 on my M1 Max):
+On a 1024x1024 image (Ruby 4.0.1 on my M1 Max):
 
 | Operation | Time |
 |-----------|------|
-| Encode (color, q85) | ~2.8s |
-| Decode (color) | ~12s |
+| Encode (color, q85) | ~1.7s |
+| Decode (color) | ~1.8s |
 
-The encoder uses a separable DCT with a precomputed cosine matrix and reuses all per-block buffers to minimize GC pressure (more on the optimizations below).
+Both the encoder and decoder use a separable DCT with a precomputed cosine matrix and reuse all per-block buffers to minimize GC pressure. Pixel data is stored as packed integers internally to avoid per-pixel object allocation.
 
 ## Some useful `rake` tasks
 
@@ -167,13 +204,19 @@ rake profile     # CPU profile with StackProf (requires the stackprof gem)
 
 ## AI Disclosure
 
-Claude Code did the majority of the work. However, it did require a lot of guidance as it was quite naive in its approach at first with its JPEG outputs looking very akin to those of my Kodak digital camera from 2001! It turns out it got something wrong which, amusingly, it seems devices of those era also got wrong (specifically not using the zigzag approach during quanitization).
+**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 :-)
+
+**I have read all of the code produced.** The algorithms are above my paygrade, but I'm OK with what has been produced, and I manually fixed a variety of stylistic things along the way. For example, CC seems to like wrapping entire functions in `if` statements rather than bailing on the opposite condition.
+
+**CC needed a lot of guidance.** Its initial JPEG algorithm was somewhat naive and output odd looking JPEGs akin to those of my Kodak digital camera from 2001. After some back and forth and image comparisons, we figured out it was doing the quantization entirely wrong (specifically not using the zigzag approach during quanitization but just going in raster order). I *like* this aesthetic, but fixed it up so that it works as a generally usable JPEG library, while adding ways to customize things so you can recreate the effect, if preferred (see `CREATIVE.md` for more on that).
+
+**CC is lazy.** The initial implementation was VERY SLOW. It took 15 seconds to turn a 1024x1024 PNG into a JPEG, so we went down the profiling rabbit hole and found many optimizations to make it ~6x faster. CC is poor at considering the role of Ruby's GC when implementing low level algorithms and needs some prodding to make the correct optimizations. CC is also lazy to the point of recommending that you just use another language (e.g. Go or Rust) rather than do a pure Ruby version of something - despite it being possible with some extra work.
 
-The initial implementation was also VERY SLOW. It took about 15 seconds just to turn a 1024x1024 PNG into a JPEG, so some profiling was necessary which ended up finding a lot of possible optimizations to make it about 6x faster.
+**CC's testing and cleanliness leaves a bit to be desired.** The CC-created tests were superficial, so I worked on getting them beefed up to tackle a variety of edge cases. They could still get better. It also didn't do RDoc comments, use Minitest, and a variety of other things I coerced it into working on. A good `CLAUDE.md` file could probably avoid many of these problems. I worked without one.
 
-The tests were also a bit superficial, so I worked on getting them beefed up to tackle a variety of edge cases, although they could still be better. It also didn't do RDoc comments, use Minitest, and a variety of other things I had to coerce it into finishing.
+**The overall experience was good.** I enjoyed this project, but CC clearly requires an experienced developer to keep it on the rails and to not end up with a bunch of buggy half-working crap. Getting to the basic 'turn a PNG into a JPEG' took only twenty minutes, but the rest of making it actually widely useful took several hours more.
 
-I have read all of the code produced. A lot of the internals are above my paygrade but I'm generally OK with what has been produced and fixed a variety of stylistic things along the way.
+**The final 10% still takes 90% of the time.** As mentioned above, the first run was quick, but getting things right has taken much longer. v0.1->0.2 has taken longer than 0.1 did! But we now have progressive JPEG support, even more optimizations, better tests, etc. etc.
 
 ## License
 

data/lib/pure_jpeg/bit_reader.rb

@@ -18,6 +18,12 @@ module PureJPEG
 
     def read_bits(n)
       return 0 if n == 0
+      # Fast path: enough bits already in the buffer
+      if @bits_in_buffer >= n
+        @bits_in_buffer -= n
+        return (@buffer >> @bits_in_buffer) & ((1 << n) - 1)
+      end
+      # Slow path: need to refill
       value = 0
       n.times { value = (value << 1) | read_bit }
       value
@@ -43,10 +49,11 @@ module PureJPEG
     private
 
     def fill_buffer
-      raise "Unexpected end of scan data" if @pos >= @length
+      raise PureJPEG::DecodeError, "Unexpected end of scan data" if @pos >= @length
       byte = @data.getbyte(@pos)
       @pos += 1
       if byte == 0xFF
+        raise PureJPEG::DecodeError, "Unexpected end of scan data" if @pos >= @length
         next_byte = @data.getbyte(@pos)
         @pos += 1
         # 0xFF 0x00 is a stuffed 0xFF byte

data/lib/pure_jpeg/bit_writer.rb

@@ -3,7 +3,7 @@
 module PureJPEG
   class BitWriter
     def initialize
-      @data = []
+      @data = String.new(capacity: 4096, encoding: Encoding::BINARY)
       @buffer = 0
       @bits_in_buffer = 0
     end
@@ -17,8 +17,8 @@ module PureJPEG
       while @bits_in_buffer >= 8
         @bits_in_buffer -= 8
         byte = (@buffer >> @bits_in_buffer) & 0xFF
-        @data << byte
-        @data << 0x00 if byte == 0xFF  # byte stuffing
+        @data << byte.chr
+        @data << "\x00".b if byte == 0xFF  # byte stuffing
       end
 
       @buffer &= (1 << @bits_in_buffer) - 1
@@ -32,7 +32,7 @@ module PureJPEG
     end
 
     def bytes
-      @data.pack("C*")
+      @data
     end
   end
 end

data/lib/pure_jpeg/decoder.rb

@@ -13,7 +13,7 @@ module PureJPEG
     # @param path_or_data [String] a file path or raw JPEG bytes
     # @return [Image] decoded image with pixel access
     def self.decode(path_or_data)
-      data = if path_or_data.is_a?(String) && !path_or_data.include?("\x00") && File.exist?(path_or_data)
+      data = if path_or_data.is_a?(String) && !path_or_data.start_with?("\xFF\xD8".b) && File.exist?(path_or_data)
                File.binread(path_or_data)
              else
                path_or_data.b
@@ -27,6 +27,8 @@ module PureJPEG
 
     def decode
       jfif = JFIFReader.new(@data)
+      return decode_progressive(jfif) if jfif.progressive
+
       width = jfif.width
       height = jfif.height
 
@@ -127,6 +129,290 @@ module PureJPEG
 
     private
 
+    # --- Progressive JPEG decoding ---
+
+    def decode_progressive(jfif)
+      width = jfif.width
+      height = jfif.height
+
+      comp_info = {}
+      jfif.components.each { |c| comp_info[c.id] = c }
+
+      max_h = jfif.components.map(&:h_sampling).max
+      max_v = jfif.components.map(&:v_sampling).max
+
+      mcu_px_w = max_h * 8
+      mcu_px_h = max_v * 8
+      mcus_x = (width + mcu_px_w - 1) / mcu_px_w
+      mcus_y = (height + mcu_px_h - 1) / mcu_px_h
+
+      # Coefficient buffers per component (zigzag order, pre-dequantization)
+      coeffs = {}
+      comp_blocks = {}
+      jfif.components.each do |c|
+        bx = mcus_x * c.h_sampling
+        by = mcus_y * c.v_sampling
+        coeffs[c.id] = Array.new(bx * by * 64, 0)
+        comp_blocks[c.id] = [bx, by]
+      end
+
+      restart_interval = jfif.restart_interval
+
+      jfif.scans.each do |scan|
+        # Build Huffman tables from this scan's snapshot (tables change between scans)
+        dc_tables = {}
+        ac_tables = {}
+        scan.huffman_tables.each do |(table_class, table_id), info|
+          table = Huffman::DecodeTable.new(info[:bits], info[:values])
+          if table_class == 0
+            dc_tables[table_id] = table
+          else
+            ac_tables[table_id] = table
+          end
+        end
+
+        reader = BitReader.new(scan.data)
+        ss = scan.spectral_start
+        se = scan.spectral_end
+        ah = scan.successive_high
+        al = scan.successive_low
+
+        if scan.components.length == 1
+          prog_scan_non_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
+                                    coeffs, comp_blocks, restart_interval, ss, se, ah, al)
+        else
+          prog_scan_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
+                                coeffs, comp_blocks, mcus_x, mcus_y, restart_interval, ss, se, ah, al)
+        end
+      end
+
+      # Reconstruct: unzigzag, dequantize, IDCT, write to channel buffers
+      padded_w = mcus_x * mcu_px_w
+      padded_h = mcus_y * mcu_px_h
+      channels = {}
+      jfif.components.each do |c|
+        ch_w = (padded_w * c.h_sampling) / max_h
+        ch_h = (padded_h * c.v_sampling) / max_v
+        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.0)
+      dequant = Array.new(64, 0.0)
+      temp = Array.new(64, 0.0)
+      spatial = Array.new(64, 0.0)
+
+      jfif.components.each do |c|
+        qt = jfif.quant_tables[c.qt_id]
+        ch = channels[c.id]
+        coeff_buf = coeffs[c.id]
+        bx_count, by_count = comp_blocks[c.id]
+
+        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)
+            DCT.inverse!(dequant, temp, spatial)
+            write_block(spatial, ch[:data], ch[:width], block_x * 8, block_y * 8)
+          end
+        end
+      end
+
+      num_components = jfif.components.length
+      if num_components == 1
+        assemble_grayscale(width, height, channels, jfif.components[0])
+      else
+        assemble_color(width, height, channels, jfif.components, max_h, max_v)
+      end
+    end
+
+    def prog_scan_non_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
+                                  coeffs, comp_blocks, restart_interval, ss, se, ah, al)
+      sc = scan.components[0]
+      comp = comp_info[sc.id]
+      dc_tab = dc_tables[sc.dc_table_id]
+      ac_tab = ac_tables[sc.ac_table_id]
+      coeff_buf = coeffs[comp.id]
+      bx_count, by_count = comp_blocks[comp.id]
+
+      prev_dc = 0
+      eobrun = 0
+      mcu_count = 0
+
+      by_count.times do |block_y|
+        bx_count.times do |block_x|
+          if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
+            reader.reset
+            prev_dc = 0
+            eobrun = 0
+          end
+
+          offset = (block_y * bx_count + block_x) * 64
+
+          if ss == 0
+            if ah == 0
+              prev_dc = prog_dc_first(reader, dc_tab, prev_dc, coeff_buf, offset, al)
+            else
+              prog_dc_refine(reader, coeff_buf, offset, al)
+            end
+          else
+            if ah == 0
+              eobrun = prog_ac_first(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
+            else
+              eobrun = prog_ac_refine(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
+            end
+          end
+
+          mcu_count += 1
+        end
+      end
+    end
+
+    def prog_scan_interleaved(reader, scan, comp_info, dc_tables, ac_tables,
+                              coeffs, comp_blocks, mcus_x, mcus_y, restart_interval, ss, se, ah, al)
+      prev_dc = Hash.new(0)
+      mcu_count = 0
+
+      mcus_y.times do |mcu_row|
+        mcus_x.times do |mcu_col|
+          if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
+            reader.reset
+            prev_dc.clear
+          end
+
+          scan.components.each do |sc|
+            comp = comp_info[sc.id]
+            dc_tab = dc_tables[sc.dc_table_id]
+            coeff_buf = coeffs[comp.id]
+            bx_count = comp_blocks[comp.id][0]
+
+            comp.v_sampling.times do |bv|
+              comp.h_sampling.times do |bh|
+                block_x = mcu_col * comp.h_sampling + bh
+                block_y = mcu_row * comp.v_sampling + bv
+                offset = (block_y * bx_count + block_x) * 64
+
+                if ah == 0
+                  prev_dc[sc.id] = prog_dc_first(reader, dc_tab, prev_dc[sc.id], coeff_buf, offset, al)
+                else
+                  prog_dc_refine(reader, coeff_buf, offset, al)
+                end
+              end
+            end
+          end
+
+          mcu_count += 1
+        end
+      end
+    end
+
+    def prog_dc_first(reader, dc_tab, prev_dc, coeff_buf, offset, al)
+      cat = dc_tab.decode(reader)
+      diff = reader.receive_extend(cat)
+      dc_val = prev_dc + diff
+      coeff_buf[offset] = dc_val << al
+      dc_val
+    end
+
+    def prog_dc_refine(reader, coeff_buf, offset, al)
+      coeff_buf[offset] |= (reader.read_bit << al)
+    end
+
+    def prog_ac_first(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
+      return eobrun - 1 if eobrun > 0
+
+      k = ss
+      while k <= se
+        symbol = ac_tab.decode(reader)
+        run = (symbol >> 4) & 0x0F
+        size = symbol & 0x0F
+
+        if size == 0
+          if run == 15
+            k += 16
+          else
+            # EOBn
+            eobrun = (1 << run)
+            eobrun += reader.read_bits(run) if run > 0
+            return eobrun - 1
+          end
+        else
+          k += run
+          coeff_buf[offset + k] = reader.receive_extend(size) << al
+          k += 1
+        end
+      end
+
+      0
+    end
+
+    def prog_ac_refine(reader, ac_tab, coeff_buf, offset, ss, se, al, eobrun)
+      p1 = 1 << al
+      m1 = -(1 << al)
+
+      if eobrun > 0
+        ss.upto(se) do |k|
+          prog_refine_bit(reader, coeff_buf, offset + k, p1, m1) if coeff_buf[offset + k] != 0
+        end
+        return eobrun - 1
+      end
+
+      k = ss
+      while k <= se
+        symbol = ac_tab.decode(reader)
+        r = (symbol >> 4) & 0x0F
+        s = symbol & 0x0F
+
+        # Read the new coefficient value before processing the run
+        # (the value bits come before refinement bits in the bitstream)
+        new_value = nil
+        if s != 0
+          new_value = reader.receive_extend(s) << al
+        elsif r != 15
+          # EOBn: refine remaining nonzero coefficients in this block
+          eobrun = (1 << r)
+          eobrun += reader.read_bits(r) if r > 0
+          while k <= se
+            prog_refine_bit(reader, coeff_buf, offset + k, p1, m1) if coeff_buf[offset + k] != 0
+            k += 1
+          end
+          return eobrun - 1
+        end
+
+        # Advance through the band: refine nonzero coefficients, count zeros for run.
+        # Break when we've skipped `r` zeros and found the target zero position.
+        while k <= se
+          if coeff_buf[offset + k] != 0
+            prog_refine_bit(reader, coeff_buf, offset + k, p1, m1)
+          elsif r == 0
+            break
+          else
+            r -= 1
+          end
+          k += 1
+        end
+
+        # Place new coefficient at the target zero position
+        if new_value && k <= se
+          coeff_buf[offset + k] = new_value
+        end
+        k += 1
+      end
+
+      0
+    end
+
+    def prog_refine_bit(reader, coeff_buf, idx, p1, m1)
+      if reader.read_bit == 1
+        coeff_buf[idx] += coeff_buf[idx] > 0 ? p1 : m1
+      end
+    end
+
+    # --- Baseline decoding helpers ---
+
     def decode_block(reader, dc_tab, ac_tab, prev_dc, comp_id, out)
       # DC coefficient
       dc_cat = dc_tab.decode(reader)
@@ -185,7 +471,7 @@ module PureJPEG
         dst_row = y * width
         width.times do |x|
           v = ch[:data][src_row + x]
-          pixels[dst_row + x] = Source::Pixel.new(v, v, v)
+          pixels[dst_row + x] = (v << 16) | (v << 8) | v
         end
       end
       Image.new(width, height, pixels)
@@ -228,7 +514,7 @@ module PureJPEG
           g = g < 0 ? 0 : (g > 255 ? 255 : g)
           b = b < 0 ? 0 : (b > 255 ? 255 : b)
 
-          pixels[dst_row + px] = Source::Pixel.new(r, g, b)
+          pixels[dst_row + px] = (r << 16) | (g << 8) | b
         end
       end
 

data/lib/pure_jpeg/encoder.rb

@@ -41,6 +41,8 @@ module PureJPEG
       @quality = quality
       @grayscale = grayscale
       @chroma_quality = chroma_quality || quality
+      validate_qtable!(luminance_table, "luminance_table") if luminance_table
+      validate_qtable!(chrominance_table, "chrominance_table") if chrominance_table
       @luminance_table = luminance_table
       @chrominance_table = chrominance_table
       @quantization_modifier = quantization_modifier
@@ -78,6 +80,13 @@ module PureJPEG
       table
     end
 
+    def validate_qtable!(table, name)
+      raise ArgumentError, "#{name} must have exactly 64 elements (got #{table.length})" unless table.length == 64
+      unless table.all? { |v| v.is_a?(Integer) && v >= 1 && v <= 255 }
+        raise ArgumentError, "#{name} elements must be integers between 1 and 255"
+      end
+    end
+
     def encode(io)
       width = source.width
       height = source.height
@@ -223,13 +232,37 @@ module PureJPEG
 
     # --- Pixel extraction ---
 
+    # Determine RGB bit shifts for a packed_pixels source.
+    # ChunkyPNG uses (r<<24 | g<<16 | b<<8 | a), Image uses (r<<16 | g<<8 | b).
+    def packed_shifts
+      if source.is_a?(Image)
+        [16, 8, 0]
+      else
+        [24, 16, 8]
+      end
+    end
+
     def extract_luminance(width, height)
       luminance = Array.new(width * height)
-      height.times do |y|
-        row = y * width
-        width.times do |x|
-          pixel = source[x, y]
-          luminance[row + x] = (0.299 * pixel.r + 0.587 * pixel.g + 0.114 * pixel.b).round.clamp(0, 255)
+      if source.respond_to?(:packed_pixels)
+        packed = source.packed_pixels
+        r_shift, g_shift, b_shift = packed_shifts
+        i = 0
+        (width * height).times do
+          color = packed[i]
+          r = (color >> r_shift) & 0xFF
+          g = (color >> g_shift) & 0xFF
+          b = (color >> b_shift) & 0xFF
+          luminance[i] = (0.299 * r + 0.587 * g + 0.114 * b).round.clamp(0, 255)
+          i += 1
+        end
+      else
+        height.times do |y|
+          row = y * width
+          width.times do |x|
+            pixel = source[x, y]
+            luminance[row + x] = (0.299 * pixel.r + 0.587 * pixel.g + 0.114 * pixel.b).round.clamp(0, 255)
+          end
         end
       end
       luminance
@@ -241,15 +274,31 @@ module PureJPEG
       cb_data = Array.new(size)
       cr_data = Array.new(size)
 
-      height.times do |py|
-        row = py * width
-        width.times do |px|
-          pixel = source[px, py]
-          r = pixel.r; g = pixel.g; b = pixel.b
-          i = row + px
+      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]  = ( 0.299    * r + 0.587    * g + 0.114    * b).round.clamp(0, 255)
           cb_data[i] = (-0.168736 * r - 0.331264 * g + 0.5      * b + 128.0).round.clamp(0, 255)
           cr_data[i] = ( 0.5      * r - 0.418688 * g - 0.081312 * b + 128.0).round.clamp(0, 255)
+          i += 1
+        end
+      else
+        height.times do |py|
+          row = py * width
+          width.times do |px|
+            pixel = source[px, py]
+            r = pixel.r; g = pixel.g; b = pixel.b
+            i = row + px
+            y_data[i]  = ( 0.299    * r + 0.587    * g + 0.114    * b).round.clamp(0, 255)
+            cb_data[i] = (-0.168736 * r - 0.331264 * g + 0.5      * b + 128.0).round.clamp(0, 255)
+            cr_data[i] = ( 0.5      * r - 0.418688 * g - 0.081312 * b + 128.0).round.clamp(0, 255)
+          end
         end
       end
 

data/lib/pure_jpeg/huffman/decoder.rb

@@ -33,7 +33,7 @@ module PureJPEG
             return @values[@val_ptr[len] + code - @min_code[len]]
           end
         end
-        raise "Invalid Huffman code"
+        raise PureJPEG::DecodeError, "Invalid Huffman code"
       end
     end
   end

data/lib/pure_jpeg/huffman/encoder.rb

@@ -33,8 +33,8 @@ module PureJPEG
         last_nonzero = 63
         last_nonzero -= 1 while last_nonzero > 0 && zigzag[last_nonzero] == 0
 
-        if last_nonzero == 0 && zigzag[0] == zigzag[0]  # AC starts at index 1
-          # All AC coefficients are zero
+        if last_nonzero == 0
+          # All AC coefficients are zero (AC starts at index 1)
           eob = @ac_table[0x00]
           writer.write_bits(eob[0], eob[1])
           return

data/lib/pure_jpeg/huffman/tables.rb

@@ -64,8 +64,9 @@ module PureJPEG
 
     # Build a lookup table: symbol -> [code, code_length]
     # from the bits/values specification.
+    # Returns an Array indexed by symbol value for O(1) lookup.
     def self.build_table(bits, values)
-      table = {}
+      table = Array.new(256)
       code = 0
       k = 0
 

data/lib/pure_jpeg/image.rb

@@ -3,22 +3,28 @@
 module PureJPEG
   # A decoded JPEG image with pixel-level access.
   #
-  # Implements the same pixel source interface (+width+, +height+, +[x, y]+)
-  # as encoder inputs, so a decoded image can be passed directly to
-  # {PureJPEG.encode} for re-encoding.
+  # Internally stores pixels as packed integers (+r << 16 | g << 8 | b+) to
+  # avoid per-pixel object allocation. Implements the same pixel source
+  # interface (+width+, +height+, +[x, y]+) as encoder inputs, so a decoded
+  # image can be passed directly to {PureJPEG.encode} for re-encoding.
   class Image
     # @return [Integer] image width in pixels
     attr_reader :width
     # @return [Integer] image height in pixels
     attr_reader :height
 
+    # @return [Array<Integer>] flat row-major array of packed RGB integers.
+    #   Format: +(r << 16) | (g << 8) | b+.
+    attr_reader :packed_pixels
+
     # @param width [Integer]
     # @param height [Integer]
-    # @param pixels [Array<Source::Pixel>] flat row-major array of pixels
-    def initialize(width, height, pixels)
+    # @param packed_pixels [Array<Integer>] flat row-major array of packed RGB
+    #   integers in the format +(r << 16) | (g << 8) | b+
+    def initialize(width, height, packed_pixels)
       @width = width
       @height = height
-      @pixels = pixels
+      @packed_pixels = packed_pixels
     end
 
     # Retrieve a pixel by coordinate.
@@ -27,7 +33,8 @@ module PureJPEG
     # @param y [Integer] row (0-based)
     # @return [Source::Pixel] pixel with +.r+, +.g+, +.b+ in 0-255
     def [](x, y)
-      @pixels[y * @width + x]
+      color = @packed_pixels[y * @width + x]
+      Source::Pixel.new((color >> 16) & 0xFF, (color >> 8) & 0xFF, color & 0xFF)
     end
 
     # Set a pixel by coordinate.
@@ -37,7 +44,8 @@ module PureJPEG
     # @param pixel [Source::Pixel] replacement pixel
     # @return [Source::Pixel]
     def []=(x, y, pixel)
-      @pixels[y * @width + x] = pixel
+      @packed_pixels[y * @width + x] = (pixel.r << 16) | (pixel.g << 8) | pixel.b
+      pixel
     end
 
     # Iterate over every pixel in the image.
@@ -53,5 +61,24 @@ module PureJPEG
         end
       end
     end
+
+    # Iterate over every pixel without allocating Pixel structs.
+    #
+    # @yieldparam x [Integer] column
+    # @yieldparam y [Integer] row
+    # @yieldparam r [Integer] red component (0-255)
+    # @yieldparam g [Integer] green component (0-255)
+    # @yieldparam b [Integer] blue component (0-255)
+    # @return [void]
+    def each_rgb
+      i = 0
+      @height.times do |y|
+        @width.times do |x|
+          color = @packed_pixels[i]
+          yield x, y, (color >> 16) & 0xFF, (color >> 8) & 0xFF, color & 0xFF
+          i += 1
+        end
+      end
+    end
   end
 end

data/lib/pure_jpeg/jfif_reader.rb

@@ -3,10 +3,11 @@
 module PureJPEG
   class JFIFReader
     attr_reader :width, :height, :components, :quant_tables, :huffman_tables,
-                :scan_components, :scan_data, :restart_interval
+                :restart_interval, :progressive, :scans
 
     Component = Struct.new(:id, :h_sampling, :v_sampling, :qt_id)
     ScanComponent = Struct.new(:id, :dc_table_id, :ac_table_id)
+    Scan = Struct.new(:components, :spectral_start, :spectral_end, :successive_high, :successive_low, :data, :huffman_tables)
 
     def initialize(data)
       @data = data.b
@@ -14,11 +15,20 @@ module PureJPEG
       @quant_tables = {}
       @huffman_tables = {}
       @components = []
-      @scan_components = []
       @restart_interval = 0
+      @progressive = false
+      @scans = []
       parse
     end
 
+    def scan_components
+      @scans.first&.components || []
+    end
+
+    def scan_data
+      @scans.first&.data || "".b
+    end
+
     private
 
     def parse
@@ -35,14 +45,21 @@ module PureJPEG
           parse_dht
         when 0xC0 # SOF0 (baseline)
           parse_sof0
+        when 0xC2 # SOF2 (progressive)
+          parse_sof0
+          @progressive = true
         when 0xDA # SOS
-          parse_sos
-          extract_scan_data
-          return
+          scan = parse_sos
+          scan.data = extract_scan_data
+          scan.huffman_tables = @huffman_tables.dup
+          @scans << scan
+          return unless @progressive
         when 0xFE # COM (comment)
           skip_segment
         when 0xDD # DRI (restart interval)
           parse_dri
+        when 0xD9 # EOI
+          return
         else
           skip_segment
         end
@@ -50,6 +67,7 @@ module PureJPEG
     end
 
     def read_byte
+      raise PureJPEG::DecodeError, "Unexpected end of JPEG data" if @pos >= @data.bytesize
       byte = @data.getbyte(@pos)
       @pos += 1
       byte
@@ -61,7 +79,7 @@ module PureJPEG
 
     def read_marker
       byte = read_byte
-      raise "Expected 0xFF, got 0x#{byte.to_s(16)}" unless byte == 0xFF
+      raise PureJPEG::DecodeError, "Expected 0xFF, got 0x#{byte.to_s(16)}" unless byte == 0xFF
       # Skip padding 0xFF bytes
       code = read_byte
       code = read_byte while code == 0xFF
@@ -70,7 +88,7 @@ module PureJPEG
 
     def expect_marker(expected)
       marker = read_marker
-      raise "Expected marker 0x#{expected.to_s(16)}, got 0x#{marker.to_s(16)}" unless marker == expected
+      raise PureJPEG::DecodeError, "Expected marker 0x#{expected.to_s(16)}, got 0x#{marker.to_s(16)}" unless marker == expected
     end
 
     def skip_segment
@@ -136,7 +154,7 @@ module PureJPEG
       read_u16 # length
       num_components = read_byte
 
-      @scan_components = Array.new(num_components) do
+      components = Array.new(num_components) do
         id = read_byte
         tables = read_byte
         dc_id = (tables >> 4) & 0x0F
@@ -144,8 +162,12 @@ module PureJPEG
         ScanComponent.new(id, dc_id, ac_id)
       end
 
-      # Spectral selection and approximation (ignored for baseline)
-      3.times { read_byte }
+      ss = read_byte  # spectral selection start
+      se = read_byte  # spectral selection end
+      ahl = read_byte # successive approximation
+      ah = (ahl >> 4) & 0x0F
+      al = ahl & 0x0F
+      Scan.new(components, ss, se, ah, al, nil)
     end
 
     def parse_dri
@@ -156,18 +178,20 @@ module PureJPEG
     # Extract entropy-coded scan data (everything from current position to EOI marker).
     def extract_scan_data
       start = @pos
+      len = @data.bytesize
       # Scan forward looking for a marker that isn't a stuffing byte or restart
-      while @pos < @data.bytesize - 1
-        if @data.getbyte(@pos) == 0xFF
-          next_byte = @data.getbyte(@pos + 1)
-          # 0x00 is byte stuffing, 0xD0-0xD7 are restart markers — all part of scan data
-          if next_byte != 0x00 && !(next_byte >= 0xD0 && next_byte <= 0xD7) && next_byte != 0xFF
-            break
-          end
+      while @pos < len - 1
+        found = @data.index("\xFF".b, @pos)
+        break unless found && found < len - 1
+        @pos = found
+        next_byte = @data.getbyte(@pos + 1)
+        # 0x00 is byte stuffing, 0xD0-0xD7 are restart markers, 0xFF is padding — all part of scan data
+        if next_byte != 0x00 && !(next_byte >= 0xD0 && next_byte <= 0xD7) && next_byte != 0xFF
+          break
         end
-        @pos += 1
+        @pos += 2
       end
-      @scan_data = @data[start...@pos]
+      @data[start...@pos]
     end
   end
 end

data/lib/pure_jpeg/source/chunky_png_source.rb

@@ -19,22 +19,25 @@ module PureJPEG
 
       # @param image [ChunkyPNG::Image] the source PNG image
       def initialize(image)
-        @image = image
         @width = image.width
         @height = image.height
+        @packed_pixels = image.pixels
       end
 
+      # @return [Array<Integer>] flat row-major array of packed RGBA integers
+      attr_reader :packed_pixels
+
       # Retrieve a pixel at the given coordinate.
       #
       # @param x [Integer] column (0-based)
       # @param y [Integer] row (0-based)
       # @return [Pixel]
       def [](x, y)
-        color = @image[x, y]
+        color = @packed_pixels[y * @width + x]
         Pixel.new(
-          ChunkyPNG::Color.r(color),
-          ChunkyPNG::Color.g(color),
-          ChunkyPNG::Color.b(color)
+          (color >> 24) & 0xFF,
+          (color >> 16) & 0xFF,
+          (color >> 8) & 0xFF
         )
       end
     end

data/lib/pure_jpeg/source/raw_source.rb

@@ -27,7 +27,8 @@ module PureJPEG
       def initialize(width, height, &block)
         @width = width
         @height = height
-        @pixels = Array.new(width * height)
+        black = Pixel.new(0, 0, 0)
+        @pixels = Array.new(width * height, black)
 
         if block
           height.times do |y|

data/lib/pure_jpeg/version.rb

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

data/lib/pure_jpeg.rb

@@ -25,6 +25,9 @@ require_relative "pure_jpeg/decoder"
   # Supports baseline DCT (SOF0) with 8-bit precision, grayscale and YCbCr
   # color (4:2:0 chroma subsampling), and standard Huffman tables (Annex K).
 module PureJPEG
+  # Raised when decoding invalid or unsupported JPEG data.
+  class DecodeError < StandardError; end
+
   # Encode a pixel source as a JPEG.
   #
   # @param source [#width, #height, #[]] any object responding to +width+,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pure_jpeg
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Peter Cooper
@@ -78,7 +78,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="