image_processing 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c73cfe4047169c0385afc59779c47cc43385b8c02a82e540d8ad53adbd32aa41
-  data.tar.gz: 6ae50e569a9bad8b408c7f17a2eaded27e939be43c8b72f956d19875e2de5116
+  metadata.gz: 8ebf3b3c8fc4a4729473e346f5caddb1cc56fd971436ead2842185aa900c33b5
+  data.tar.gz: 9aaa8ae0ffbecbb0d3badd05835ca1d04c800bd0da4dfdec0beb11ea895fe003
 SHA512:
-  metadata.gz: deae9e4f3c13765f296aaf3801d02f55756518e077c38e1e6df89fc6c478fda48de41866292326684be06aeac3dedcd4fd1bd4688b09cc2b0ba858d6034e6416
-  data.tar.gz: 152da0d976a408e8c2dbf66e5054df86e22ae8006381833e4d0c845f7c643acb55355efeb30f910ca32c0b19fb3171503f92fcef240d26728151a0a8de68ec54
+  metadata.gz: e223f370b545ff3181877d416565e3e5e67ce9bc4478b0b94a26434a2086cb76f1f07f9099e27b01d7b4c46a90c457e39409b146b5839fd953b1d08f694acae6
+  data.tar.gz: a0e9c3db88a40607128d90a4f37e8c5b5ba5e56064a7cc8c38f6ee13bb585f6de0d13b40177f5af20434e6b1ab37b5dbe22ca96d22cb4b98266878673d3c9e4b

data/CHANGELOG.md

@@ -1,4 +1,8 @@
-## HEAD
+## 1.7.0 (2018-09-20)
+
+* [vips] `#rotate` now always calls `vips_similarity()` and forwards all options to it (@janko-m)
+
+## 1.6.0 (2018-07-13)
 
 * [vips] In `#composite` accept `:offset` option for the position of the overlay image (@janko-m)
 

data/image_processing.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "mini_magick", "~> 4.0"
-  spec.add_dependency "ruby-vips", ">= 2.0.11", "< 3"
+  spec.add_dependency "ruby-vips", ">= 2.0.13", "< 3"
 
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest", "~> 5.8"

data/lib/image_processing/builder.rb

@@ -8,6 +8,7 @@ module ImageProcessing
       @options = options
     end
 
+    # Calls the pipeline to perform the processing from built options.
     def call!(**options)
       Pipeline.new(self.options).call(**options)
     end

data/lib/image_processing/chainable.rb

@@ -1,21 +1,31 @@
 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
 
+    # 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
@@ -28,6 +38,8 @@ module ImageProcessing
       end
     end
 
+    # 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?("!")
@@ -35,10 +47,13 @@ module ImageProcessing
       operation(name, *args, &block)
     end
 
+    # 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
@@ -47,6 +62,7 @@ module ImageProcessing
       branch(options).call!(**call_options)
     end
 
+    # Creates a new builder object, merging current options with new options.
     def branch(loader: nil, saver: nil, operations: nil, **other_options)
       options = respond_to?(:options) ? self.options : DEFAULT_OPTIONS
 
@@ -61,6 +77,7 @@ module ImageProcessing
       Builder.new(options)
     end
 
+    # Empty options which the builder starts with.
     DEFAULT_OPTIONS = {
       source:     nil,
       loader:     {},

data/lib/image_processing/mini_magick.rb

@@ -5,6 +5,7 @@ module ImageProcessing
   module MiniMagick
     extend Chainable
 
+    # Returns whether the given image file is processable.
     def self.valid_image?(file)
       ::MiniMagick::Tool::Convert.new do |convert|
         convert << file.path
@@ -18,8 +19,12 @@ module ImageProcessing
     class Processor < ImageProcessing::Processor
       accumulator :magick, ::MiniMagick::Tool
 
+      # Default sharpening parameters used on generated thumbnails.
       SHARPEN_PARAMETERS = { radius: 0, sigma: 1 }
 
+      # Initializes the image on disk into a MiniMagick::Tool object. Accepts
+      # additional options related to loading the image (e.g. geometry).
+      # Additionally auto-orients the image to be upright.
       def self.load_image(path_or_magick, page: nil, geometry: nil, auto_orient: true, **options)
         if path_or_magick.is_a?(::MiniMagick::Tool)
           magick = path_or_magick
@@ -40,6 +45,9 @@ module ImageProcessing
         magick
       end
 
+      # Calls the built ImageMagick command to perform processing and save
+      # the result to disk. Accepts additional options related to saving the
+      # image (e.g. quality).
       def self.save_image(magick, destination_path, allow_splitting: false, **options)
         Utils.apply_options(magick, options)
 
@@ -49,14 +57,18 @@ module ImageProcessing
         Utils.disallow_split_layers!(destination_path) unless allow_splitting
       end
 
+      # Resizes the image to not be larger than the specified dimensions.
       def resize_to_limit(width, height, **options)
         thumbnail("#{width}x#{height}>", **options)
       end
 
+      # Resizes the image to fit within the specified dimensions.
       def resize_to_fit(width, height, **options)
         thumbnail("#{width}x#{height}", **options)
       end
 
+      # Resizes the image to fill the specified dimensions, applying any
+      # necessary cropping.
       def resize_to_fill(width, height, gravity: "Center", **options)
         thumbnail("#{width}x#{height}^", **options)
         magick.gravity gravity
@@ -64,6 +76,8 @@ module ImageProcessing
         magick.extent "#{width}x#{height}"
       end
 
+      # Resizes the image to fit within the specified dimensions and fills
+      # the remaining area with the specified background color.
       def resize_and_pad(width, height, background: :transparent, gravity: "Center", **options)
         thumbnail("#{width}x#{height}", **options)
         magick.background color(background)
@@ -71,11 +85,17 @@ module ImageProcessing
         magick.extent "#{width}x#{height}"
       end
 
+      # Rotates the image by an arbitrary angle. For angles that are not
+      # multiple of 90 degrees an optional background color can be specified to
+      # fill in the gaps.
       def rotate(degrees, background: nil)
         magick.background color(background) if background
         magick.rotate(degrees)
       end
 
+      # Overlays the specified image over the current one. Supports specifying
+      # an additional mask, composite mode, direction or offset of the overlay
+      # image.
       def composite(overlay = :none, mask: nil, mode: nil, gravity: nil, offset: nil, args: nil, **options, &block)
         return magick.composite if overlay == :none
 
@@ -107,22 +127,28 @@ module ImageProcessing
         magick.composite
       end
 
+      # Defines settings from the provided hash.
       def define(options)
         return magick.define(options) if options.is_a?(String)
         Utils.apply_define(magick, options)
       end
 
+      # Specifies resource limits from the provided hash.
       def limits(options)
         options.each { |type, value| magick.args.unshift("-limit", type.to_s, value.to_s) }
         magick
       end
 
+      # Appends a raw ImageMagick command-line argument to the command.
       def append(*args)
         magick.merge! args
       end
 
       private
 
+      # Converts the given color value into an identifier ImageMagick understands.
+      # This supports specifying RGB(A) values with arrays, which mainly exists
+      # for compatibility with the libvips implementation.
       def color(value)
         return "rgba(255,255,255,0.0)" if value.to_s == "transparent"
         return "rgb(#{value.join(",")})" if value.is_a?(Array) && value.count == 3
@@ -132,6 +158,8 @@ module ImageProcessing
         raise ArgumentError, "unrecognized color format: #{value.inspect} (must be one of: string, 3-element RGB array, 4-element RGBA array)"
       end
 
+      # Resizes the image using the specified geometry, and sharpens the
+      # resulting thumbnail.
       def thumbnail(geometry, sharpen: {})
         magick.resize(geometry)
 
@@ -143,6 +171,7 @@ module ImageProcessing
         magick
       end
 
+      # Converts the image on disk in various forms into a path.
       def convert_to_path(file, name)
         if file.is_a?(String)
           file
@@ -158,6 +187,9 @@ module ImageProcessing
       module Utils
         module_function
 
+        # When a multi-layer format is being converted into a single-layer
+        # format, ImageMagick will create multiple images, one for each layer.
+        # We want to warn the user that this is probably not what they wanted.
         def disallow_split_layers!(destination_path)
           layers = Dir[destination_path.sub(/\.\w+$/, '-*\0')]
 
@@ -167,6 +199,7 @@ module ImageProcessing
           end
         end
 
+        # Applies options from the provided hash.
         def apply_options(magick, define: {}, **options)
           options.each do |option, value|
             case value
@@ -179,12 +212,13 @@ module ImageProcessing
           apply_define(magick, define)
         end
 
+        # Applies settings from the provided (nested) hash.
         def apply_define(magick, options)
           options.each do |namespace, settings|
-            namespace = namespace.to_s.gsub("_", "-")
+            namespace = namespace.to_s.tr("_", "-")
 
             settings.each do |key, value|
-              key = key.to_s.gsub("_", "-")
+              key = key.to_s.tr("_", "-")
 
               magick.define "#{namespace}:#{key}=#{value}"
             end

data/lib/image_processing/pipeline.rb

@@ -6,6 +6,7 @@ module ImageProcessing
 
     attr_reader :source, :loader, :saver, :format, :operations, :processor, :destination
 
+    # Initializes the pipeline with all the processing options.
     def initialize(options)
       options.each do |name, value|
         value = normalize_source(value, options) if name == :source
@@ -13,6 +14,10 @@ module ImageProcessing
       end
     end
 
+    # Performs the defined series of operations, and saves the result in a new
+    # tempfile or a specified path on disk, or if `save: false` was passed in
+    # returns the unsaved accumulator object that can be used for further
+    # processing.
     def call(save: true)
       accumulator = processor.load_image(source, **loader)
 
@@ -33,10 +38,12 @@ module ImageProcessing
       end
     end
 
+    # Retrieves the source path on disk.
     def source_path
       source if source.is_a?(String)
     end
 
+    # Determines the appropriate destination image format.
     def destination_format
       format   = File.extname(destination)[1..-1] if destination
       format ||= self.format
@@ -47,6 +54,8 @@ module ImageProcessing
 
     private
 
+    # Creates a new tempfile for the destination file, yields it, and refreshes
+    # the file descriptor to get the updated file.
     def create_tempfile
       tempfile = Tempfile.new(["image_processing", ".#{destination_format}"], binmode: true)
 
@@ -70,6 +79,7 @@ module ImageProcessing
       raise
     end
 
+    # Converts the source image object into a path or the accumulator object.
     def normalize_source(source, options)
       fail Error, "source file is not provided" unless source
 

data/lib/image_processing/processor.rb

@@ -1,11 +1,18 @@
 module ImageProcessing
+  # Abstract class inherited by individual processors.
   class Processor
+    # Use for processor subclasses to specify the name and the class of their
+    # accumulator object (e.g. MiniMagic::Tool or Vips::Image).
     def self.accumulator(name, klass)
       define_method(name) { @accumulator }
       protected(name)
       const_set(:ACCUMULATOR_CLASS, klass)
     end
 
+    # Calls the operation to perform the processing. If the operation is
+    # defined on the processor (macro), calls it. Otherwise calls the
+    # operation directly on the accumulator object. This provides a common
+    # umbrella above defined macros and direct operations.
     def self.apply_operation(accumulator, name, *args, &block)
       if (instance_methods - Object.instance_methods).include?(name)
         instance = new(accumulator)
@@ -19,6 +26,8 @@ module ImageProcessing
       @accumulator = accumulator
     end
 
+    # Calls the given block with the accumulator object. Useful for when you
+    # want to access the accumulator object directly.
     def custom(&block)
       (block && block.call(@accumulator)) || @accumulator
     end

data/lib/image_processing/version.rb

@@ -1,3 +1,3 @@
 module ImageProcessing
-  VERSION = "1.6.0"
+  VERSION = "1.7.0"
 end

data/lib/image_processing/vips.rb

@@ -7,6 +7,7 @@ module ImageProcessing
   module Vips
     extend Chainable
 
+    # Returns whether the given image file is processable.
     def self.valid_image?(file)
       ::Vips::Image.new_from_file(file.path, access: :sequential).avg
       true
@@ -17,12 +18,15 @@ module ImageProcessing
     class Processor < ImageProcessing::Processor
       accumulator :image, ::Vips::Image
 
-      # default sharpening mask that provides a fast and mild sharpen
+      # Default sharpening mask that provides a fast and mild sharpen.
       SHARPEN_MASK = ::Vips::Image.new_from_array [[-1, -1, -1],
                                                    [-1, 32, -1],
                                                    [-1, -1, -1]], 24
 
 
+      # Loads the image on disk into a Vips::Image object. Accepts additional
+      # loader-specific options (e.g. interlacing). Afterwards auto-rotates the
+      # image to be upright.
       def self.load_image(path_or_image, autorot: true, **options)
         if path_or_image.is_a?(::Vips::Image)
           image = path_or_image
@@ -37,6 +41,9 @@ module ImageProcessing
         image
       end
 
+      # Writes the Vips::Image object to disk. This starts the processing
+      # pipeline defined in the Vips::Image object. Accepts additional
+      # saver-specific options (e.g. quality).
       def self.save_image(image, destination_path, quality: nil, **options)
         options = options.merge(Q: quality) if quality
         options = Utils.select_valid_saver_options(destination_path, options)
@@ -44,41 +51,43 @@ module ImageProcessing
         image.write_to_file(destination_path, **options)
       end
 
+      # Resizes the image to not be larger than the specified dimensions.
       def resize_to_limit(width, height, **options)
         width, height = default_dimensions(width, height)
         thumbnail(width, height, size: :down, **options)
       end
 
+      # Resizes the image to fit within the specified dimensions.
       def resize_to_fit(width, height, **options)
         width, height = default_dimensions(width, height)
         thumbnail(width, height, **options)
       end
 
+      # Resizes the image to fill the specified dimensions, applying any
+      # necessary cropping.
       def resize_to_fill(width, height, **options)
         thumbnail(width, height, crop: :centre, **options)
       end
 
+      # Resizes the image to fit within the specified dimensions and fills
+      # the remaining area with the specified background color.
       def resize_and_pad(width, height, gravity: "centre", extend: nil, background: nil, alpha: nil, **options)
-        embed_options = { extend: extend, background: background }
-        embed_options.reject! { |name, value| value.nil? }
-
         image = thumbnail(width, height, **options)
         image = image.add_alpha if alpha && !image.has_alpha?
-        image.gravity(gravity, width, height, **embed_options)
+        image.gravity(gravity, width, height, extend: extend, background: background)
       end
 
-      def rotate(degrees, background: nil)
-        if degrees % 90 == 0
-          image.rot(:"d#{degrees % 360}")
-        else
-          options = { angle: degrees }
-          options[:background] = background if background
-
-          image.similarity(**options)
-        end
+      # Rotates the image by an arbitrary angle. Additional options can be
+      # specified, such as background colors to fill in the gaps when rotating
+      # with an angle which is not a multiple of 90 degrees.
+      def rotate(degrees, **options)
+        image.similarity(angle: degrees, **options)
       end
 
-      def composite(overlay, _mode = nil, mode: :over, gravity: :"north-west", offset: nil, **options)
+      # Overlays the specified image over the current one. Supports specifying
+      # composite mode, direction or offset of the overlay image.
+      def composite(overlay, _mode = nil, mode: "over", gravity: "north-west", offset: nil, **options)
+        # if the mode argument is given, call the original Vips::Image#composite
         if _mode
           overlay = [overlay] unless overlay.is_a?(Array)
           overlay = overlay.map { |object| convert_to_image(object, "overlay") }
@@ -87,15 +96,19 @@ module ImageProcessing
         end
 
         overlay = convert_to_image(overlay, "overlay")
-        overlay = overlay.add_alpha unless overlay.has_alpha? # so that #gravity can use transparent background
+        # add alpha channel so that #gravity can use a transparent background
+        overlay = overlay.add_alpha unless overlay.has_alpha?
 
+        # apply offset with correct gravity and make remainder transparent
         if offset
           opposite_gravity = gravity.to_s.gsub(/\w+/, "north"=>"south", "south"=>"north", "east"=>"west", "west"=>"east")
           overlay = overlay.gravity(opposite_gravity, overlay.width + offset.first, overlay.height + offset.last)
         end
 
+        # create image-sized transparent background and apply specified gravity
         overlay = overlay.gravity(gravity, image.width, image.height)
 
+        # apply the composition
         image.composite(overlay, mode, **options)
       end
 
@@ -106,6 +119,8 @@ module ImageProcessing
 
       private
 
+      # Resizes the image according to the specified parameters, and sharpens
+      # the resulting thumbnail.
       def thumbnail(width, height, sharpen: SHARPEN_MASK, **options)
         image = self.image
         image = image.thumbnail_image(width, height: height, **options)
@@ -113,12 +128,14 @@ module ImageProcessing
         image
       end
 
+      # Hack to allow omitting one dimension.
       def default_dimensions(width, height)
         raise Error, "either width or height must be specified" unless width || height
 
         [width || ::Vips::MAX_COORD, height || ::Vips::MAX_COORD]
       end
 
+      # Converts the image on disk in various forms into a Vips::Image object.
       def convert_to_image(object, name)
         return object if object.is_a?(::Vips::Image)
 
@@ -138,16 +155,24 @@ module ImageProcessing
       module Utils
         module_function
 
+        # libvips uses various loaders depending on the input format.
         def select_valid_loader_options(source_path, options)
           loader = ::Vips.vips_foreign_find_load(source_path)
           loader ? select_valid_options(loader, options) : options
         end
 
+        # Filters out unknown options for saving images.
         def select_valid_saver_options(destination_path, options)
           saver = ::Vips.vips_foreign_find_save(destination_path)
           saver ? select_valid_options(saver, options) : options
         end
 
+        # libvips uses various loaders and savers depending on the input and
+        # output image format. Each of these loaders and savers accept slightly
+        # different options, so to allow the user to be able to specify options
+        # for a specific loader/saver and have it ignored for other
+        # loaders/savers, we do a little bit of introspection and filter out
+        # options that don't exist for a particular loader or saver.
         def select_valid_options(operation_name, options)
           operation = ::Vips::Operation.new(operation_name)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: image_processing
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-13 00:00:00.000000000 Z
+date: 2018-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_magick
@@ -30,7 +30,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.13
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -40,7 +40,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.13
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'