kithe 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2442db92e7c22e24d345483d17020d6025c42e4b24b9fe2dbdf0d9ad8625309e
-  data.tar.gz: 8d15649504ce721fd2c8b5ee1dc8a7f64b9486e64e3f4f3b5a983ce8d295e5ed
+  metadata.gz: c501b48a3f6f517f1fd6906a357aba0004717c94f8b40bd20996efd696bcaff2
+  data.tar.gz: b29ffa367832a02a78a94641c6bf37c5bac03cda23c7db80325806bcc151d3f5
 SHA512:
-  metadata.gz: 788253f8998adb2a6cd1799b4b124d7e301737477a002c6541f7de5b33f8c6744b818d8aee40de67e3eea316ca6be3411f28a6a2c1951a2ca921416e810cfc45
-  data.tar.gz: dac26e54710bef716c27833bf822763fc54f784a009835ee43d71fe7e39e63f315cce90dbd6b9a34af54e7ec5ab604b9bf9d749a5450bb94fdc4ebbcdcc4cbf6
+  metadata.gz: a1e75a34696381c7564e2f2484a991dff65a97e2d7dde3d4132ecb48eb5ba5c3967d665241dd1b4c9de82bc8a205f42238fbe2c410ad5019c878851e4e35c938
+  data.tar.gz: c68de2016880101aef6ed61dcf0752e62a68dc79ac9633aa9b74ad478e5daa2af1f49a94a4445d77d0e1c13a303b722eb6ec6a74affbacd59d301b7d77811dd0

data/app/characterization/kithe/exiftool_characterization/result.rb

@@ -0,0 +1,111 @@
+module Kithe
+  class ExiftoolCharacterization
+    # Retrieve known info out of exiftool results.
+    #
+    # It can be really tricky to get this reliably from arbitrary files/cameras, there's a lot of variety
+    # in EXIF/XMP/etc use.
+    #
+    # We also normalize exiftool validation warnings in #exiftool_validation_warnings, they're
+    # kind of a pain to extract
+    #
+    # We do this right now for our use cases, in terms of what data we want, and what is actually
+    # found in ours. PR's welcome to generalize!
+    #
+    # In the future, we might have different result classes for different versions of exiftool or ways
+    # of calling it, it's best to instantiate this with:
+    #
+    #     result = Kithe::ExiftoolChacterization.presenter(some_result_hash)
+    #     result.camera_model
+    #     result.exiftool_validation_warnings
+    class Result
+      attr_reader :result
+
+      def initialize(hash)
+        @result = hash || {}
+      end
+
+      def exiftool_version
+        result["ExifTool:ExifToolVersion"]
+      end
+
+      def exif_tool_args
+        result["Kithe:CliArgs"]
+      end
+
+      def bits_per_sample
+        result["EXIF:BitsPerSample"]
+      end
+
+      def photometric_interpretation
+        result["EXIF:PhotometricInterpretation"]
+      end
+
+      def compression
+        result["EXIF:Compression"]
+      end
+
+      def camera_make
+        result["EXIF:Make"]
+      end
+
+      def camera_model
+        result["EXIF:Model"]
+      end
+
+      def dpi
+        # only "dpi" if unit is inches
+        return nil unless result["EXIF:ResolutionUnit"] == "inches"
+
+        if result["EXIF:XResolution"] == result["EXIF:YResolution"]
+          result["EXIF:XResolution"]
+        else
+          # for now, we bail on complicated case
+          nil
+        end
+      end
+
+      def software
+        result["XMP:CreatorTool"]
+      end
+
+      def camera_lens
+        result["XMP:Lens"]
+      end
+
+      def shutter_speed
+        result["Composite:ShutterSpeed"]
+      end
+
+      def camera_iso
+        result["EXIF:ISO"]
+      end
+
+      def icc_profile_name
+        result["ICC_Profile:ProfileDescription"]
+      end
+
+      # We look in a few places, and we only return date not time because
+      # getting timezone info is unusual, and it's all we need right now.
+      #
+      # @return Date
+      def creation_date
+        str_date = result["EXIF:DateTimeOriginal"] || result["EXIF:DateTimeOriginal"] || result["XMP:DateCreated"]
+        return nil unless str_date
+
+        Date.strptime(str_date, '%Y:%m:%d')
+      rescue Date::Error
+        return nil
+      end
+
+      # Multiple exiftool validation warnings are annoyingly in keys `ExifTool:Warning`,
+      # `ExifTool:Copy1:Warning`, `ExifTool:Copy2:Warning`, etc. We provide a convenience
+      # method to fetch em all and return them as an array.
+      #
+      # @return Array[String]
+      def exiftool_validation_warnings
+        @exiftool_validation_warnings ||= result.slice( *result.keys.grep(/ExifTool(:Copy\d+):Warning/) ).values
+      end
+
+    end
+  end
+end

data/app/characterization/kithe/exiftool_characterization.rb

@@ -0,0 +1,97 @@
+require 'tty/command'
+require 'json'
+
+module Kithe
+  # Can run an installed `exiftool` command line, and return results as a JSON hash. exiftool
+  # needs to be installed.  This version developed against exiftool 12.60
+  #
+  # Results are extended with exact command-line arguments given to exiftool in key `Kithe:CliArgs` as
+  # an array of Strings.
+  #
+  # We ask exiftool to check for validation errors, and output them too, although they are
+  # output in exiftool json with kind of inconvenient key patterns.
+  #
+  # Results can be parsed with accompanying Kithe::Exiftool::Characterization::Result class --
+  # in future, if different versions or invocations of exiftool produce different hash results,
+  # we can provide different Results parsers, and a switching method to choose right one
+  # based on exiftool version and args embedded in results.
+  #
+  # In cases of errors where exiftool returns errors in hash, hash is still returned, no raise!
+  #
+  # @example
+  #     hash = Kithe::ExiftoolCharacterization.new.call(file_path)
+  #
+  #     presenter = Kithe::ExiftoolCharacterization.presenter_for(hash)
+  #     presenter.bits_per_sample
+  #     presenter.make
+  #     presenter.model
+  #     presenter.exiftool_validation_warnings # Array of strings
+  #
+  # * exiftool needs to be installed
+  #
+  # * Runs with -G0:4 so keys might look like `EXIF:BitsPerSample` or in some cases
+  #   have a `Copy1` or `Copy2` in there, like `XMP:Copy1:Make`.  The `g4` arg
+  #   results in that `Copy1`, necessary to get multiple validation warnings
+  #   all included, but a bit annoying when it puts in extraneous `Copy1` for singular
+  #   results sometimes too.
+  class ExiftoolCharacterization
+    class_attribute :exiftool_command, default: "exiftool"
+
+    attr_accessor :file_path
+
+    # Returns a nice presenter object with methods that get out metadata
+    # we are interested in -- in the future, might return differnet classes
+    # for specific data, looking at `Exiftool:Version` or `Kithe:CliArgs`
+    # keys to switch.
+    #
+    # @param hash [Hash] a hash returned by ExiftoolCharacterization.call
+    # @return a presenter
+    def self.presenter_for(hash)
+      Kithe::ExiftoolCharacterization::Result.new(hash)
+    end
+
+    # @param file_path [String] path to a local file
+    # @returns Hash
+    def call(file_path)
+      cmd = TTY::Command.new(printer: :null)
+
+      exiftool_args = [
+        "-All",       # all tags
+        "--File:All",  # EXCEPT not "File" group tags,
+        "-duplicates", # include duplicate values
+        "-validate",   # include some validation errors
+        "-json",       # json output
+
+        # with exif group names as key prefixes eg "ICC_Profile:ProfileDescription"
+        # But also with weird `:Copy1`, `:Copy2` appended for multiples, which we need
+        # for `ExifTool:Warning` from `-validate`, to get all of them, that's what the :4 does.
+        #
+        # https://exiftool.org/forum/index.php?topic=15194.0
+        "-G0:4"
+      ]
+
+      # exiftool may return a non-zero exit for a corrupt file -- we don't want to raise,
+      # it's still usually returning a nice json hash with error message, just store that
+      # in the exiftool_result area anyway!
+      result = cmd.run!(
+        exiftool_command,
+        *exiftool_args,
+        file_path.to_s)
+
+
+      if result.out.blank? && result.failed?
+        raise ArgumentError.new("#{self.class}: #{result.err}")
+      end
+
+      # Returns an array of hashes
+      # decimal_class: String needed so exiftool version number like `12.60` doesn't
+      # wind up truncated to 12.6 as a ruby float!
+      result_hash = JSON.parse(result.out, decimal_class: String).first
+
+      # Let's add our invocation options, as a record
+      result_hash["Kithe:CliArgs"] = exiftool_args
+
+      result_hash
+    end
+  end
+end

data/lib/kithe/version.rb

@@ -1,3 +1,3 @@
 module Kithe
-  VERSION = '2.10.0'
+  VERSION = '2.11.0'
 end

data/lib/shrine/plugins/kithe_promotion_callbacks.rb

@@ -23,6 +23,27 @@ class Shrine
     # Because getting this right required some shuffling around of where the wrapping happened, it
     # was convenient and avoided confusion to isolate wrapping in a class method that can be used
     # anywhere, and only depends on args passed in, no implicit state anywhere.
+    #
+    # ## Sharing same tempfile for processing
+    #
+    # If we have maybe multiple before_promotion hooks that all need an on-disk file,
+    # PLUS maybe multiple `add_metadata` hooks that need an on-desk file -- we
+    # ABSOLUTELY do NOT each to do a separate copy/download from possibly remote cloud source!
+    #
+    # The default shrine implementation using Down::ChunkedIO may avoid that (not necessarily
+    # as a contract!), BUT still makes multiple local copies, which can still be a performance issue
+    # for large files.
+    #
+    # The solution is the [Shrine tempfile plugin](https://shrinerb.com/docs/plugins/tempfile), which
+    # requires the UploadedFile to be opened *around* all uses of `Shrine.with_file`.
+    #
+    # We include some pretty kludgey code to make this a thing.
+    #
+    # To take advantage of it, you DO need to add `Shrine.plugin :tempfile` in your app, we don't
+    # want to force this global on apps!
+    #
+    # Note *after_promotion* hooks won't share the common tempfile, since the UploadedFile location
+    # has been changed from the one we opened!
     class KithePromotionCallbacks
       def self.load_dependencies(uploader, *)
         uploader.plugin :kithe_promotion_directives
@@ -36,7 +57,20 @@ class Shrine
       #        promotion_logic # sometimes `super`
       #     end
       #
+      # This also contains some pretty kludgey code to open the underlying Shrine::UploadedFile
+      # *around* the before_promotion hooks AND promotion.  When combined with Shrine tempfile plugin,
+      # this means all `before_promotion` hooks and `add_metadata` hooks can use `Shrine.with_file`
+      # to get the
       def self.with_promotion_callbacks(model)
+        # only if Shrine::UploadedFile isn't *already* open we definitely want
+        # to open it and keep it open -- so WITH Shrine tempfile plugin, we can have
+        # various hooks sharing the same tempfile instead of making multiple copies.
+        unless model.file_attacher.file.opened?
+          model.file_attacher.file.open
+          self_opened_file = model.file_attacher.file
+        end
+
+
         # If callbacks haven't been skipped, and we have a model that implements
         # callbacks, wrap yield in callbacks.
         #
@@ -44,12 +78,19 @@ class Shrine
         if (  !model.file_attacher.promotion_directives["skip_callbacks"] &&
               model &&
               model.class.respond_to?(:_promotion_callbacks) )
+
           model.run_callbacks(:promotion) do
             yield
           end
+
         else
           yield
         end
+      ensure
+        # only if we DID open the Shrine::UploadedFile ourselves, for the purpose of
+        # using a common tempfile with Shrine tempfile plugin,
+        # make sure to clean up after ourselves by closing it.
+        self_opened_file.close if self_opened_file && self_opened_file.opened?
       end
 
       module AttacherMethods

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kithe
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Jonathan Rochkind
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-02 00:00:00.000000000 Z
+date: 2023-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -345,6 +345,8 @@ files:
 - README.md
 - Rakefile
 - app/assets/config/kithe_manifest.js
+- app/characterization/kithe/exiftool_characterization.rb
+- app/characterization/kithe/exiftool_characterization/result.rb
 - app/characterization/kithe/ffprobe_characterization.rb
 - app/derivative_transformers/kithe/ffmpeg_extract_jpg.rb
 - app/derivative_transformers/kithe/ffmpeg_transformer.rb