image_pack 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e741b4071a7d8ef87a2bbfb62f1d3a5fe11e809eac31463ee52f3f919833f148
-  data.tar.gz: f60b9c3bb2e8ff303099b5339a170640950c1e0928686d19c5a0f9bafe297c30
+  metadata.gz: 606688569aac1fa1515edefe270b18a04e5b0042de602b18663964726d8fbb34
+  data.tar.gz: 9092fcf9fa3c061edc87ce2a22544acfe52dfa6ce4fe39961c95a1d17220a6b0
 SHA512:
-  metadata.gz: 966485e630b9ab72ab0e193aaa588a8d396bbb9f8fd5dba40e0e2a17eaa392cc2d7944134b679ec5e73fdd6902ba9db24dbff6582aaa1071b9f1986c77df8590
-  data.tar.gz: c1f70b669944ce35139f005cc4ed24db9634c51af8ff90d509eec6c6544c4c664525c27b9eb9045ac40fb3ea9bf81ea36e75ad7ce842427fd8968c289ed03ae6
+  metadata.gz: ad6b0db99c56d69c99d9216559e3c114a2079941a4f879e69508126bbf12b070844dc53e806b3da7637783a205528c10136c3cd3bac8f60b5fd6ee2ddcad01eb
+  data.tar.gz: f1acfa9f5a7154d1ea201ae66658da704a5ee5d207886b096d284b7b69eca175d668993dba127b0a609d6fb5b68492196edb8d3bb70d12575f129c095c6b7704

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+- Lowered the runtime floor to Ruby >= 3.1.0 while keeping `execution: :offload` Ruby >= 3.4-only and explicitly unsupported on older Rubies.
+## 0.2.2
+
+- Fixed native cleanup safety: native contexts are now released through `rb_ensure`, including Ruby exception paths from argument coercion, config reads, native status errors, output `String` allocation, and file-output failures.
+- Fixed libjpeg `longjmp` cleanup for encode/decode/luma-decode transient buffers.
+- Fixed `max_output_size = 0` semantics; all size/dimension limits now consistently treat `0` as disabled.
+- Fixed `compress_pixels(min_ssim:)`: it now uses the raw pixel buffer as the reference instead of a temporary quality-95 seed JPEG, and it respects the requested execution mode.
+- Fixed metadata preservation drift: `strip_metadata: false` now preserves markers across fast, size, and SSIM paths.
+- Fixed EXIF Orientation stripping: when metadata is stripped, orientation is applied to decoded pixels before output.
+- Fixed `progressive:` for `algo: :mozjpeg`; `progressive: false` no longer silently inherits the max-compression progressive scan script.
+- Added decode/luma-decode cancellation checkpoints.
+- Reduced avoidable copying for explicit `execution: :direct` String/pixel inputs.
+- Batched RGBA→RGB scanline encoding instead of writing one line at a time.
+- Decoded SSIM candidate luma directly as grayscale instead of RGB + manual luma conversion.
+- Made output-path writes safer by writing to a temporary file, checking `fclose`, and renaming into place.
+- Added `compress_bytes`, `compress_file`, `optimize_jpeg`, `optimize_bytes`, `optimize_file`, and `build_info`.
+- Added coefficient-level lossless JPEG optimization through `jpeg_read_coefficients` / `jpeg_write_coefficients`; this avoids decode→pixels→re-encode when only optimizing an existing JPEG.
+- Made private native entrypoints private class methods.
+- Added `-fvisibility=hidden` and `IMAGE_PACK_REQUIRE_SIMD=1` build guard.
+
 ## 0.2.1
 
 - `ip_compute_ssim_luma_buffer`: rewrote inner accumulators from `double` to

data/README.md

@@ -1,8 +1,8 @@
 # image_pack
 
-`image_pack` is a Ruby-native JPEG compressor prototype for Ruby `>= 3.4.0`.
+`image_pack` is a Ruby-native JPEG compressor prototype for Ruby `>= 3.1.0`.
 
-Current version: `0.2.0`.
+Current version: `0.2.2`.
 
 This pure-C variant intentionally removes Jpegli and any C++ toolchain requirement.
 The native layer is written in C and links against vendored MozJPEG, which is libjpeg-compatible and based on libjpeg-turbo.
@@ -14,8 +14,8 @@ ImagePack.compress(input, algo: :jpeg_turbo)
 ImagePack.compress(input, algo: :mozjpeg)
 ```
 
-- `:jpeg_turbo` — fast libjpeg-compatible mode with MozJPEG-specific size optimizations disabled.
-- `:mozjpeg` — size-oriented mode using progressive/optimized Huffman coding through the MozJPEG/libjpeg API.
+- `:jpeg_turbo` / `:fast` — fast libjpeg-compatible mode with MozJPEG-specific size optimizations disabled.
+- `:mozjpeg` / `:size` — size-oriented mode using optimized Huffman coding and optional progressive output through the MozJPEG/libjpeg API.
 
 Both modes produce ordinary `.jpg` files.
 
@@ -52,6 +52,14 @@ ImagePack.compress(jpeg, algo: :mozjpeg, min_ssim: 0.985)
 ImagePack.compress(jpeg, algo: :mozjpeg, quality: 75, min_ssim: 0.985)
 
 ImagePack.compress("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
+ImagePack.compress_file("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
+ImagePack.compress_bytes(jpeg, algo: :fast, quality: 82)
+
+# Lossless coefficient-level JPEG optimization/transcode.
+# This rewrites JPEG coefficients without decoding/re-encoding pixels.
+ImagePack.optimize_jpeg(jpeg, progressive: true, strip_metadata: false)
+ImagePack.optimize_file("photo.jpg", output: "photo.lossless.jpg")
+ImagePack.optimize_bytes(jpeg)
 
 ImagePack.compress_pixels(rgb_buffer,
   width: 1920,
@@ -69,19 +77,32 @@ ImagePack.inspect_image(jpeg)
 `compress(input, ...)` accepts JPEG input only:
 
 - binary `String` (`ASCII-8BIT`) — JPEG bytes;
-- non-binary `String` — file path;
+- non-binary `String` that points to an existing file — file path;
 - `Pathname` — file path;
 - `IO::Buffer` — JPEG bytes, copied before native no-GVL execution for safety.
 
+For non-ambiguous call sites prefer `compress_bytes(bytes, ...)` or `compress_file(path, ...)`.
+
 `compress_pixels(buffer, ...)` accepts raw pixels as binary `String` or `IO::Buffer`.
-`channels` must be `1`, `3`, or `4`. Alpha in RGBA input is dropped in v0.2.0.
+`channels` must be `1`, `3`, or `4`. Alpha in RGBA input is dropped in v0.2.2; pass `drop_alpha: true` to make that explicit, or `drop_alpha: false` to reject it.
+
+`output: nil` returns binary JPEG bytes. `output: String/Pathname` writes through a temporary file and renames it into place.
+Streaming output is intentionally not supported in v0.2.2.
+
+## Lossless JPEG optimize
+
+`optimize_jpeg`, `optimize_bytes`, and `optimize_file` are coefficient-level JPEG transcode helpers. They use `jpeg_read_coefficients` / `jpeg_write_coefficients`, so pixels are not decoded and re-encoded. This is the preferred path when you only want to rewrite an existing JPEG with optimized Huffman tables and optional progressive scans.
+
+Defaults are intentionally conservative:
 
-`output: nil` returns binary JPEG bytes. `output: String/Pathname` writes to path and returns `true`.
-Streaming output is intentionally not supported in v0.2.0.
+- `progressive: true` creates a progressive optimized JPEG;
+- `strip_metadata: false` preserves APP/COM metadata by default because this path is meant to be visually/losslessly safe.
+
+If `strip_metadata: true` is requested and the source JPEG has EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently removing the orientation tag and changing how viewers display the image. Use `strip_metadata: false` for coefficient-level optimization, or `compress(..., strip_metadata: true)` if you want pixel-level orientation normalization.
 
 ## SSIM guard
 
-`compress` accepts `min_ssim:` for JPEG input. This enables a native guarded path:
+`compress` and `compress_pixels` accept `min_ssim:`. This enables a native guarded path:
 
 1. decode the original JPEG to reference pixels;
 2. encode trial JPEG candidates with the existing MozJPEG/libjpeg backend;
@@ -96,11 +117,31 @@ the encoder raises quality only if the candidate violates the SSIM floor.
 If no quality can satisfy the requested floor, `ImagePack::QualityConstraintError`
 is raised. With `execution: :auto`, guarded compression uses the no-GVL/offload
 path instead of the small-image direct path because it may encode/decode several
-candidates. `min_ssim` is intentionally not supported by `compress_pixels` in
-this release.
+candidates. For `compress_pixels`, the reference is the raw pixel buffer itself, not a seed JPEG. RGBA + `min_ssim` is rejected because JPEG cannot represent alpha.
+
+The metric is a fast native luma SSIM-like guard based on 8x8 blocks, not a full Wang-style Gaussian-window reference implementation. It is intended as a compression guard, not as a general-purpose image quality benchmark.
 
 ## Execution modes
 
+### Ruby compatibility for offload
+
+ImagePack supports Ruby `>= 3.1.0`. Ruby `>= 3.4.0` is required only for the scheduler-aware `execution: :offload` path.
+
+On Ruby 3.1–3.3:
+
+- `execution: :direct` works.
+- `execution: :nogvl` works.
+- `execution: :auto` works, but never selects `:offload`.
+- explicit `execution: :offload` raises `ImagePack::UnsupportedError`.
+
+On Ruby 3.4+:
+
+- `execution: :offload` is available.
+- `execution: :auto` may select `:offload` when a Fiber scheduler is active.
+
+Use `ImagePack.offload_safe?` or `ImagePack.build_info[:offload_safe]` to check the native capability at runtime.
+
+
 ```ruby
 ImagePack.compress(jpeg, execution: :direct)
 ImagePack.compress(jpeg, execution: :nogvl)
@@ -110,13 +151,24 @@ ImagePack.compress(jpeg, execution: :auto)
 
 - `:direct` — executes under GVL, intended for small images.
 - `:nogvl` — uses `rb_nogvl(..., flags: 0)`.
-- `:offload` — uses `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` on Ruby 3.4+.
-- `:auto` — header-first policy chooses direct/nogvl/offload.
+- `:offload` — uses `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` on Ruby 3.4+; raises `ImagePack::UnsupportedError` on Ruby 3.1–3.3.
+- `:auto` — header-first policy chooses direct/nogvl/offload; on Ruby 3.1–3.3 it never selects offload.
 
 ## Cancellation
 
-`cancellable: true` is supported only for `algo: :mozjpeg` and `execution: :nogvl`, `:offload`, or `:auto`.
-Cancellation is cooperative at encoder scanline checkpoints, not instant.
+`cancellable: true` is supported for `execution: :nogvl`, `:offload`, or `:auto`.
+Cancellation is cooperative at decode, encode, and SSIM-search checkpoints, not instant.
+
+## Metadata / EXIF orientation
+
+`strip_metadata: true` removes metadata. If the source JPEG contains EXIF Orientation, `image_pack` applies that orientation to decoded pixels before stripping metadata, so the visual orientation is preserved. With `strip_metadata: false`, APP/COM markers are preserved across both fast and size-oriented paths.
+
+## Build info
+
+```ruby
+ImagePack.build_info
+# => { version: "0.2.2", mozjpeg: "4.1.5", simd: true, offload_safe: true }
+```
 
 ## Vendoring
 
@@ -130,11 +182,18 @@ bundle exec rake compile
 
 `rake vendor` pins MozJPEG `v4.1.5`.
 
+## Current limitations
+
+- Pixel-level `compress` rejects CMYK/YCCK JPEG input because it decodes to RGB/gray before re-encoding. Use `optimize_jpeg` for coefficient-level lossless optimization of existing CMYK/YCCK JPEGs.
+- Arithmetic-coded JPEG support is disabled in the vendored `jconfig.h` for v0.2.2.
+- The SSIM guard is a fast 8x8 luma block metric and still assumes quality/SSIM monotonicity during binary search.
+- `compress(input, ...)` still has a legacy path-vs-bytes heuristic for non-binary `String`; prefer `compress_bytes` / `compress_file` and `optimize_bytes` / `optimize_file` in new code.
+
 ## What is intentionally not included
 
 - Jpegli / C++ code
 - AVIF/WebP/PNG
 - FFI
 - shell-out
-- tempfiles by default
+- external tempfiles for in-memory output
 - byte-size targets / max-bytes policy

data/ext/image_pack/extconf.rb

@@ -4,127 +4,19 @@ require "mkmf"
 require "fileutils"
 require "rbconfig"
 
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.4.0")
-  abort "image_pack requires Ruby >= 3.4.0; got #{RUBY_VERSION}"
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.1.0")
+  abort "image_pack requires Ruby >= 3.1.0; got #{RUBY_VERSION}"
 end
 
-MOZJPEG_CORE_SOURCES = %w[
-  jcapimin.c
-  jcapistd.c
-  jccoefct.c
-  jccolor.c
-  jcdctmgr.c
-  jchuff.c
-  jcext.c
-  jcicc.c
-  jcinit.c
-  jcmainct.c
-  jcmarker.c
-  jcmaster.c
-  jcomapi.c
-  jcparam.c
-  jcphuff.c
-  jcprepct.c
-  jcsample.c
-  jctrans.c
-  jdapimin.c
-  jdapistd.c
-  jdatadst.c
-  jdatasrc.c
-  jdcoefct.c
-  jdcolor.c
-  jddctmgr.c
-  jdhuff.c
-  jdicc.c
-  jdinput.c
-  jdmainct.c
-  jdmarker.c
-  jdmaster.c
-  jdmerge.c
-  jdphuff.c
-  jdpostct.c
-  jdsample.c
-  jdtrans.c
-  jerror.c
-  jfdctflt.c
-  jfdctfst.c
-  jfdctint.c
-  jidctflt.c
-  jidctfst.c
-  jidctint.c
-  jidctred.c
-  jquant1.c
-  jquant2.c
-  jutils.c
-  jmemmgr.c
-  jmemnobs.c
-].freeze
-
-NEON_AARCH64_SOURCES = [
-  "simd/arm/aarch64/jsimd.c",
-  "simd/arm/aarch64/jchuff-neon.c",
-  "simd/arm/jccolor-neon.c",
-  "simd/arm/jcgray-neon.c",
-  "simd/arm/jcphuff-neon.c",
-  "simd/arm/jcsample-neon.c",
-  "simd/arm/jdcolor-neon.c",
-  "simd/arm/jdmerge-neon.c",
-  "simd/arm/jdsample-neon.c",
-  "simd/arm/jfdctfst-neon.c",
-  "simd/arm/jfdctint-neon.c",
-  "simd/arm/jidctfst-neon.c",
-  "simd/arm/jidctint-neon.c",
-  "simd/arm/jidctred-neon.c",
-  "simd/arm/jquanti-neon.c",
-].freeze
-
-X86_64_C_SOURCES = [
-  "simd/x86_64/jsimd.c",
-].freeze
-
-X86_64_ASM_SOURCES = %w[
-  simd/x86_64/jsimdcpu.asm
-  simd/x86_64/jfdctflt-sse.asm
-  simd/x86_64/jccolor-sse2.asm
-  simd/x86_64/jcgray-sse2.asm
-  simd/x86_64/jchuff-sse2.asm
-  simd/x86_64/jcphuff-sse2.asm
-  simd/x86_64/jcsample-sse2.asm
-  simd/x86_64/jdcolor-sse2.asm
-  simd/x86_64/jdmerge-sse2.asm
-  simd/x86_64/jdsample-sse2.asm
-  simd/x86_64/jfdctfst-sse2.asm
-  simd/x86_64/jfdctint-sse2.asm
-  simd/x86_64/jidctflt-sse2.asm
-  simd/x86_64/jidctfst-sse2.asm
-  simd/x86_64/jidctint-sse2.asm
-  simd/x86_64/jidctred-sse2.asm
-  simd/x86_64/jquantf-sse2.asm
-  simd/x86_64/jquanti-sse2.asm
-  simd/x86_64/jccolor-avx2.asm
-  simd/x86_64/jcgray-avx2.asm
-  simd/x86_64/jcsample-avx2.asm
-  simd/x86_64/jdcolor-avx2.asm
-  simd/x86_64/jdmerge-avx2.asm
-  simd/x86_64/jdsample-avx2.asm
-  simd/x86_64/jfdctint-avx2.asm
-  simd/x86_64/jidctint-avx2.asm
-  simd/x86_64/jquanti-avx2.asm
-].freeze
-
-X86_64_ASM_TEMPLATE_SOURCES = %w[
-  simd/x86_64/jccolext-sse2.asm
-  simd/x86_64/jcgryext-sse2.asm
-  simd/x86_64/jdcolext-sse2.asm
-  simd/x86_64/jdmrgext-sse2.asm
-  simd/x86_64/jccolext-avx2.asm
-  simd/x86_64/jcgryext-avx2.asm
-  simd/x86_64/jdcolext-avx2.asm
-  simd/x86_64/jdmrgext-avx2.asm
-].freeze
-
-MOZJPEG_VERSION = "4.1.5"
-MOZJPEG_VERSION_NUMBER = "4001005"
+require_relative "mozjpeg_sources"
+
+MOZJPEG_CORE_SOURCES = ImagePackMozjpegSources::TOPLEVEL_C_SOURCES
+MOZJPEG_INCLUDE_TEMPLATES = ImagePackMozjpegSources::TOPLEVEL_INCLUDE_TEMPLATES
+NEON_AARCH64_SOURCES = ImagePackMozjpegSources::NEON_AARCH64_C_SOURCES
+X86_64_C_SOURCES = ImagePackMozjpegSources::X86_64_C_SOURCES
+X86_64_ASM_SOURCES = ImagePackMozjpegSources::X86_64_ASM_SOURCES
+MOZJPEG_VERSION = ImagePackMozjpegSources::VERSION
+MOZJPEG_VERSION_NUMBER = ImagePackMozjpegSources::VERSION_NUMBER
 
 def find_vendor_dir
   candidates = [
@@ -285,8 +177,14 @@ def select_simd_backend(mozjpeg_dir, arch)
     else
       missing = NEON_AARCH64_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
       missing << "simd/arm/neon-compat.h.in" unless template_present
-      warn "image_pack: ARM64 detected but NEON sources missing under #{mozjpeg_dir}:"
-      missing.each { |m| warn "  - #{m}" }
+      message = "image_pack: ARM64 detected but NEON sources are incomplete under #{mozjpeg_dir}:
+"                 "#{missing.map { |m| "  - #{m}" }.join("
+")}"
+      if ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1"
+        abort "#{message}
+image_pack: refusing scalar fallback because IMAGE_PACK_REQUIRE_SIMD=1."
+      end
+      warn message
       warn "image_pack: re-run `bundle exec rake vendor` after updating script/vendor_libs.rb."
       warn "image_pack: falling back to scalar."
       { kind: :none }
@@ -294,16 +192,32 @@ def select_simd_backend(mozjpeg_dir, arch)
 
   when :x86_64
     if find_nasm.nil?
-      warn "image_pack: x86_64 detected but NASM/YASM not found on PATH. Falling back to scalar; install nasm for ~3-4x speedup."
+      message = "image_pack: x86_64 detected but NASM/YASM not found on PATH."
+      if ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1"
+        abort "#{message} Install nasm/yasm or unset IMAGE_PACK_REQUIRE_SIMD."
+      end
+      warn "#{message} Falling back to scalar; install nasm for ~3-4x speedup. Set IMAGE_PACK_REQUIRE_SIMD=1 to fail instead."
       { kind: :none }
     elsif !X86_64_C_SOURCES.all? { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
-      warn "image_pack: x86_64 SIMD sources missing under #{mozjpeg_dir}/simd/x86_64/. Falling back to scalar."
+      missing = X86_64_C_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
+      message = "image_pack: x86_64 SIMD C sources missing under #{mozjpeg_dir}: #{missing.join(', ')}"
+      ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1" ? abort(message) : warn("#{message}. Falling back to scalar.")
       { kind: :none }
     else
+      missing_asm = X86_64_ASM_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
+      unless missing_asm.empty?
+        message = "image_pack: x86_64 SIMD ASM sources missing under #{mozjpeg_dir}: #{missing_asm.join(', ')}"
+        if ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1"
+          abort message
+        end
+        warn "#{message}. Falling back to scalar."
+        return { kind: :none }
+      end
+
       {
         kind:           :x86_64_simd,
         c_sources:      X86_64_C_SOURCES,
-        asm_sources:    X86_64_ASM_SOURCES.select { |rel| File.exist?(File.join(mozjpeg_dir, rel)) },
+        asm_sources:    X86_64_ASM_SOURCES,
         extra_includes: [
           File.join(mozjpeg_dir, "simd"),
           File.join(mozjpeg_dir, "simd", "nasm"),
@@ -363,7 +277,8 @@ def configure_vendored_mozjpeg(vendor_dir)
 
   abort "vendored MozJPEG sources not found in #{mozjpeg_dir}" unless Dir.exist?(mozjpeg_dir)
 
-  missing_sources = MOZJPEG_CORE_SOURCES.reject { |source| File.exist?(File.join(mozjpeg_dir, source)) }
+  required_sources = MOZJPEG_CORE_SOURCES + MOZJPEG_INCLUDE_TEMPLATES
+  missing_sources = required_sources.reject { |source| File.exist?(File.join(mozjpeg_dir, source)) }
   abort "vendored MozJPEG sources are incomplete: #{missing_sources.join(', ')}" unless missing_sources.empty?
 
   arch = detect_simd_arch
@@ -489,7 +404,7 @@ $warnflags = ""
 
 unless msvc?
   $CFLAGS += " -O3 -Wall -Wextra -Wno-unused-parameter -Wno-sign-compare -std=gnu11"
-  $CFLAGS += " -fno-math-errno -fno-trapping-math"
+  $CFLAGS += " -fno-math-errno -fno-trapping-math -fvisibility=hidden"
 
   march = ENV["IMAGE_PACK_MARCH"].to_s
   unless march.empty?