oximg 0.18.1-aarch64-linux-gnu → 0.20.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4d3cb7265d61a0d89d9851f6e0938951ca773603a02dcdc19ad5b8abf3d68de
-  data.tar.gz: 7cfa66df5ffac827bc245ddd387cc321054dabd6f97c97a13bf3e6b3e8ad50e5
+  metadata.gz: 18c7da6b14cbd76c0f403a39479b59e611e643a15f06a087012c42e7c86114f4
+  data.tar.gz: 0237a92850bd1259b6b1eb1182a2688d4c73ff2d2e3de14b1de6138212a80201
 SHA512:
-  metadata.gz: 1be6c2171b1eb682a4d495d3130eca32b7e856db393a5319aba109ada1f5d5cdd1e636ebf8072243894b58d6801849aa0cee30cb34d91adee4f0ff4593bfeb53
-  data.tar.gz: 5c2cf3b537d675e748cd62e3787a1008099ab2e16103ecdfee11d80a8e4b1535f81a5ebc3e3a7b5124410948042b230269f7ffae0dec5a75ea5f91770bfa6dbc
+  metadata.gz: cbcb4f7a737d982744d982a5cd489536964e394feae912e33166a659a4f8e4b49e311a229452b39f452f66da4e2fcfa21d65e549a354806b8e86b7331de6ccde
+  data.tar.gz: d4f54f32aabd7bd4dc7659bbe2b9f9462e04bc74f82e0c0092fed1af7881f63697af8d04abb328a1fe7da47af299c9ba8b351bd1a93de78220d6dc2d50ea0461

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
@@ -66,7 +67,7 @@ cannot be read as a flag.
 ## Stripping metadata
 
 ```ruby
-Oximg.strip(source, destination, icc: nil, env: nil)
+Oximg.strip(source, destination, icc: nil, auto_rotate: nil, env: nil)
 ```
 
 Removes EXIF (GPS, camera, timestamps), XMP, IPTC and comments from a
@@ -78,6 +79,38 @@ 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. It costs a full entropy decode and encode, about
+170 ms for a 12 MP photo.
+
+`strip` returns an `Oximg::Stripped`, the binary's own account of the
+run, so telling which happened needs no second read:
+
+```ruby
+result = Oximg.strip(upload, clean, icc: :keep, auto_rotate: true)
+result.upright?             # no orientation tag left: stored size is displayed size
+result.rotated?             # the pixels were turned upright
+result.orientation          #=> 6, the tag kept, or nil
+result.not_rotated&.code    #=> :unaligned_edges, :corrupt, :over_limit or :not_jpeg
+result.not_rotated&.message # for humans; the wording may change
+```
+
+`not_rotated` is nil unless `auto_rotate: true` left a rotated source
+tagged. The code is the contract (the table is in
+[docs/features/paths.md](../../docs/features/paths.md)), so count
+fallbacks by it. The result also stands in for the destination path
+`strip` used to return: `to_s`, `to_path` and `to_str` are the path and
+it compares equal to that String, so `File.size(Oximg.strip(...))`
+still works. With an `oximg` older than 0.20, which has no `strip
+--json`, the gem reads the summary line that binary prints instead:
+`orientation` and `rotated?` are still right, `removed` is nil, and
+the code is `:unknown` beside the binary's own reason.
+
 ## Knobs, per process or per call
 
 Everything the server tunes through `OXIMG_*` environment variables
@@ -106,12 +139,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
@@ -161,8 +203,8 @@ Oximg.in_process_probe?  #=> true on a platform gem
 
 ```ruby
 Oximg.available?  #=> true
-Oximg.executable  #=> "/…/gems/oximg-0.18.1-arm64-darwin/exe/oximg"
-Oximg.version     #=> "0.18.1"   # the binary's version, not the gem's
+Oximg.executable  #=> "/…/gems/oximg-0.20.0-arm64-darwin/exe/oximg"
+Oximg.version     #=> "0.20.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

@@ -76,11 +76,23 @@ module Oximg
         [out, err]
       end
 
+      # True once the executable refused `strip --json` (an oximg older
+      # than 0.20): Oximg.strip then runs without it and reads the
+      # summary line that binary prints. Memoized per executable, like
+      # the path, so a process
+      # pays the refused spawn once.
+      attr_accessor :legacy_strip
+
+      def legacy_strip?
+        @legacy_strip == true
+      end
+
       # Resets the memoized lookup. For tests, and for a process that
       # changes OXIMG_BIN after boot.
       def reset!
         @path = nil
         @version = nil
+        @legacy_strip = nil
       end
 
       private

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Oximg
+  # What Oximg.strip did: where it wrote, and whether the output
+  # displays upright. Built from <tt>oximg strip --json</tt>, so it is
+  # the binary's own account of the run, not a second read of the file.
+  #
+  # It stands in for the destination path Oximg.strip returned before
+  # (#176): #to_s, #to_path and #to_str are the path, and it compares
+  # equal to that path as a String, so
+  # <tt>File.size(Oximg.strip(...))</tt>, <tt>File.join</tt> and
+  # <tt>assert_equal out, Oximg.strip(...)</tt> keep working.
+  #
+  #   result = Oximg.strip(upload, clean, auto_rotate: true)
+  #   result.rotated?                #=> false
+  #   result.orientation             #=> 6, the tag the output keeps
+  #   result.not_rotated.code        #=> :unaligned_edges
+  #   result.not_rotated.message     #=> "1601x1203 does not divide into ..."
+  class Stripped
+    # Why <tt>auto_rotate: true</tt> left a rotated source tagged.
+    # +code+ is the contract, a Symbol from NOT_ROTATED_CODES (or
+    # :unknown, below); +message+ is for humans and may change.
+    NotRotated = Data.define(:code, :message)
+
+    # The binary's codes (docs/features/paths.md). A code missing here
+    # still comes through, as its Symbol: a newer binary may add one.
+    NOT_ROTATED_CODES = %i[unaligned_edges corrupt over_limit not_jpeg].freeze
+
+    # The destination, absolute.
+    attr_reader :path
+    # The output's content type ("image/jpeg", ...).
+    attr_reader :content_type
+    # Output size in bytes.
+    attr_reader :bytes
+    # What was dropped: <tt>[{name: "APP1 Exif", count: 1, bytes: 1204}, ...]</tt>;
+    # nil from an oximg older than 0.20.
+    attr_reader :removed
+    # The orientation tag the output keeps, 2..8, or nil when it
+    # displays as stored (upright, untagged, or rotated upright).
+    attr_reader :orientation
+    # The orientation turned into the pixels, 2..8, or nil.
+    attr_reader :rotated
+    # A NotRotated, or nil unless auto_rotate left a rotated source
+    # tagged. From an oximg older than 0.20, which has no --json and
+    # gives the reason only as a sentence, the code is :unknown.
+    attr_reader :not_rotated
+
+    # From the hash <tt>oximg strip --json</tt> prints.
+    def self.from_json(path, report)
+      why = report["not_rotated"]
+      new(
+        path: path,
+        content_type: report["content_type"],
+        bytes: report["bytes"],
+        removed: report["removed"]&.map { |r| {name: r["name"], count: r["count"], bytes: r["bytes"]} },
+        orientation: report["orientation"],
+        rotated: report["rotated"],
+        not_rotated: why && NotRotated.new(code: why["code"].to_sym, message: why["message"])
+      )
+    end
+
+    def initialize(path:, bytes:, content_type:, orientation:, rotated:, not_rotated:, removed: nil)
+      @path = path
+      @content_type = content_type
+      @bytes = bytes
+      @removed = removed
+      @orientation = orientation
+      @rotated = rotated
+      @not_rotated = not_rotated
+      freeze
+    end
+
+    # True when the pixels were turned upright (auto_rotate).
+    def rotated?
+      !@rotated.nil?
+    end
+
+    # True when the output displays as stored: no orientation tag left,
+    # so its stored width and height are the displayed ones.
+    def upright?
+      @orientation.nil?
+    end
+
+    def to_s
+      @path
+    end
+    alias_method :to_path, :to_s
+    alias_method :to_str, :to_s
+
+    # Equal to another result for the same run, or to the destination
+    # path as a String (String#== defers here for anything with to_str).
+    def ==(other)
+      case other
+      when Stripped then to_h == other.to_h
+      when String then @path == other
+      else false
+      end
+    end
+
+    def to_h
+      {path: @path, content_type: @content_type, bytes: @bytes, removed: @removed,
+       orientation: @orientation, rotated: @rotated, not_rotated: @not_rotated&.to_h}
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@path} #{to_h.except(:path).compact.inspect}>"
+    end
+  end
+end

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.1"
+  VERSION = "0.20.0"
 end

data/lib/oximg.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "fcntl"
+require "json"
 require "tempfile"
 require_relative "oximg/version"
 require_relative "oximg/binary"
 require_relative "oximg/native"
+require_relative "oximg/stripped"
 
 # Ruby bindings for oximg (https://github.com/oximg/oximg):
 # high-performance image compression and resizing, in-process work for a
@@ -102,8 +104,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
@@ -113,7 +119,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
@@ -176,17 +200,49 @@ module Oximg
     # a rotated photo keeps only its EXIF orientation, so it still
     # displays upright. +icc:+ is :keep or :strip (default: the
     # binary's OXIMG_ICC, else keep); dropping a CMYK JPEG's profile is
-    # refused with a ProcessingError. Returns the destination path.
+    # refused with a ProcessingError.
+    #
+    # Returns an Oximg::Stripped: the binary's own account of the run
+    # (orientation kept, rotated?, not_rotated with a stable code). It
+    # stands in for the destination path this returned before:
+    # #to_path, #to_str and == against a String are the path.
     #
     # This is what <tt>saver(strip: true)</tt> / <tt>-strip</tt> did
     # under libvips or ImageMagick, minus the re-encode.
     #
+    # <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, and the result says why:
+    #
+    #   result = Oximg.strip(upload, clean, auto_rotate: true)
+    #   unless result.upright?
+    #     result.not_rotated.code  #=> :unaligned_edges, :corrupt, :over_limit, :not_jpeg
+    #   end
+    #
     # +env:+ is per-call knobs, as for resize.
-    def strip(source, destination, icc: nil, env: nil)
+    def strip(source, destination, icc: nil, auto_rotate: nil, env: nil)
       output = expand(destination, "destination")
-      argv = strip_argv(source, output, icc: icc)
-      Binary.run(*argv, env: knob_env(env))
-      output
+      argv = strip_argv(source, output, icc: icc, auto_rotate: auto_rotate)
+      child_env = knob_env(env)
+      unless Binary.legacy_strip?
+        begin
+          out, = Binary.run(*argv, "--json", env: child_env)
+          return Stripped.from_json(output, JSON.parse(out))
+        rescue ProcessingError => e
+          # An oximg older than 0.20 refuses the flag at parse time,
+          # before it reads or writes anything: remember that, and run
+          # the strip it does know.
+          raise unless e.status == 2 && e.message.include?('unknown option "--json"')
+
+          Binary.legacy_strip = true
+        end
+      end
+      _, err = Binary.run(*argv, env: child_env)
+      legacy_stripped(output, err)
     end
 
     # The child environment an +env:+ turns into: String names and
@@ -211,17 +267,24 @@ module Oximg
       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)
+    # The argv `strip` would run, minus the executable and the --json it
+    # adds to read the outcome; public for the same reason as
+    # resize_argv.
+    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
@@ -363,12 +426,31 @@ 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
+
+    # The summary every oximg since 0.18 ends a strip with, after
+    # "oximg: wrote <out> " (src/cli.rs). Those releases are frozen, so
+    # their wording is a fixed format here, though it is not a contract
+    # for later ones (they have --json). Removed block names are JPEG
+    # segment names or 4-byte chunk types, so the tail is unambiguous.
+    LEGACY_STRIP_SUMMARY = /\A\((\d+) bytes, ([^;\s]+); (.*?)(?:; kept orientation ([2-8])(?:, not rotated: (.*))?|; rotated orientation ([2-8]) upright)?\)\z/m
+
+    # The result from an oximg without --json, read from that summary
+    # rather than by probing: probe stops looking for the orientation
+    # after 1 MiB of metadata and needs a header libjpeg reads, where
+    # strip does neither. The reason a rotation was not made has no
+    # code before 0.20, so it is :unknown, with the binary's sentence.
+    def legacy_stripped(output, stderr)
+      prefix = "oximg: wrote #{output} "
+      line = stderr.lines.map(&:chomp).reverse.find { |l| l.start_with?(prefix) }
+      match = line && line.delete_prefix(prefix).match(LEGACY_STRIP_SUMMARY)
+      raise ProcessingError, "unparsable strip summary: #{stderr.strip.inspect}" unless match
+
+      kept = match[4] && Integer(match[4])
+      why = match[5] && Stripped::NotRotated.new(code: :unknown, message: match[5])
+      Stripped.new(path: output, bytes: Integer(match[1]), content_type: match[2],
+        orientation: kept, rotated: match[6] && Integer(match[6]), not_rotated: why)
     end
 
     # Absolute paths throughout: a relative name beginning with "-"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oximg
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.20.0
 platform: aarch64-linux-gnu
 authors:
 - oximg contributors
@@ -37,6 +37,7 @@ files:
 - lib/oximg/binary.rb
 - lib/oximg/native.rb
 - lib/oximg/native/liboximg_probe.so
+- lib/oximg/stripped.rb
 - lib/oximg/version.rb
 homepage: https://github.com/oximg/oximg
 licenses: