image_processing 1.2.0 → 1.12.1

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
@@ -16,125 +17,224 @@ module ImageProcessing
     end
 
     class Processor < ImageProcessing::Processor
-      IMAGE_CLASS        = ::MiniMagick::Tool
+      accumulator :magick, ::MiniMagick::Tool
+
+      # Default sharpening parameters used on generated thumbnails.
       SHARPEN_PARAMETERS = { radius: 0, sigma: 1 }
 
-      def resize_to_limit(magick, width, height, **options)
-        thumbnail(magick, "#{width}x#{height}>", **options)
+      # 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, loader: nil, page: nil, geometry: nil, auto_orient: true, **options)
+        if path_or_magick.is_a?(::MiniMagick::Tool)
+          magick = path_or_magick
+        else
+          source_path = path_or_magick
+          magick = ::MiniMagick::Tool::Convert.new
+
+          Utils.apply_options(magick, **options)
+
+          input  = source_path
+          input  = "#{loader}:#{input}" if loader
+          input += "[#{page}]" if page
+          input += "[#{geometry}]" if geometry
+
+          magick << input
+        end
+
+        magick.auto_orient if auto_orient
+        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)
+
+        magick << destination_path
+        magick.call
+
+        Utils.disallow_split_layers!(destination_path) unless allow_splitting
       end
 
-      def resize_to_fit(magick, width, height, **options)
-        thumbnail(magick, "#{width}x#{height}", **options)
+      # Resizes the image to not be larger than the specified dimensions.
+      def resize_to_limit(width, height, **options)
+        thumbnail("#{width}x#{height}>", **options)
       end
 
-      def resize_to_fill(magick, width, height, gravity: "Center", **options)
-        thumbnail(magick, "#{width}x#{height}^", **options)
+      # 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
-        magick.background "rgba(255,255,255,0.0)" # transparent
+        magick.background color(:transparent)
         magick.extent "#{width}x#{height}"
       end
 
-      def resize_and_pad(magick, width, height, background: :transparent, gravity: "Center", **options)
-        background = "rgba(255,255,255,0.0)" if background.to_s == "transparent"
-
-        thumbnail(magick, "#{width}x#{height}", **options)
-        magick.background background
+      # 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)
         magick.gravity gravity
         magick.extent "#{width}x#{height}"
       end
 
-      def define(magick, options)
-        return magick.define(options) if options.is_a?(String)
+      # Crops the image with the specified crop points.
+      def crop(*args)
+        case args.count
+        when 1 then magick.crop(*args)
+        when 4 then magick.crop("#{args[2]}x#{args[3]}+#{args[0]}+#{args[1]}")
+        else fail ArgumentError, "wrong number of arguments (expected 1 or 4, got #{args.count})"
+        end
+      end
 
-        options.each do |namespace, options|
-          namespace = namespace.to_s.gsub("_", "-")
+      # 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
 
-          options.each do |key, value|
-            key = key.to_s.gsub("_", "-")
+      # 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
 
-            magick.define "#{namespace}:#{key}=#{value}"
-          end
+        if options.key?(:compose)
+          warn "[IMAGE_PROCESSING] The :compose parameter in #composite has been renamed to :mode, the :compose alias will be removed in ImageProcessing 2."
+          mode = options[:compose]
         end
 
-        magick
-      end
-
-      def limits(magick, options)
-        limit_args = options.flat_map { |type, value| %W[-limit #{type} #{value}] }
-        prepend_args(magick, limit_args)
-      end
+        if options.key?(:geometry)
+          warn "[IMAGE_PROCESSING] The :geometry parameter in #composite has been deprecated and will be removed in ImageProcessing 2. Use :offset instead, e.g. `geometry: \"+10+15\"` should be replaced with `offset: [10, 15]`."
+          geometry = options[:geometry]
+        end
+        geometry = "%+d%+d" % offset if offset
 
-      def append(magick, *args)
-        magick.merge! args
-      end
+        overlay_path = convert_to_path(overlay, "overlay")
+        mask_path    = convert_to_path(mask, "mask") if mask
 
-      def 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
-        else
-          source_path = path_or_magick
-          magick = ::MiniMagick::Tool::Convert.new
+        magick << overlay_path
+        magick << mask_path if mask_path
 
-          apply_options(magick, options)
+        magick.compose(mode) if mode
+        define(compose: { args: args }) if args
 
-          input_path  = source_path
-          input_path += "[#{page}]" if page
-          input_path += "[#{geometry}]" if geometry
+        magick.gravity(gravity) if gravity
+        magick.geometry(geometry) if geometry
 
-          magick << input_path
-        end
+        yield magick if block_given?
 
-        magick.auto_orient if auto_orient
-        magick
+        magick.composite
       end
 
-      def save_image(magick, destination_path, allow_splitting: false, **options)
-        apply_options(magick, options)
+      # Defines settings from the provided hash.
+      def define(options)
+        return magick.define(options) if options.is_a?(String)
+        Utils.apply_define(magick, options)
+      end
 
-        magick << destination_path
-        magick.call
+      # 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
 
-        disallow_split_layers!(destination_path) unless allow_splitting
+      # Appends a raw ImageMagick command-line argument to the command.
+      def append(*args)
+        magick.merge! args
       end
 
       private
 
-      def thumbnail(magick, geometry, sharpen: {})
+      # 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
+        return "rgba(#{value.join(",")})" if value.is_a?(Array) && value.count == 4
+        return value if value.is_a?(String)
+
+        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: nil)
         magick.resize(geometry)
-        magick.sharpen(sharpen_value(sharpen)) if sharpen
+
+        if sharpen
+          sharpen = SHARPEN_PARAMETERS.merge(sharpen)
+          magick.sharpen("#{sharpen[:radius]}x#{sharpen[:sigma]}")
+        end
+
         magick
       end
 
-      def sharpen_value(parameters)
-        parameters    = SHARPEN_PARAMETERS.merge(parameters)
-        radius, sigma = parameters.values_at(:radius, :sigma)
-
-        "#{radius}x#{sigma}"
+      # Converts the image on disk in various forms into a path.
+      def convert_to_path(file, name)
+        if file.is_a?(String)
+          file
+        elsif file.respond_to?(:to_path)
+          file.to_path
+        elsif file.respond_to?(:path)
+          file.path
+        else
+          raise ArgumentError, "#{name} must be a String, Pathname, or respond to #path"
+        end
       end
 
-      def apply_options(magick, define: {}, **options)
-        options.each do |option, value|
-          case value
-          when true, nil then magick.send(option)
-          when false     then magick.send(option).+
-          else                magick.send(option, *value)
+      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')]
+
+          if layers.any?
+            layers.each { |path| File.delete(path) }
+            raise Error, "Source format is multi-layer, but destination format is single-layer. If you care only about the first layer, add `.loader(page: 0)` to your pipeline. If you want to process each layer, see https://github.com/janko/image_processing/wiki/Splitting-a-PDF-into-multiple-images or use `.saver(allow_splitting: true)`."
           end
         end
 
-        define(magick, define)
-      end
+        # Applies options from the provided hash.
+        def apply_options(magick, define: {}, **options)
+          options.each do |option, value|
+            case value
+            when true, nil then magick.send(option)
+            when false     then magick.send(option).+
+            else                magick.send(option, *value)
+            end
+          end
 
-      def prepend_args(magick, args)
-        magick.args.replace args + magick.args
-        magick
-      end
+          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.tr("_", "-")
 
-      def disallow_split_layers!(destination_path)
-        layers = Dir[destination_path.sub(/\.\w+$/, '-*\0')]
+            settings.each do |key, value|
+              key = key.to_s.tr("_", "-")
+
+              magick.define "#{namespace}:#{key}=#{value}"
+            end
+          end
 
-        if layers.any?
-          layers.each { |path| File.delete(path) }
-          raise Error, "Multi-layer image is being converted into a single-layer format. You should either process individual layers or set :allow_splitting to true. See https://github.com/janko-m/image_processing/wiki/Splitting-a-PDF-into-multiple-images for how to process each layer individually."
+          magick
         end
       end
     end

data/lib/image_processing/pipeline.rb

@@ -4,50 +4,60 @@ module ImageProcessing
   class Pipeline
     DEFAULT_FORMAT = "jpg"
 
-    attr_reader :source, :loader, :saver, :format, :operations, :processor_class, :destination
+    attr_reader :loader, :saver, :format, :operations, :processor, :destination
 
+    # Initializes the pipeline with all the processing options.
     def initialize(options)
+      fail Error, "source file is not provided" unless options[:source]
+
       options.each do |name, value|
-        value = normalize_source(value, options) if name == :source
         instance_variable_set(:"@#{name}", value)
       end
     end
 
+    # Determines the destination and calls the processor.
     def call(save: true)
-      processor = processor_class.new(self)
-      image     = processor.load_image(source, **loader)
-
-      operations.each do |name, args|
-        image = processor.apply_operation(name, image, *args)
-      end
-
       if save == false
-        image
+        call_processor
       elsif destination
         handle_destination do
-          processor.save_image(image, destination, **saver)
+          call_processor(destination: destination)
         end
       else
         create_tempfile do |tempfile|
-          processor.save_image(image, tempfile.path, **saver)
+          call_processor(destination: tempfile.path)
         end
       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   = determine_format(destination) if destination
       format ||= self.format
-      format ||= File.extname(source_path)[1..-1] if source_path
+      format ||= determine_format(source_path) if source_path
 
       format || DEFAULT_FORMAT
     end
 
     private
 
+    def call_processor(**options)
+      processor.call(
+        source:     source,
+        loader:     loader,
+        operations: operations,
+        saver:      saver,
+        **options
+      )
+    end
+
+    # 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)
 
@@ -71,22 +81,23 @@ module ImageProcessing
       raise
     end
 
-    def normalize_source(source, options)
-      fail Error, "source file is not provided" unless source
-
-      image_class = options[:processor_class]::IMAGE_CLASS
-
-      if source.is_a?(image_class)
-        source
-      elsif source.is_a?(String)
-        source
-      elsif source.respond_to?(:path)
-        source.path
-      elsif source.respond_to?(:to_path)
-        source.to_path
+    # Converts the source image object into a path or the accumulator object.
+    def source
+      if @source.is_a?(String)
+        @source
+      elsif @source.respond_to?(:path)
+        @source.path
+      elsif @source.respond_to?(:to_path)
+        @source.to_path
       else
-        fail Error, "source file needs to respond to #path, or be a String, a Pathname, or a #{image_class} object"
+        @source
       end
     end
+
+    def determine_format(file_path)
+      extension = File.extname(file_path)
+
+      extension[1..-1] if extension.size > 1
+    end
   end
 end

data/lib/image_processing/processor.rb

@@ -1,23 +1,72 @@
 module ImageProcessing
+  # Abstract class inherited by individual processors.
   class Processor
-    def initialize(pipeline)
-      @pipeline = pipeline
-    end
+    def self.call(source:, loader:, operations:, saver:, destination: nil)
+      unless source.is_a?(String) || source.is_a?(self::ACCUMULATOR_CLASS)
+        fail Error, "invalid source: #{source.inspect}"
+      end
+
+      if operations.dig(0, 0).to_s.start_with?("resize_") &&
+         loader.empty? &&
+         supports_resize_on_load?
+
+        accumulator = source
+      else
+        accumulator = load_image(source, **loader)
+      end
+
+      operations.each do |operation|
+        accumulator = apply_operation(accumulator, operation)
+      end
 
-    def apply_operation(name, image, *args)
-      if respond_to?(name)
-        public_send(name, image, *args)
+      if destination
+        save_image(accumulator, destination, **saver)
       else
-        image.send(name, *args)
+        accumulator
       end
     end
 
-    def custom(image, block)
-      (block && block.call(image)) || image
+    # Use for processor subclasses to specify the name and the class of their
+    # accumulator object (e.g. MiniMagick::Tool or Vips::Image).
+    def self.accumulator(name, klass)
+      define_method(name) { @accumulator }
+      protected(name)
+      const_set(:ACCUMULATOR_CLASS, klass)
     end
 
-    private
+    # Delegates to #apply_operation.
+    def self.apply_operation(accumulator, (name, args, block))
+      new(accumulator).apply_operation(name, *args, &block)
+    end
 
-    attr_reader :pipeline
+    # Whether the processor supports resizing the image upon loading.
+    def self.supports_resize_on_load?
+      false
+    end
+
+    def initialize(accumulator = nil)
+      @accumulator = accumulator
+    end
+
+    # Calls the operation to perform the processing. If the operation is
+    # defined on the processor (macro), calls the method. Otherwise calls the
+    # operation directly on the accumulator object. This provides a common
+    # umbrella above defined macros and direct operations.
+    def apply_operation(name, *args, &block)
+      receiver = respond_to?(name) ? self : @accumulator
+
+      if args.last.is_a?(Hash)
+        kwargs = args.pop
+        receiver.public_send(name, *args, **kwargs, &block)
+      else
+        receiver.public_send(name, *args, &block)
+      end
+    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
   end
 end