pure_jpeg 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 780f932b176fecdb5daab2546909fe2610325e54f7364cf482e3e2652ab614a5
-  data.tar.gz: 1fbc350f25d09b989ee6262e077bb36847c6637db325fb03c29f2083bb0ec973
+  metadata.gz: 7c252d678f3b8c916a2430b802569dc5099a19636359e9864637ed9fe01c90a3
+  data.tar.gz: 8feec524d8c41ca74be1e9bc47cf41b762cb14dc3500dc03c9240680d5877933
 SHA512:
-  metadata.gz: a385db40804bf4a992d78253ba619e90b147aa5be7808b341398918f5f36c3593fbd1a979aaad9729ad874f2427fe15d31fc9a0413e5f7ea98ee44e43e125f2d
-  data.tar.gz: b9f5581f4c4f27f42460961b3b4231fd94b45be130fbdce74a28bc4888f2a2f3de08fd43b9e3efc782ccb6b4f260aa8484ff7794e7bde1362018dc3deb282b26
+  metadata.gz: c8d26b4d4bed6da87f048036b06bc80eddd6c7ff8318032fb9cfccc15f5aea961e62fefe9965dde33c3d33cea5b611b4c2f6cb2397efa2f43effd8eb456fcf93
+  data.tar.gz: 63a9fe6bdf1136c8ea6c8e38a6b6641e6be2975fef4fea9394f0b48de22b01862996a87557b5c0bf7d7915020630f08c9285ebf8b8e8482f38f228c31b2d08e7

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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, and JRuby 10.0. 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,77 @@ Possible future improvements: ICC profile rendering/conversion.
 
 ## Performance
 
-On a 1024x1024 image (Ruby 4.0.2 with YJIT on an M5):
+On a 1024x1024 image (Apple M5, 5 runs after warmup):
+
+| Operation | CRuby 4.0.2 (YJIT) | TruffleRuby 33.0.1 |
+|-----------|---------------------|---------------------|
+| Encode (color, q85) | ~0.16s | ~0.08s |
+| Decode (baseline) | ~0.14s | ~0.05s |
+| Decode (progressive) | ~0.18s | ~0.09s |
+
+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, resulting in 2-3x faster performance 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.
 
-| Operation | Time |
-|-----------|------|
-| Encode (color, q85) | ~0.16s |
-| Decode (baseline) | ~0.14s |
-| Decode (progressive) | ~0.18s |
+```
+ruby examples/png_to_jpeg.rb [--grayscale] INPUT.png OUTPUT.jpg [quality]
+```
+
+**`jpeg_to_png.rb`** -- Convert a JPEG to PNG.
 
-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.
+```
+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.
+
+```
+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]
+```
+
+**`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 +295,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/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"

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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PureJPEG
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 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.3.3
 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: []