image_processing 1.2.0 → 1.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39c52030a178edeef33439eb70807d86935b1e05bbf250d0f30aa9a4947f6dea
-  data.tar.gz: 60c936577febb87380de300024a8f4517ae9dafed394d74fe7b0f78ab04efd7f
+  metadata.gz: ec4b4776480756b2721185419de81f228e5ca927b4bd3077fb4c0a5dcafef15f
+  data.tar.gz: d40b8822b6a7b2b5e1bad182099f7e3b23b25d0cdd6b61b1afa3154b665e76a6
 SHA512:
-  metadata.gz: 9bc68c91084d44b3052a47ac332d21840965537163b541ef09cd662d729c26e152b3e588f97fd954a13aaae0a5a645be86389a79308de4eee154feb7fed95baa
-  data.tar.gz: 4c026c8eb9cc4dfa537ef3f0f86b460a8dc0a13134fe441604483b6a4b1afd1048911b499673807fac82f7a15c37773e27fad1dd2d049f8e8adedd5204166923
+  metadata.gz: 77cff245646f56f409d4c1d006d26cee819d11cc9c263b88d86bafb6e480ac691240bfa17542bf9c578891056355d53f63fefddfa1f3eb801e3ddeea20666ae3
+  data.tar.gz: bf3f39c4204d7dcbb6382596a4a8850f8c7d22fee94e8ed77a1782a58bd1f370448268bb4e74028e429ee2e7c6156613b1022f5465faf6d30ab01833751c4df9

data/CHANGELOG.md

@@ -1,112 +1,204 @@
+## 1.12.1 (2020-11-06)
+
+* Fix format fallback for files ending with a dot on Ruby 2.7+ (@coding-chimp)
+
+## 1.12.0 (2020-09-20)
+
+* Add instrumentation support via `#instrumenter` (@janko)
+
+## 1.11.0 (2020-05-17)
+
+* [minimagick] Handle destination format having no file extension (@janko)
+
+* [minimagick] Disable sharpening on `#resize_*` operators by default (@flori)
+
+* [minimagick] Add `#crop` which accepts `left, top, width, height` arguments (@janko)
+
+## 1.10.3 (2020-01-12)
+
+* [vips] Fix auto-rotation not working in certain cases on libvips 8.9.0 (@janko)
+
+## 1.10.2 (2020-01-11)
+
+* Fix Ruby 2.7 warnings for separation of positional and keyword arguments (@kamipo, @janko)
+
+## 1.10.1 (2020-01-07)
+
+* [vips] Fix compatibility with ruby-vips 2.0.17+ (@janko)
+
+## 1.10.0 (2019-12-18)
+
+* [minimagick] Add `:loader` option for explicitly setting input file type (@janko)
+
+## 1.9.3 (2019-08-11)
+
+* [vips] Use integer precision when sharpening for better quality (@metaskills)
+
+## 1.9.2 (2019-07-22)
+
+* Bump `mini_magick` dependency to `>= 4.9.5` (@chioreandan)
+
+## 1.9.1 (2019-07-20)
+
+* Bring back support for MRI 2.3 (@janko)
+
+## 1.9.0 (2019-04-09)
+
+* Drop support for MRI 2.2 and 2.3 (@janko)
+
+* [vips] Allow forcing a specific loader or saver (@janko)
+
+## 1.8.0 (2019-02-25)
+
+* [vips] Perform resize-on-load when possible, significantly improving resizing speed (@janko)
+
+## 1.7.1 (2018-09-27)
+
+* [vips] Make `#remove` that's used for removing image metadata chainable (@janko)
+
+## 1.7.0 (2018-09-20)
+
+* [vips] `#rotate` now always calls `vips_similarity()` and forwards all options to it (@janko)
+
+## 1.6.0 (2018-07-13)
+
+* [vips] In `#composite` accept `:offset` option for the position of the overlay image (@janko)
+
+* [vips] In `#composite` accept `:gravity` option for the direction of the overlay image (@janko)
+
+* [vips] In `#composite` accept blend mode as an optional `:mode` parameter which defaults to `:over` (@janko)
+
+* [minimagick] In `#composite` rename `:compose` option to `:mode` (@janko)
+
+* [minimagick] In `#composite` replace `:geometry` option with `:offset` which accepts an array (@janko)
+
+## 1.5.0 (2018-07-10)
+
+* [minimagick, vips] Add `#composite` method (@janko)
+
+* [core] Allow operations to accept blocks (janko-m)
+
+## 1.4.0 (2018-06-14)
+
+* [minimagick] Accept RGB(A) arrays for color names for `:background` (@janko)
+
+* [minimagick] Don't add empty `-background` option in `#rotate` when `:background` is not given (@janko)
+
+* [vips] Modify `#rotate` to accept only `:background` and not other `vips_similarity()` options (@janko)
+
+## 1.3.0 (2018-06-13)
+
+* [minimagick, vips] Add `#rotate` method (@janko)
+
+* [vips] Use native `vips_image_hasalpha()` and `vips_addalpha()` functions in `#resize_and_pad` (@janko)
+
 ## 1.2.0 (2018-04-18)
 
-* [minimagick] Allow appending "+" operators in `#loader` and `#saver` using the value `false` (@janko-m)
+* [minimagick] Allow appending "+" operators in `#loader` and `#saver` using the value `false` (@janko)
 
-* [core] Fix `#apply` not accepting a Hash as an argument (@janko-m)
+* [core] Fix `#apply` not accepting a Hash as an argument (@janko)
 
-* [core] Allow sending any builder commands via `#apply`, not just operations (@janko-m)
+* [core] Allow sending any builder commands via `#apply`, not just operations (@janko)
 
-* [minimagick] Add `#define` as a wrapper around `-define` (@janko-m)
+* [minimagick] Add `#define` as a wrapper around `-define` (@janko)
 
 ## 1.1.0 (2018-04-05)
 
 * [minimagick] Disallow splitting multi-layer images into multiple single-layer
   images by default to avoid unexpected behaviour, but can be re-enabled with
-  the `:allow_splitting` saver option (@janko-m)
+  the `:allow_splitting` saver option (@janko)
 
-* [core] Add `#apply` for applying a list of operations (@janko-m)
+* [core] Add `#apply` for applying a list of operations (@janko)
 
 ## 1.0.0 (2018-04-04)
 
-* Depend on `mini_magick` and `ruby-vips` gems (@janko-m, @mokolabs)
+* Depend on `mini_magick` and `ruby-vips` gems (@janko, @mokolabs)
 
-* [minimagick] Remove deprecated API in favor of the chainable API (@janko-m)
+* [minimagick] Remove deprecated API in favor of the chainable API (@janko)
 
-* [core] Rename `Builder#default_options` to `Builder#options` (@janko-m)
+* [core] Rename `Builder#default_options` to `Builder#options` (@janko)
 
-* [minimagick] Remove `:fail` loader option in favor of the existing `:regard_warnings` (@janko-m)
+* [minimagick] Remove `:fail` loader option in favor of the existing `:regard_warnings` (@janko)
 
-* [vips, minimagick] Don't fail on warnings when loading the image (@janko-m)
+* [vips, minimagick] Don't fail on warnings when loading the image (@janko)
 
-* [vips] Don't apply `Vips::Image#autorot` if `:autorotate` loader option was passed in (@janko-m)
+* [vips] Don't apply `Vips::Image#autorot` if `:autorotate` loader option was passed in (@janko)
 
-* [minimagick] Allow using value `nil` to add ImageMagick options that don't have a value (@janko-m)
+* [minimagick] Allow using value `nil` to add ImageMagick options that don't have a value (@janko)
 
-* [vips] Accept `:quality` saver option as an alias to `:Q` (@janko-m)
+* [vips] Accept `:quality` saver option as an alias to `:Q` (@janko)
 
-* [minimagick] Automatically sharpen thumbnails after resizing (@janko-m, @mokolabs)
+* [minimagick] Automatically sharpen thumbnails after resizing (@janko, @mokolabs)
 
-* [vips] Automatically sharpen thumbnails after resizing (@janko-m, @mokolabs)
+* [vips] Automatically sharpen thumbnails after resizing (@janko, @mokolabs)
 
 ## 0.11.2 (2018-03-31)
 
-* [minimagick] Avoid `#resize_*` operations stripping data by switching back to `-resize` (@janko-m)
-
-* [core] Make sure an empty destination file doesn't remain on processing errors when `:destination` is used (@janko-m)
+* [minimagick] Avoid `#resize_*` operations stripping data by switching back to `-resize` (@janko)
 
-* [vips] Fix `:alpha` not correctly adding alpha for certain types of images (@janko-m)
+* [core] Make sure an empty destination file doesn't remain on processing errors when `:destination` is used (@janko)
 
-* [minimagick] Drop official support for GraphicsMagick (@janko-m)
+* [vips] Fix `:alpha` not correctly adding alpha for certain types of images (@janko)
 
 ## 0.11.1 (2018-03-27)
 
-* [minimagick] Rename `#limit` to `#limits` to still allow adding `-limit` arguments directly (@janko-m)
+* [minimagick] Rename `#limit` to `#limits` to still allow adding `-limit` arguments directly (@janko)
 
 ## 0.11.0 (2018-03-27)
 
-* [minimagick] Fix broken deprecated `#convert` (@janko-m)
+* [minimagick] Fix broken deprecated `#convert` (@janko)
 
-* [minimagick] Add `#limit` for specifying resource limits using `-limit` (@janko-m)
+* [minimagick] Add `#limit` for specifying resource limits using `-limit` (@janko)
 
-* [minimagick] Use `-thumbnail` instead of `-resize` in `#resize_*` methods (@janko-m)
+* [minimagick] Use `-thumbnail` instead of `-resize` in `#resize_*` methods (@janko)
 
-* [minimagick] Add loader and saver options (@janko-m)
+* [minimagick] Add loader and saver options (@janko)
 
 ## 0.10.3 (2018-03-24)
 
-* [minimagick] Fix bang methods in deprecated API calling nondestructive versions (@janko-m)
+* [minimagick] Fix bang methods in deprecated API calling nondestructive versions (@janko)
 
 ## 0.10.2 (2018-03-22)
 
-* [minimagick] Add back default offset arguments to deprecated `#crop` (@janko-m)
+* [minimagick] Add back default offset arguments to deprecated `#crop` (@janko)
 
 ## 0.10.1 (2018-03-22)
 
-* [minimagick] Don't print deprecation warning for old API twice when IO objects are used (@janko-m)
+* [minimagick] Don't print deprecation warning for old API twice when IO objects are used (@janko)
 
 ## 0.10.0 (2018-03-21)
 
-* [minimagick] Rewrite MiniMagick module to use the chainable API (@janko-m)
+* [minimagick] Rewrite MiniMagick module to use the chainable API (@janko)
 
-* [minimagick] Deprecate the old API (@janko-m)
+* [minimagick] Deprecate the old API (@janko)
 
-* [minimagick] Raise an exception on processing warnings (@janko-m)
+* [minimagick] Raise an exception on processing warnings (@janko)
 
-* [minimagick] Speed up `.valid_image?` by an order of magnitude (@janko-m)
+* [minimagick] Speed up `.valid_image?` by an order of magnitude (@janko)
 
-* [minimagick] Don't accept arbitrary IO object anymore (@janko-m)
+* [minimagick] Don't accept arbitrary IO object anymore (@janko)
 
-* [minimagick] Removed unnecessary `#crop` and `#resample` macros (@janko-m)
+* [minimagick] Removed unnecessary `#crop` and `#resample` macros (@janko)
 
-* [vips] Ignore undefined loader/saver options (@janko-m)
+* [vips] Ignore undefined loader/saver options (@janko)
 
-* [vips] Preserve transparent background in `#resize_to_pad` (@janko-m)
+* [vips] Preserve transparent background in `#resize_to_pad` (@janko)
 
-* [vips] Remove the ability to specify colors using names (@janko-m)
+* [vips] Remove the ability to specify colors using names (@janko)
 
-* [minimagick, vips] Autorotate images after loading them (@janko-m)
+* [minimagick, vips] Autorotate images after loading them (@janko)
 
-* [core] Delete result `Tempfile` object in case of processing errors (@janko-m)
+* [core] Delete result `Tempfile` object in case of processing errors (@janko)
 
-* [core] Allow returning `nil` in the `#custom` block (@janko-m)
+* [core] Allow returning `nil` in the `#custom` block (@janko)
 
-* [core] Allow specifying a path string as source file (@janko-m)
+* [core] Allow specifying a path string as source file (@janko)
 
-* [core] Allow saving to a specific location with the `:destination` call option (@janko-m)
+* [core] Allow saving to a specific location with the `:destination` call option (@janko)
 
 ## 0.9.0 (2018-03-16)
 
-* Added libvips module (@GustavoCaso, @janko-m)
+* Added libvips module (@GustavoCaso, @janko)
 
 * Drop official support for MRI 2.0 and 2.1
 
@@ -116,15 +208,15 @@
 
 ## 0.4.4 (2017-06-16)
 
-* Fix last changes being incompatible with older Ruby versions, again (@janko-m)
+* Fix last changes being incompatible with older Ruby versions, again (@janko)
 
 ## 0.4.3 (2017-06-16)
 
-* Fix last changes being incompatible with older Ruby versions (@janko-m)
+* Fix last changes being incompatible with older Ruby versions (@janko)
 
 ## 0.4.2 (2017-06-16)
 
-* Don't use path of input file as basename for output file (@janko-m)
+* Don't use path of input file as basename for output file (@janko)
 
 ## 0.4.1 (2016-09-08)
 

data/README.md

@@ -3,11 +3,11 @@
 Provides higher-level image processing helpers that are commonly needed
 when handling image uploads.
 
-This gem can process images with either [ImageMagick] or [libvips] libraries.
-ImageMagick is a good default choice, especially if you are migrating from
-another gem or library that uses ImageMagick. Libvips is a newer library that
-can process images [very rapidly][libvips performance] (up to 10x faster than
-ImageMagick).
+This gem can process images with either [ImageMagick]/[GraphicsMagick] or
+[libvips] libraries. ImageMagick is a good default choice, especially if you
+are migrating from another gem or library that uses ImageMagick. Libvips is a
+newer library that can process images [very rapidly][libvips performance]
+(often multiple times faster than ImageMagick).
 
 
 ## Goal
@@ -42,9 +42,9 @@ how to resize and process images.
 
 ## Usage
 
-Processing is performed through [`ImageProcessing::Vips`] or
-[`ImageProcessing::MiniMagick`] modules. Both modules share the same chainable
-API for defining the processing pipeline:
+Processing is performed through **[`ImageProcessing::Vips`]** or
+**[`ImageProcessing::MiniMagick`]** modules. Both modules share the same
+chainable API for defining the processing pipeline:
 
 ```rb
 require "image_processing/mini_magick"
@@ -117,7 +117,8 @@ pipeline.options
 ```
 
 The source object needs to responds to `#path`, or be a String, a Pathname, or
-a `Vips::Image`/`MiniMagick::Tool` object.
+a `Vips::Image`/`MiniMagick::Tool` object. Note that the processed file is
+always saved to a new location, in-place processing is not supported.
 
 ```rb
 ImageProcessing::Vips.source(File.open("source.jpg"))
@@ -144,8 +145,37 @@ You can continue reading the API documentation for specific modules:
 * **[`ImageProcessing::Vips`]**
 * **[`ImageProcessing::MiniMagick`]**
 
-See the **[wiki]** for additional "How To" guides for common scenarios.
+See the **[wiki]** for additional "How To" guides for common scenarios. The wiki
+is publicly editable, so you're encouraged to add your own guides.
 
+## Instrumentation
+
+You can register an `#instrumenter` block for a given pipeline, which will wrap
+the pipeline execution, allowing you to record performance metrics.
+
+```rb
+pipeline = ImageProcessing::Vips.instrumenter do |**options, &processing|
+  options[:source]     #=> #<File:...>
+  options[:loader]     #=> { fail: true }
+  options[:saver]      #=> { quality: 85 }
+  options[:format]     #=> "png"
+  options[:operations] #=> [[:resize_to_limit, 500, 500], [:flip, [:horizontal]]]
+  options[:processor]  #=> ImageProcessing::Vips::Processor
+
+  ActiveSupport::Notifications.instrument("process.image_processing", **options) do
+    processing.call # calls the pipeline
+  end
+end
+
+pipeline
+  .source(image)
+  .loader(fail: true)
+  .saver(quality: 85)
+  .convert("png")
+  .resize_to_limit(500, 500)
+  .flip(:horizontal)
+  .call # calls instrumenter
+```
 
 ## Contributing
 
@@ -179,11 +209,12 @@ The `ImageProcessing::MiniMagick` functionality was extracted from
 
 [MIT](LICENSE.txt)
 
-[libvips]: http://jcupitt.github.io/libvips/
+[libvips]: http://libvips.github.io/libvips/
 [ImageMagick]: https://www.imagemagick.org
-[`ImageProcessing::Vips`]: /doc/vips.md#imageprocessingvips
-[`ImageProcessing::MiniMagick`]: /doc/minimagick.md#imageprocessingminimagick
+[GraphicsMagick]: http://www.graphicsmagick.org
+[`ImageProcessing::Vips`]: doc/vips.md#readme
+[`ImageProcessing::MiniMagick`]: doc/minimagick.md#readme
 [refile-mini_magick]: https://github.com/refile/refile-mini_magick
-[wiki]: https://github.com/janko-m/image_processing/wiki
+[wiki]: https://github.com/janko/image_processing/wiki
 [HTTP.rb]: https://github.com/httprb/http
-[libvips performance]: https://github.com/jcupitt/libvips/wiki/Speed-and-memory-use
+[libvips performance]: https://github.com/libvips/libvips/wiki/Speed-and-memory-use

data/image_processing.gemspec

@@ -1,14 +1,14 @@
-require File.expand_path('../lib/image_processing/version', __FILE__)
+require File.expand_path("../lib/image_processing/version", __FILE__)
 
 Gem::Specification.new do |spec|
   spec.name          = "image_processing"
   spec.version       = ImageProcessing::VERSION
 
-  spec.required_ruby_version = ">= 2.0"
+  spec.required_ruby_version = ">= 2.3"
 
-  spec.summary       = "Set of higher-level helper methods for image processing."
-  spec.description   = "Set of higher-level helper methods for image processing."
-  spec.homepage      = "https://github.com/janko-m/image_processing"
+  spec.summary       = "High-level wrapper for processing images for the web with ImageMagick or libvips."
+  spec.description   = "High-level wrapper for processing images for the web with ImageMagick or libvips."
+  spec.homepage      = "https://github.com/janko/image_processing"
   spec.authors       = ["Janko Marohnić"]
   spec.email         = ["janko.marohnic@gmail.com"]
   spec.license       = "MIT"
@@ -16,8 +16,8 @@ Gem::Specification.new do |spec|
   spec.files         = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "*.gemspec"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "mini_magick", "~> 4.0"
-  spec.add_dependency "ruby-vips", ">= 2.0.10", "< 3"
+  spec.add_dependency "mini_magick", ">= 4.9.5", "< 5"
+  spec.add_dependency "ruby-vips", ">= 2.0.17", "< 3"
 
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest", "~> 5.8"

data/lib/image_processing/builder.rb

@@ -8,8 +8,25 @@ module ImageProcessing
       @options = options
     end
 
-    def call!(**options)
-      Pipeline.new(self.options).call(**options)
+    # Calls the pipeline to perform the processing from built options.
+    def call!(**call_options)
+      instrument do
+        Pipeline.new(pipeline_options).call(**call_options)
+      end
+    end
+
+    private
+
+    def instrument
+      return yield unless options[:instrumenter]
+
+      result = nil
+      options[:instrumenter].call(**pipeline_options) { result = yield }
+      result
+    end
+
+    def pipeline_options
+      options.reject { |key, _| key == :instrumenter }
     end
   end
 end

data/lib/image_processing/chainable.rb

@@ -1,77 +1,102 @@
 module ImageProcessing
+  # Implements a chainable interface for building processing options.
   module Chainable
+    # Specify the source image file.
     def source(file)
       branch source: file
     end
 
+    # Specify the output format.
     def convert(format)
       branch format: format
     end
 
+    # Specify processor options applied when loading the image.
     def loader(**options)
       branch loader: options
     end
 
+    # Specify processor options applied when saving the image.
     def saver(**options)
       branch saver: options
     end
 
-    def custom(&block)
-      operation :custom, block
+    # Register instrumentation block that will be called around the pipeline.
+    def instrumenter(&block)
+      branch instrumenter: block
     end
 
+    # Add multiple operations as a hash or an array.
+    #
+    #   .apply(resize_to_limit: [400, 400], strip: true)
+    #   # or
+    #   .apply([[:resize_to_limit, [400, 400]], [:strip, true])
     def apply(operations)
       operations.inject(self) do |builder, (name, argument)|
         if argument == true || argument == nil
           builder.send(name)
         elsif argument.is_a?(Array)
           builder.send(name, *argument)
+        elsif argument.is_a?(Hash)
+          builder.send(name, **argument)
         else
           builder.send(name, argument)
         end
       end
     end
 
-    def method_missing(name, *args)
-      return super if name.to_s.end_with?("?")
-      return send(name.to_s.chomp("!"), *args).call if name.to_s.end_with?("!")
-
-      operation name, *args
-    end
-
-    def operation(name, *args)
-      branch operations: [[name, args]]
+    # Add an operation defined by the processor.
+    def operation(name, *args, &block)
+      branch operations: [[name, args, *block]]
     end
 
+    # Call the defined processing and get the result. Allows specifying
+    # the source file and destination.
     def call(file = nil, destination: nil, **call_options)
-      options = {}
-      options = options.merge(source: file) if file
-      options = options.merge(destination: destination) if destination
+      options = { source: file, destination: destination }.compact
 
-      branch(options).call!(**call_options)
+      branch(**options).call!(**call_options)
     end
 
-    def branch(loader: nil, saver: nil, operations: nil, **other_options)
-      options = respond_to?(:options) ? self.options : DEFAULT_OPTIONS
+    # Creates a new builder object, merging current options with new options.
+    def branch(**new_options)
+      if self.is_a?(Builder)
+        options = self.options
+      else
+        options = DEFAULT_OPTIONS.merge(processor: self::Processor)
+      end
 
-      options = options.merge(loader: options[:loader].merge(loader)) if loader
-      options = options.merge(saver: options[:saver].merge(saver)) if saver
-      options = options.merge(operations: options[:operations] + operations) if operations
-      options = options.merge(processor_class: self::Processor) unless self.is_a?(Builder)
-      options = options.merge(other_options)
+      options = options.merge(new_options) do |key, old_value, new_value|
+        case key
+        when :loader, :saver then old_value.merge(new_value)
+        when :operations     then old_value + new_value
+        else                      new_value
+        end
+      end
+
+      Builder.new(options.freeze)
+    end
 
-      options.freeze
+    private
+
+    # Assume that any unknown method names an operation supported by the
+    # processor. Add a bang ("!") if you want processing to be performed.
+    def method_missing(name, *args, &block)
+      return super if name.to_s.end_with?("?")
+      return send(name.to_s.chomp("!"), *args, &block).call if name.to_s.end_with?("!")
 
-      Builder.new(options)
+      operation(name, *args, &block)
     end
+    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
 
+    # Empty options which the builder starts with.
     DEFAULT_OPTIONS = {
-      source:          nil,
-      loader:          {},
-      saver:           {},
-      format:          nil,
-      operations:      [],
-      processor_class: nil,
+      source:     nil,
+      loader:     {},
+      saver:      {},
+      format:     nil,
+      operations: [],
+      processor:  nil,
     }.freeze
   end
 end