oximg 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16e1f0079f0e556b9dd2bf4200f3e5667bb6904d1ab6597a7189dee077c731bc
-  data.tar.gz: cf19c0196c9636544db5c4318170b262a6ba9d57529776ef7fd0b13faa77e521
+  metadata.gz: f234cc2b72a4f0a06af417190cec9d9c2502c56fd5dcb88f4d56108f2ac1a277
+  data.tar.gz: 54f825fc86fbbe0149149393c25ffd4be99eec3fecb6ee3630b634088327e400
 SHA512:
-  metadata.gz: c0cf987fde6720add95242c3c5e12a21f395b27c2c32cc7ab8e52c9203d02162a3823315a68d4bb69719c13d831573256b87d7acf2e140fe6d97c30f18d46e30
-  data.tar.gz: a8d0316e4b3770e02c1f4347d6f9e514ba24a85b02903ea43b12a3ef01cbd875c851bbe2fc2ad634493ae601be810cf918d40407e3065d591da8562c57394c88
+  metadata.gz: ed00e440e6e93a7d045b73c2a0826efcc182b4420c76827bf233f821c7f45f909a2f2987083e86c585a2d79bed1791b019c4786efdb0f4be1033a2c181c25f1b
+  data.tar.gz: b0d9fe2516572b8495b754c60c0bccda2614bc26a5429141399a560ad873d264e0247d1aeab96d3af86856de647bd4c12939a003af75fdf858fab16d9b20c78f

data/README.md

@@ -20,7 +20,8 @@ Oximg.resize("in.jpg", "out.jpg", width: 750)
 Oximg.resize("in.jpg", "out.webp", width: 750, height: 500, quality: 80)
 Oximg.strip("upload.jpg", "clean.jpg")
 Oximg.probe("in.jpg")
-#=> {content_type: "image/jpeg", format: :jpeg, width: 4000, height: 3000}
+#=> {content_type: "image/jpeg", format: :jpeg, width: 4000, height: 3000,
+#    orientation: 1, display_width: 4000, display_height: 3000}
 ```
 
 A GIF source is read and probed like the others (`format: :gif`), but
@@ -31,7 +32,8 @@ the name does not say, and `:gif` is not a `format:` you can ask for.
 
 ```ruby
 Oximg.resize(source, destination, width: 0, height: 0,
-             quality: nil, format: nil, preset: nil)
+             quality: nil, format: nil, preset: nil,
+             icc: nil, auto_rotate: nil)
 ```
 
 The source is fitted within `width` x `height` and **never enlarged**. A
@@ -50,6 +52,12 @@ Oximg.resize("photo.jpg", "smaller.jpg", quality: 70)
 | `quality` | 1–100, default 80. JPEG quality |
 | `format` | `:jpg`, `:jpeg`, `:png`, `:webp`, `:avif`. Defaults to the destination's extension, else the source's own format |
 | `preset` | `:jpegli` (default — maximum quality per byte), `:fast`, `:small` |
+| `icc` | `:keep` or `:strip` the source's colour profile. Default: `OXIMG_ICC`, else keep |
+| `auto_rotate` | `false` keeps the stored orientation, `true` applies the EXIF one. Default: `OXIMG_AUTO_ROTATE`, else true |
+
+`icc` and `auto_rotate` apply to that call only, and win over the
+environment, so a threaded job runner can treat one image differently
+without touching `ENV`.
 
 `resize` returns the destination path and raises `Oximg::ProcessingError`
 on failure, carrying the binary's own message and exit status. Paths are
@@ -59,7 +67,7 @@ cannot be read as a flag.
 ## Stripping metadata
 
 ```ruby
-Oximg.strip(source, destination, icc: nil)
+Oximg.strip(source, destination, icc: nil, auto_rotate: nil, env: nil)
 ```
 
 Removes EXIF (GPS, camera, timestamps), XMP, IPTC and comments from a
@@ -71,10 +79,36 @@ still displays upright. `icc: :strip` also drops the colour profile.
 The default is `:keep`, or `OXIMG_ICC`. Dropping a CMYK JPEG's profile
 raises `Oximg::ProcessingError`, as do GIF and AVIF sources.
 
+`auto_rotate: true` turns a rotated JPEG upright instead, still without
+re-encoding: its compressed 8x8 blocks are moved, as `jpegtran
+-perfect` does, so the stored and displayed sizes agree for every
+reader, not only for ones that honor EXIF. That is only exact when the
+edges it moves are whole 8 or 16 px blocks (a phone's 4032x3024 is);
+otherwise, and for PNG and WebP, the file is stripped as without it,
+orientation kept. `Oximg.probe(destination)` tells which: orientation
+1, or the one kept. It costs a full entropy decode and encode, about
+170 ms for a 12 MP photo.
+
+## Knobs, per process or per call
+
 Everything the server tunes through `OXIMG_*` environment variables
 applies here too, and is validated the same fail-closed way: a typo'd
 knob is a startup error, never a silent default.
 
+To set one for a single call, pass `env:` to `resize` or `strip`:
+
+```ruby
+Oximg.resize("in.jpg", "out.jpg", width: 750, env: {"OXIMG_JPEG_PROGRESSIVE" => "0"})
+```
+
+Each call spawns its own process, and `env:` reaches that process
+only: `ENV` is never touched, so concurrent calls in a threaded job
+runner each get their own settings. Names must be in `Oximg::KNOBS`
+(the pipeline knobs; server settings such as `OXIMG_KEY` are refused),
+values are Strings or Integers, and `nil` unsets a name for that call.
+An unknown name raises `ArgumentError` before anything runs; a bad
+value is refused by the binary (`ProcessingError`, status 2).
+
 ## Probing
 
 ```ruby
@@ -83,12 +117,21 @@ Oximg.probe(Pathname("in.jpg"))                # also a path
 Oximg.probe(upload.tempfile)                   # anything with #path
 Oximg.probe(File.open("in.jpg", "rb"))         # an open File
 Oximg.probe(StringIO.new(bytes))               # an IO: bytes in memory
-#=> {content_type: "image/jpeg", format: :jpeg, width: 4000, height: 3000}
+#=> {content_type: "image/jpeg", format: :jpeg, width: 4000, height: 3000,
+#    orientation: 1, display_width: 4000, display_height: 3000}
 ```
 
-`probe` reads the header only and decodes no pixels. The dimensions are
-the stored ones, before any EXIF rotation. A String is always a path,
-so bytes already in memory go in as a `StringIO`. An open `File` is
+`probe` reads the header only and decodes no pixels. `width` and
+`height` are the stored ones, before any EXIF rotation. `orientation`
+is the EXIF value, 1..8 (1 when there is none or it is invalid, as
+`resize` reads it), and `display_width` / `display_height` are what a
+viewer honoring it shows: the axes exchanged for 5..8. A portrait
+phone photo stored 4000x3000 with orientation 6, as `strip` leaves it,
+lays out at 3000x4000. A WebP keeps its EXIF after the image data, so
+probing one that has it reads the whole source. An `oximg` executable
+older than this gem reports every source as orientation 1.
+
+A String is always a path, so bytes already in memory go in as a `StringIO`. An open `File` is
 read from its start, its position untouched, and it is the file you
 hold that is read, even if its name has since been replaced, renamed,
 or was relative to a directory the process has left. A closed or
@@ -138,8 +181,8 @@ Oximg.in_process_probe?  #=> true on a platform gem
 
 ```ruby
 Oximg.available?  #=> true
-Oximg.executable  #=> "/…/gems/oximg-0.18.0-arm64-darwin/exe/oximg"
-Oximg.version     #=> "0.18.0"   # the binary's version, not the gem's
+Oximg.executable  #=> "/…/gems/oximg-0.19.0-arm64-darwin/exe/oximg"
+Oximg.version     #=> "0.19.0"   # the binary's version, not the gem's
 ```
 
 `resize` shells out to that binary — one process per image, which is

data/lib/oximg/binary.rb

@@ -60,8 +60,14 @@ module Oximg
       # nothing in a filename can be interpreted as syntax. Returns
       # [stdout, stderr]; a non-zero exit raises with the binary's own
       # stderr, which already names what it refused.
-      def run(*args)
-        out, err, status = Open3.capture3(path, *args)
+      #
+      # +env+ is merged into the child's environment only (a nil value
+      # unsets that name there): one process per call means one call's
+      # knobs never reach another's, even across threads, and the
+      # parent's ENV is never touched. Validate it first; Oximg.resize
+      # and Oximg.strip do.
+      def run(*args, env: {})
+        out, err, status = Open3.capture3(env, path, *args)
         unless status.success?
           message = err.strip
           message = "oximg exited #{status.exitstatus}" if message.empty?

data/lib/oximg/native.rb

@@ -29,7 +29,7 @@ module Oximg
     BUNDLED = File.expand_path("native/#{LIBRARY}", __dir__)
 
     # The library's oximg_probe_abi_version this code was written for.
-    ABI_VERSION = 1
+    ABI_VERSION = 2
 
     # Statuses (ext/src/lib.rs).
     OK = 0
@@ -110,7 +110,8 @@ module Oximg
       end
 
       def call
-        dims = FFI::MemoryPointer.new(:uint64, 2)
+        # Stored width, stored height, orientation (ext/src/lib.rs).
+        dims = FFI::MemoryPointer.new(:uint64, 3)
         msg = FFI::MemoryPointer.new(:char, MESSAGE_BYTES)
         status = yield(dims, msg)
         return if status == READ
@@ -118,8 +119,8 @@ module Oximg
         text = msg.read_string.force_encoding(Encoding::UTF_8)
         raise ProcessingError.new(text, 1) unless status == OK
 
-        width, height = dims.read_array_of_uint64(2)
-        {content_type: text, format: CONTENT_TYPE_FORMATS[text], width: width, height: height}
+        width, height, orientation = dims.read_array_of_uint64(3)
+        Header.build(text, width, height, orientation)
       end
 
       # nil when there is no library to use. Memoized either way, so a

data/lib/oximg/version.rb

@@ -7,5 +7,5 @@ module Oximg
   # names a binary it does not carry. `Oximg.version` reports what the
   # resolved executable actually is, which can differ when it comes
   # from PATH.
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

data/lib/oximg.rb

@@ -45,9 +45,52 @@ module Oximg
   # mozjpeg's fast/small trade differently.
   PRESETS = %i[jpegli fast small].freeze
 
-  # What `strip` may do with an embedded colour profile.
+  # What `resize` and `strip` may do with an embedded colour profile.
   ICC_MODES = %i[keep strip].freeze
 
+  # The OXIMG_* pipeline knobs an +env:+ may set for one call. Pinned to
+  # the binary's own inventory (KNOBS in src/config.rs) by a test there,
+  # so a knob the binary gains or drops cannot drift from this list.
+  # Server-startup settings (OXIMG_KEY, OXIMG_BIND, ...) are not here:
+  # a one-shot never reads them.
+  KNOBS = %w[
+    OXIMG_TIMING
+    OXIMG_RESIZE
+    OXIMG_RESIZE_BACKEND
+    OXIMG_AUTO_ROTATE
+    OXIMG_ICC
+    OXIMG_DCT_MARGIN
+    OXIMG_LINEAR_SHRINK
+    OXIMG_JPEG_PROGRESSIVE
+    OXIMG_JPEG_SEQUENTIAL_PIXELS
+    OXIMG_JPEG_STREAMING_PIXELS
+    OXIMG_FLATTEN_BG
+    OXIMG_PNG_EFFORT
+    OXIMG_PNG_QUANTIZE
+    OXIMG_PNG_QUANTIZE_COLORS
+    OXIMG_WEBP_QUALITY
+    OXIMG_WEBP_EFFORT
+    OXIMG_WEBP_DECODE_THREADS
+    OXIMG_AVIF_QUALITY
+    OXIMG_AVIF_ALPHA_QUALITY
+    OXIMG_AVIF_SPEED
+    OXIMG_AVIF_DECODE_THREADS
+    OXIMG_MAX_SOURCE_BYTES
+    OXIMG_MAX_SRC_PIXELS
+    OXIMG_GIF_ANIMATION
+    OXIMG_MAX_ANIM_FRAMES
+    OXIMG_MAX_ANIM_WORK
+    OXIMG_ANIM_FRAME_STEP
+    OXIMG_MAX_DECODED_BYTES
+    OXIMG_LOG_DECODED_BYTES_ABOVE
+    OXIMG_UPSTREAM_CONNECT_TIMEOUT
+    OXIMG_UPSTREAM_TIMEOUT
+    OXIMG_GCS_ENDPOINT
+    OXIMG_S3_ENDPOINT
+    OXIMG_S3_PATH_STYLE
+    OXIMG_OVERLAP
+  ].freeze
+
   CONTENT_TYPE_FORMATS = {
     "image/jpeg" => :jpeg,
     "image/png" => :png,
@@ -59,8 +102,12 @@ module Oximg
   # The line `oximg probe` prints (src/cli.rs):
   #
   #   in.gif: image/gif 120x90 (10800 stored pixels), 3 frames, 1500ms, looping forever
+  #   in.jpg: image/jpeg 3000x2000 (6000000 stored pixels), orientation 6 (displayed 2000x3000)
   #
-  # The three fields the gem reports are pinned exactly. Everything after
+  # The three fields the gem reports are pinned exactly, and so is the
+  # orientation, which a non-upright source prints first after the
+  # comma (its absence means 1; the displayed size is derived here from
+  # it, not read). Everything after
   # the comma — the animation summary, printed for an animated source
   # only — is information the gem does not expose, and is deliberately
   # left unparsed rather than matched: a pattern that stopped at
@@ -70,7 +117,25 @@ module Oximg
   # a field missing, a continuation without the comma, or anything
   # printed before or after it. stderr is captured separately, so a
   # warning never lands here.
-  PROBE_LINE = /\A[^\n]*: (\S+) (\d+)x(\d+) \(\d+ stored pixels\)(?:,[^\n]*)?\n?\z/
+  PROBE_LINE = /\A[^\n]*: (\S+) (\d+)x(\d+) \(\d+ stored pixels\)(?:, orientation ([1-8]) \(displayed \d+x\d+\))?(?:,[^\n]*)?\n?\z/
+
+  # The hash probe returns, built in one place for both of its paths
+  # (the in-process library and the spawned executable).
+  module Header # :nodoc:
+    def self.build(content_type, width, height, orientation)
+      # Orientations 5-8 exchange the axes on display.
+      swapped = orientation >= 5
+      {
+        content_type: content_type,
+        format: CONTENT_TYPE_FORMATS[content_type],
+        width: width,
+        height: height,
+        orientation: orientation,
+        display_width: swapped ? height : width,
+        display_height: swapped ? width : height
+      }
+    end
+  end
 
   class << self
     # Absolute path to the executable in use; raises
@@ -106,10 +171,24 @@ module Oximg
     # The output format follows +format:+, else +destination+'s
     # extension, else the source's own format. Returns the destination
     # path.
-    def resize(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil)
+    #
+    # +icc:+ (:keep or :strip) and +auto_rotate:+ (true or false)
+    # override the binary's OXIMG_ICC and OXIMG_AUTO_ROTATE for this
+    # call only; nil leaves them to the environment (default: keep the
+    # profile, apply the EXIF orientation).
+    #
+    # +env:+ sets any other pipeline knob for this call only, e.g.
+    # <tt>env: {"OXIMG_JPEG_PROGRESSIVE" => "0"}</tt>: it reaches the
+    # one child process this call spawns, never ENV, so it is safe in a
+    # threaded job runner. Names must be in KNOBS; nil unsets a name
+    # for the call. The binary validates the values, fail-closed.
+    def resize(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil,
+      icc: nil, auto_rotate: nil, env: nil)
       output = expand(destination, "destination")
-      Binary.run(*resize_argv(source, output,
-        width: width, height: height, quality: quality, format: format, preset: preset))
+      argv = resize_argv(source, output,
+        width: width, height: height, quality: quality, format: format, preset: preset,
+        icc: icc, auto_rotate: auto_rotate)
+      Binary.run(*argv, env: knob_env(env))
       output
     end
 
@@ -123,23 +202,62 @@ module Oximg
     #
     # This is what <tt>saver(strip: true)</tt> / <tt>-strip</tt> did
     # under libvips or ImageMagick, minus the re-encode.
-    def strip(source, destination, icc: nil)
+    #
+    # <tt>auto_rotate: true</tt> turns a rotated JPEG upright instead,
+    # still without re-encoding: the compressed 8x8 blocks are moved
+    # (what <tt>jpegtran -perfect</tt> does), so its stored and displayed
+    # dimensions agree for every reader and no orientation tag is left.
+    # That is only exact when the edges it moves are whole 8 or 16 px
+    # blocks; otherwise, and for PNG and WebP, the orientation is kept
+    # as without it. Probe the destination to see which happened.
+    #
+    # +env:+ is per-call knobs, as for resize.
+    def strip(source, destination, icc: nil, auto_rotate: nil, env: nil)
       output = expand(destination, "destination")
-      Binary.run(*strip_argv(source, output, icc: icc))
+      argv = strip_argv(source, output, icc: icc, auto_rotate: auto_rotate)
+      Binary.run(*argv, env: knob_env(env))
       output
     end
 
+    # The child environment an +env:+ turns into: String names and
+    # values, each name a known knob. A typo raises here rather than
+    # being passed along and ignored, which is the same fail-closed
+    # promise the binary makes about the values. Public for the same
+    # reason as resize_argv.
+    def knob_env(env)
+      return {} if env.nil?
+      raise ArgumentError, "env must be a Hash, got #{env.inspect}" unless env.is_a?(Hash)
+
+      env.each_with_object({}) do |(name, value), out|
+        key = name.to_s
+        unless KNOBS.include?(key)
+          raise ArgumentError, "unknown knob #{name.inspect} in env (one of Oximg::KNOBS)"
+        end
+        unless value.nil? || value.is_a?(String) || value.is_a?(Integer)
+          raise ArgumentError, "#{key} must be a String, an Integer or nil, got #{value.inspect}"
+        end
+
+        out[key] = value&.to_s
+      end
+    end
+
     # The argv `strip` would run, minus the executable; public for the
     # same reason as resize_argv.
-    def strip_argv(source, destination, icc: nil)
+    def strip_argv(source, destination, icc: nil, auto_rotate: nil)
       argv = ["strip", expand(source, "source"), expand(destination, "destination")]
       argv.push("--icc", token(icc, ICC_MODES, "icc")) unless icc.nil?
+      # Off is strip's own default, so false adds nothing.
+      argv.push("--auto-rotate") if !auto_rotate.nil? && boolean(auto_rotate, "auto_rotate")
       argv
     end
 
     # Header-only inspection — no pixels are decoded. Returns
-    # <tt>{content_type:, format:, width:, height:}</tt>, where the
-    # dimensions are the stored ones (an EXIF rotation is not applied).
+    # <tt>{content_type:, format:, width:, height:, orientation:,
+    # display_width:, display_height:}</tt>. +width+ and +height+ are the
+    # stored ones; +orientation+ is the EXIF value, 1..8 (1 when there is
+    # none: the rule resize's auto-rotate applies and strip keeps), and
+    # the display size is what a viewer honoring it shows, with the axes
+    # exchanged for 5..8.
     #
     # +source+ is a path — a String, a Pathname, or anything with #path
     # such as a Tempfile — an open File, or a stream read from its
@@ -180,7 +298,8 @@ module Oximg
     # The argv `resize` would run, minus the executable. Public because
     # it is the honest way to see what a call turns into — and the way
     # to test that without a binary present.
-    def resize_argv(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil)
+    def resize_argv(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil,
+      icc: nil, auto_rotate: nil)
       argv = [
         "resize",
         expand(source, "source"),
@@ -191,6 +310,8 @@ module Oximg
       argv.push("-q", bounded(quality, "quality", 1, 100).to_s) unless quality.nil?
       argv.push("-f", token(format, FORMATS, "format")) unless format.nil?
       argv.push("--preset", token(preset, PRESETS, "preset")) unless preset.nil?
+      argv.push("--icc", token(icc, ICC_MODES, "icc")) unless icc.nil?
+      argv.push(boolean(auto_rotate, "auto_rotate") ? "--auto-rotate" : "--no-auto-rotate") unless auto_rotate.nil?
       argv
     end
 
@@ -278,12 +399,7 @@ module Oximg
       match = output.match(PROBE_LINE)
       raise ProcessingError, "unparsable probe output: #{output.inspect}" unless match
 
-      {
-        content_type: match[1],
-        format: CONTENT_TYPE_FORMATS[match[1]],
-        width: Integer(match[2]),
-        height: Integer(match[3])
-      }
+      Header.build(match[1], Integer(match[2]), Integer(match[3]), match[4] ? Integer(match[4]) : 1)
     end
 
     # Absolute paths throughout: a relative name beginning with "-"
@@ -319,6 +435,16 @@ module Oximg
       value
     end
 
+    # Strictly true or false: a truthy "0" or "false" read as true would
+    # rotate exactly the images the caller asked not to.
+    def boolean(value, name)
+      unless value == true || value == false
+        raise ArgumentError, "#{name} must be true or false, got #{value.inspect}"
+      end
+
+      value
+    end
+
     def token(value, allowed, name)
       token = value.to_s.downcase
       unless allowed.include?(token.to_sym)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oximg
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - oximg contributors