pure_jpeg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e09848a734582d7635ff6a8c3d85b166da4f2c5b496d5c4f4e30105af4834e33
+  data.tar.gz: 052b8e0a21d58eb9aa9e169e06b7cfbde44f3610775da6fed86e05875dceaea3
+SHA512:
+  metadata.gz: 750ea3d65bf2ae6c272998b2ef7b814954eb1b576f6df83036d931543f30b99481281e8a12ef63fc388fdc60db0c54815fc8219b66782415844b3ed8721a5975
+  data.tar.gz: 16475c5174b009a7a45eec5ee288799ea7965e4e10ed02ab20d55b15de5ebbdf92e9c0196d58053b6539dfea4601d7e22016c636ee471d2e73300feb86d97f07

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Baseline DCT encoder (SOF0, 8-bit, Huffman)
+- YCbCr color with 4:2:0 chroma subsampling
+- Grayscale mode
+- Baseline DCT decoder with support for any chroma subsampling factor and restart markers
+- Creative encoding options: independent chroma quality, custom quantization tables, quantization modifier, scrambled quantization
+- Pure Ruby, no native dependencies

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,180 @@
+# PureJPEG
+
+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..)
+
+## Installation
+
+You know the drill: 
+
+```ruby
+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 ;-)
+
+`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.
+
+## Encoding (making JPEGs!)
+
+### From ChunkyPNG (easiest to get started)
+
+```ruby
+require "chunky_png"
+require "pure_jpeg"
+
+image = ChunkyPNG::Image.from_file("photo.png")
+PureJPEG.from_chunky_png(image, 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):
+
+```ruby
+require "pure_jpeg"
+
+encoder = PureJPEG.encode(source, quality: 85)
+encoder.write("output.jpg")
+
+# Or get raw bytes
+jpeg_data = encoder.to_bytes
+```
+
+### From raw pixel data
+
+```ruby
+source = PureJPEG::Source::RawSource.new(width, height) do |x, y|
+  [r, g, b]  # return RGB values 0-255
+end
+
+PureJPEG.encode(source).write("output.jpg")
+```
+
+### Grayscale
+
+```ruby
+PureJPEG.encode(source, grayscale: true).write("gray.jpg")
+```
+
+### Encoder options
+
+```ruby
+PureJPEG.encode(source,
+  quality: 85,                    # 1-100, overall compression level
+  grayscale: false,               # single-channel grayscale mode
+  chroma_quality: nil,            # 1-100, independent Cb/Cr quality (defaults to quality)
+  luminance_table: nil,           # custom 64-element quantization table for Y
+  chrominance_table: nil,         # custom 64-element quantization table for Cb/Cr
+  quantization_modifier: nil,     # proc(table, :luminance/:chrominance) -> modified table
+  scramble_quantization: false    # intentionally misordered quant tables (creative effect)
+)
+```
+
+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.
+
+## Decoding (reading JPEGs!)
+
+### From file
+
+```ruby
+image = PureJPEG.read("photo.jpg")
+image.width   # => 1024
+image.height  # => 768
+pixel = image[100, 200]
+pixel.r  # => 182
+pixel.g  # => 140
+pixel.b  # => 97
+```
+
+### From binary data
+
+```ruby
+image = PureJPEG.read(jpeg_bytes)
+```
+
+### Iterating pixels
+
+```ruby
+image.each_pixel do |x, y, pixel|
+  puts "#{x},#{y}: rgb(#{pixel.r}, #{pixel.g}, #{pixel.b})"
+end
+```
+
+### Re-encoding
+
+A decoded `PureJPEG::Image` implements the same pixel source interface, so it can be passed directly back to the encoder:
+
+```ruby
+image = PureJPEG.read("input.jpg")
+PureJPEG.encode(image, quality: 60).write("recompressed.jpg")
+```
+
+### Converting to PNG (with ChunkyPNG)
+
+```ruby
+image = PureJPEG.read("photo.jpg")
+
+png = ChunkyPNG::Image.new(image.width, image.height)
+image.each_pixel do |x, y, pixel|
+  png[x, y] = ChunkyPNG::Color.rgb(pixel.r, pixel.g, pixel.b)
+end
+png.save("photo.png")
+```
+
+## Format support
+
+Encoding:
+- Baseline DCT (SOF0)
+- 8-bit precision
+- Grayscale (1 component) and YCbCr color (3 components)
+- 4:2:0 chroma subsampling (color) or no subsampling (grayscale)
+- Standard Huffman tables (Annex K)
+
+Decoding:
+- Baseline DCT (SOF0)
+- 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!
+
+## Performance
+
+On a 1024x1024 image (Ruby 3.4 on my M1 Max):
+
+| Operation | Time |
+|-----------|------|
+| Encode (color, q85) | ~2.8s |
+| Decode (color) | ~12s |
+
+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).
+
+## Some useful `rake` tasks
+
+```
+bundle install
+rake test        # run the test suite
+rake benchmark   # benchmark encoding (3 runs against examples/a.png)
+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).
+
+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.
+
+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.
+
+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.
+
+## License
+
+MIT

data/lib/pure_jpeg/bit_reader.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PureJPEG
+  class BitReader
+    def initialize(data)
+      @data = data
+      @pos = 0
+      @length = data.bytesize
+      @buffer = 0
+      @bits_in_buffer = 0
+    end
+
+    def read_bit
+      fill_buffer if @bits_in_buffer == 0
+      @bits_in_buffer -= 1
+      (@buffer >> @bits_in_buffer) & 1
+    end
+
+    def read_bits(n)
+      return 0 if n == 0
+      value = 0
+      n.times { value = (value << 1) | read_bit }
+      value
+    end
+
+    # Discard remaining bits in the buffer (for restart marker boundaries).
+    def reset
+      @bits_in_buffer = 0
+      @buffer = 0
+    end
+
+    # Read additional bits and sign-extend per JPEG spec (receive/extend).
+    def receive_extend(size)
+      return 0 if size == 0
+      bits = read_bits(size)
+      if bits < (1 << (size - 1))
+        bits - (1 << size) + 1
+      else
+        bits
+      end
+    end
+
+    private
+
+    def fill_buffer
+      raise "Unexpected end of scan data" if @pos >= @length
+      byte = @data.getbyte(@pos)
+      @pos += 1
+      if byte == 0xFF
+        next_byte = @data.getbyte(@pos)
+        @pos += 1
+        # 0xFF 0x00 is a stuffed 0xFF byte
+        # Skip restart markers (0xD0-0xD7)
+        return fill_buffer if next_byte != 0x00 && next_byte >= 0xD0 && next_byte <= 0xD7
+        # For 0x00, the byte is 0xFF (stuffing removed)
+      end
+      @buffer = byte
+      @bits_in_buffer = 8
+    end
+  end
+end

data/lib/pure_jpeg/bit_writer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PureJPEG
+  class BitWriter
+    def initialize
+      @data = []
+      @buffer = 0
+      @bits_in_buffer = 0
+    end
+
+    # Write `num_bits` of `value` (MSB first) into the output stream.
+    def write_bits(value, num_bits)
+      return if num_bits == 0
+      @buffer = (@buffer << num_bits) | (value & ((1 << num_bits) - 1))
+      @bits_in_buffer += num_bits
+
+      while @bits_in_buffer >= 8
+        @bits_in_buffer -= 8
+        byte = (@buffer >> @bits_in_buffer) & 0xFF
+        @data << byte
+        @data << 0x00 if byte == 0xFF  # byte stuffing
+      end
+
+      @buffer &= (1 << @bits_in_buffer) - 1
+    end
+
+    # Pad remaining bits with 1s and flush (per JPEG spec).
+    def flush
+      return unless @bits_in_buffer > 0
+      padding = 8 - @bits_in_buffer
+      write_bits((1 << padding) - 1, padding)
+    end
+
+    def bytes
+      @data.pack("C*")
+    end
+  end
+end

data/lib/pure_jpeg/dct.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PureJPEG
+  module DCT
+    # Precomputed 8x8 DCT matrix: A[k][n] = (C(k)/2) * cos((2n+1)*k*pi/16)
+    # where C(0) = 1/sqrt(2), C(k) = 1 for k > 0.
+    # This lets us do the 2D DCT as two 1D matrix-vector multiplies (separable).
+    MATRIX = Array.new(8) { |k|
+      ck = k == 0 ? 0.5 / Math.sqrt(2.0) : 0.5
+      Array.new(8) { |n|
+        ck * Math.cos((2.0 * n + 1.0) * k * Math::PI / 16.0)
+      }
+    }.freeze
+
+    # Flatten for faster indexed access
+    MATRIX_FLAT = MATRIX.flatten.freeze
+
+    # Transposed matrix for inverse DCT: A^T[n][k] = A[k][n]
+    MATRIX_T_FLAT = Array.new(64) { |i| MATRIX_FLAT[(i % 8) * 8 + i / 8] }.freeze
+
+    # Separable forward 2D DCT: row pass then column pass.
+    # Writes result into `out`. Uses `temp` as scratch space.
+    # All three arrays must be pre-allocated with 64 elements.
+    def self.forward!(block, temp, out)
+      # Row pass: temp[y*8+u] = sum_x A[u][x] * block[y*8+x]
+      m = MATRIX_FLAT
+      8.times do |y|
+        y8 = y << 3
+        b0 = block[y8]; b1 = block[y8|1]; b2 = block[y8|2]; b3 = block[y8|3]
+        b4 = block[y8|4]; b5 = block[y8|5]; b6 = block[y8|6]; b7 = block[y8|7]
+        8.times do |u|
+          u8 = u << 3
+          temp[y8|u] = m[u8]*b0 + m[u8|1]*b1 + m[u8|2]*b2 + m[u8|3]*b3 +
+                       m[u8|4]*b4 + m[u8|5]*b5 + m[u8|6]*b6 + m[u8|7]*b7
+        end
+      end
+
+      # Column pass: out[v*8+u] = sum_y A[v][y] * temp[y*8+u]
+      8.times do |u|
+        t0 = temp[u]; t1 = temp[8|u]; t2 = temp[16|u]; t3 = temp[24|u]
+        t4 = temp[32|u]; t5 = temp[40|u]; t6 = temp[48|u]; t7 = temp[56|u]
+        8.times do |v|
+          v8 = v << 3
+          out[v8|u] = m[v8]*t0 + m[v8|1]*t1 + m[v8|2]*t2 + m[v8|3]*t3 +
+                      m[v8|4]*t4 + m[v8|5]*t5 + m[v8|6]*t6 + m[v8|7]*t7
+        end
+      end
+
+      out
+    end
+
+    # Separable inverse 2D DCT: same structure as forward but using A^T.
+    # f = A^T * F * A
+    def self.inverse!(block, temp, out)
+      mt = MATRIX_T_FLAT
+
+      # Row pass: temp[v*8+x] = sum_u A^T[x][u] * block[v*8+u]
+      8.times do |v|
+        v8 = v << 3
+        b0 = block[v8]; b1 = block[v8|1]; b2 = block[v8|2]; b3 = block[v8|3]
+        b4 = block[v8|4]; b5 = block[v8|5]; b6 = block[v8|6]; b7 = block[v8|7]
+        8.times do |x|
+          x8 = x << 3
+          temp[v8|x] = mt[x8]*b0 + mt[x8|1]*b1 + mt[x8|2]*b2 + mt[x8|3]*b3 +
+                        mt[x8|4]*b4 + mt[x8|5]*b5 + mt[x8|6]*b6 + mt[x8|7]*b7
+        end
+      end
+
+      # Column pass: out[y*8+x] = sum_v A^T[y][v] * temp[v*8+x]
+      8.times do |x|
+        t0 = temp[x]; t1 = temp[8|x]; t2 = temp[16|x]; t3 = temp[24|x]
+        t4 = temp[32|x]; t5 = temp[40|x]; t6 = temp[48|x]; t7 = temp[56|x]
+        8.times do |y|
+          y8 = y << 3
+          out[y8|x] = mt[y8]*t0 + mt[y8|1]*t1 + mt[y8|2]*t2 + mt[y8|3]*t3 +
+                       mt[y8|4]*t4 + mt[y8|5]*t5 + mt[y8|6]*t6 + mt[y8|7]*t7
+        end
+      end
+
+      out
+    end
+  end
+end

data/lib/pure_jpeg/decoder.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module PureJPEG
+  # Baseline JPEG decoder.
+  #
+  # Decodes baseline DCT (SOF0) JPEGs with 1 or 3 components, any chroma
+  # subsampling factor, and restart markers.
+  #
+  # Use {PureJPEG.read} for a convenient entry point.
+  class Decoder
+    # Decode a JPEG from a file path or binary string.
+    #
+    # @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)
+               File.binread(path_or_data)
+             else
+               path_or_data.b
+             end
+      new(data).decode
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def decode
+      jfif = JFIFReader.new(@data)
+      width = jfif.width
+      height = jfif.height
+
+      # Build Huffman decode tables
+      dc_tables = {}
+      ac_tables = {}
+      jfif.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
+
+      # Map component IDs to their info
+      comp_info = {}
+      jfif.components.each { |c| comp_info[c.id] = c }
+
+      # Determine max sampling factors
+      max_h = jfif.components.map(&:h_sampling).max
+      max_v = jfif.components.map(&:v_sampling).max
+
+      # MCU dimensions in pixels
+      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
+
+      # Allocate channel buffers (full padded size)
+      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
+
+      # Decode scan data
+      reader = BitReader.new(jfif.scan_data)
+      prev_dc = Hash.new(0)
+      restart_interval = jfif.restart_interval
+      mcu_count = 0
+
+      # Reusable buffers
+      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)
+
+      mcus_y.times do |mcu_row|
+        mcus_x.times do |mcu_col|
+          # Handle restart interval
+          if restart_interval > 0 && mcu_count > 0 && (mcu_count % restart_interval) == 0
+            reader.reset
+            prev_dc.clear
+          end
+
+          jfif.scan_components.each do |sc|
+            comp = comp_info[sc.id]
+            dc_tab = dc_tables[sc.dc_table_id]
+            ac_tab = ac_tables[sc.ac_table_id]
+            qt = jfif.quant_tables[comp.qt_id]
+            ch = channels[comp.id]
+
+            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)
+                DCT.inverse!(dequant, temp, spatial)
+
+                # Write block into channel buffer
+                bx = (mcu_col * comp.h_sampling + bh) * 8
+                by = (mcu_row * comp.v_sampling + bv) * 8
+                write_block(spatial, ch[:data], ch[:width], bx, by)
+              end
+            end
+          end
+
+          mcu_count += 1
+        end
+      end
+
+      # Assemble pixels
+      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
+
+    private
+
+    def decode_block(reader, dc_tab, ac_tab, prev_dc, comp_id, out)
+      # DC coefficient
+      dc_cat = dc_tab.decode(reader)
+      dc_diff = reader.receive_extend(dc_cat)
+      dc_val = prev_dc[comp_id] + dc_diff
+      prev_dc[comp_id] = dc_val
+      out[0] = dc_val
+
+      # AC coefficients
+      i = 1
+      while i < 64
+        symbol = ac_tab.decode(reader)
+        if symbol == 0x00 # EOB
+          while i < 64
+            out[i] = 0
+            i += 1
+          end
+          break
+        elsif symbol == 0xF0 # ZRL (16 zeros)
+          16.times do
+            out[i] = 0
+            i += 1
+          end
+        else
+          run = (symbol >> 4) & 0x0F
+          size = symbol & 0x0F
+          run.times do
+            out[i] = 0
+            i += 1
+          end
+          out[i] = reader.receive_extend(size)
+          i += 1
+        end
+      end
+
+      out
+    end
+
+    # Write an 8x8 spatial block (level-shifted by +128) into a channel buffer.
+    def write_block(spatial, channel, ch_width, bx, by)
+      8.times do |row|
+        dst_row = (by + row) * ch_width + bx
+        row8 = row << 3
+        8.times do |col|
+          val = (spatial[row8 | col] + 128.0).round
+          channel[dst_row + col] = val < 0 ? 0 : (val > 255 ? 255 : val)
+        end
+      end
+    end
+
+    def assemble_grayscale(width, height, channels, comp)
+      ch = channels[comp.id]
+      pixels = Array.new(width * height)
+      height.times do |y|
+        src_row = y * ch[:width]
+        dst_row = y * width
+        width.times do |x|
+          v = ch[:data][src_row + x]
+          pixels[dst_row + x] = Source::Pixel.new(v, v, v)
+        end
+      end
+      Image.new(width, height, pixels)
+    end
+
+    def assemble_color(width, height, channels, components, max_h, max_v)
+      # Upsample chroma channels if needed and convert YCbCr to RGB
+      y_ch  = channels[components[0].id]
+      cb_ch = channels[components[1].id]
+      cr_ch = channels[components[2].id]
+
+      cb_comp = components[1]
+      cr_comp = components[2]
+
+      pixels = Array.new(width * height)
+
+      height.times do |py|
+        dst_row = py * width
+        y_row = py * y_ch[:width]
+
+        # Chroma coordinates (nearest-neighbor upsampling)
+        cb_y = (py * cb_comp.v_sampling) / max_v
+        cr_y = (py * cr_comp.v_sampling) / max_v
+        cb_row = cb_y * cb_ch[:width]
+        cr_row = cr_y * cr_ch[:width]
+
+        width.times do |px|
+          lum = y_ch[:data][y_row + px]
+
+          cb_x = (px * cb_comp.h_sampling) / max_h
+          cr_x = (px * cr_comp.h_sampling) / max_h
+          cb = cb_ch[:data][cb_row + cb_x] - 128.0
+          cr = cr_ch[:data][cr_row + cr_x] - 128.0
+
+          r = (lum + 1.402 * cr).round
+          g = (lum - 0.344136 * cb - 0.714136 * cr).round
+          b = (lum + 1.772 * cb).round
+
+          r = r < 0 ? 0 : (r > 255 ? 255 : r)
+          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)
+        end
+      end
+
+      Image.new(width, height, pixels)
+    end
+  end
+end