dougmcbride-fleximage 1.0.3

data/lib/fleximage/operator/background.rb

@@ -0,0 +1,62 @@
+module Fleximage
+  module Operator
+
+    # Composites a transparent image over a colored backgroud
+    #
+    # It accepts the following options:
+    #
+    # * +color+: the color of the background image.
+    #   Use an RMagick named color or use the +color+ method in Fleximage::Controller, or a
+    #   Magick::Pixel object.
+    # 
+    # * +size+: The size of the background image, in Fleximage *size* format.  
+    #   By default the background image is the same size as the foreground image
+    # 
+    # * +alignment+: A symbol that tells Fleximage where to put the foreground image on 
+    #   top of the background image.  Can be any of the following:
+    #   <tt>:center, :top, :top_right, :right, :bottom_right, :bottom, :bottom_left, :left, :top_left</tt>.
+    #   Default is :+center+
+    # 
+    # * +offset+: the number of pixels to offset the foreground image from it's :+alignment+ anchor, in FlexImage 
+    #   *size* format.  Useful to give a bit a space between your image and the edge of the background, for instance.
+    #   *NOTE:* Due to some unexpected (buggy?) RMagick behaviour :+offset+ will work strangely
+    #   if :+alignment+ is set to a corner non-corner value, such as :+top+ or :+center+.  Using :+offset+ in
+    #   these cases will force the overlay into a corner anyway.
+    # 
+    # * +blending+: The blending mode governs how the foreground image gets composited onto the background.  You can 
+    #   get some funky effects with modes like :+copy_cyan+ or :+screen+.  For a full list of blending
+    #   modes checkout the RMagick documentation (http://www.simplesystems.org/RMagick/doc/constants.html#CompositeOperator).
+    #   To use a blend mode remove the +CompositeOp+ form the name and "unserscorize" the rest.  For instance,
+    #   +MultiplyCompositeOp+ becomes :+multiply+, and +CopyBlackCompositeOp+ becomes :+copy_black+.
+
+    class Background < Operator::Base 
+      def operate(options = {})
+        options = options.symbolize_keys
+
+        #default to a white background if the color option is not set
+        color = options[:color] || 'white'
+
+        #use the existing image's size if the size option is not set
+        width, height = options.key?(:size) ? size_to_xy(options[:size]) : [@image.columns, @image.rows]
+
+        #create the background image onto which we will composite the foreground image
+        bg = Magick::Image.new(width, height) do 
+          self.background_color = color
+          self.format = 'PNG'
+        end
+
+        #prepare attributes for composite operation
+        args = []
+        args << @image
+        args << symbol_to_gravity(options[:alignment] || :center)
+        args += size_to_xy(options[:offset]) if options[:offset]
+        args << symbol_to_blending_mode(options[:blending] || :over)
+
+        #composite the foreground image onto the background
+        bg.composite!(*args)
+
+        return bg
+      end
+    end
+  end
+end

data/lib/fleximage/operator/base.rb

@@ -0,0 +1,189 @@
+module Fleximage
+  module Operator
+    
+    class BadOperatorResult < Exception #:nodoc:
+    end
+    
+    class OperationNotImplemented < Exception #:nodoc:
+    end
+    
+    # The Operator::Base class is what all other Operator classes inherit from.
+    # To write your own Operator class, simply inherit from this class, and 
+    # implement your own operate methods, with your own arguments.  Just 
+    # return a new RMagick image object that represents the new image, and
+    # the model will be updated automatically.
+    #
+    # You have access to a few instance variables in the operate method:
+    #
+    # * @image : The current image from the model.  Use this is a starting 
+    #   point for all transformations.
+    # * @model : The model instance that this image transformation is happenining
+    #   in.  Use it to get data out of your model for display in your image.
+    class Base
+      # Create a operator, capturing the model object to operate on
+      def initialize(proxy, image, model_obj) #:nodoc:
+        @proxy = proxy
+        @image = image
+        @model = model_obj
+      end
+      
+      # Start the operation
+      def execute(*args) #:nodoc:
+        # Get the result of the Operators #operate method
+        result = operate(*args)
+        
+        # Ensure that the result is an RMagick:Image object
+        unless result.is_a?(Magick::Image)
+          raise BadOperatorResult, "expected #{self.class}#operate to return an instance of Magick::Image. \n"+
+                                   "Got instance of #{result.class} instead."
+        end
+        
+        # Save the result to the operator proxy
+        @proxy.image = result
+      end
+      
+      # Perform the operation.  Override this method in your Operator::Base subclasses
+      # in order to write your own image operators.
+      def operate(*args)
+        raise OperationNotImplemented, "Override this method in your own subclass."
+      end
+      
+      # ---
+      # - SUPPORT METHODS
+      # ---
+      
+      # Allows access to size conversion globally.  See size_to_xy for a more detailed explanation
+      def self.size_to_xy(size)
+        case          
+        when size.is_a?(Array) && size.size == 2  # [320, 240]
+          size
+      
+        when size.to_s.include?('x')              # "320x240"
+          size.split('x').collect(&:to_i)
+        
+        else # Anything else, convert the object to an integer and assume square dimensions
+          [size.to_i, size.to_i]
+          
+        end
+      end
+      
+      # This method will return a valid color Magick::Pixel object.  It will also auto adjust
+      # for the bit depth of your ImageMagick configuration.
+      #
+      # Usage:
+      #
+      #   color('red')          #=> Magick::Pixel with a red color
+      #   color(0, 255, 0)      #=> Magick::Pixel with a green color
+      #   color(0, 0, 255, 47)  #=> Magick::Pixel with a blue clolor and slightly transparent
+      #
+      #   # on an ImageMagick with a QuantumDepth of 16
+      #   color(0, 255, 0)      #=> Magick::Pixel with rgb of (0, 65535, 0) (auto adjusted to 16bit channels)
+      #
+      def self.color(*args)
+        if args.size == 1 && args.first.is_a?(String)
+          args.first
+        else
+          
+          # adjust color to proper bit depth
+          if Magick::QuantumDepth != 8
+            max = case Magick::QuantumDepth
+            when 16
+              65_535
+            when 32
+              4_294_967_295
+            end
+            
+            args.map! do |value|
+              (value.to_f/255 * max).to_i
+            end
+          end
+          
+          # create the pixel
+          Magick::Pixel.new(*args)
+        end
+      end
+      
+      def color(*args)
+        self.class.color(*args)
+      end
+      
+      # Converts a size object to an [x,y] array.  Acceptible formats are:
+      # 
+      # * 10
+      # * "10"
+      # * "10x20"
+      # * [10, 20]
+      #
+      # Usage:
+      #
+      #   x, y = size_to_xy("10x20")
+      def size_to_xy(size)
+        self.class.size_to_xy size
+      end
+      
+      # Scale the image, respecting aspect ratio.  
+      # Operation will happen in the main <tt>@image</tt> unless you supply the +img+ argument
+      # to operate on instead.
+      def scale(size, img = @image)
+        img.change_geometry!(size_to_xy(size).join('x')) do |cols, rows, _img|
+          cols = 1 if cols < 1
+          rows = 1 if rows < 1
+          _img.resize!(cols, rows)
+        end
+      end
+      
+      # Scale to the desired size and crop edges off to get the exact dimensions needed.
+      # Operation will happen in the main <tt>@image</tt> unless you supply the +img+ argument
+      # to operate on instead.
+      def scale_and_crop(size, img = @image)
+        img.crop_resized!(*size_to_xy(size))
+      end
+      
+      # Resize the image, with no respect to aspect ratio.  
+      # Operation will happen in the main <tt>@image</tt> unless you supply the +img+ argument
+      # to operate on instead.
+      def stretch(size, img = @image)
+        img.resize!(*size_to_xy(size))
+      end
+      
+      # Convert a symbol to an RMagick blending mode.
+      # 
+      # The blending mode governs how the overlay gets composited onto the image.  You can 
+      # get some funky effects with modes like :+copy_cyan+ or :+screen+.  For a full list of blending
+      # modes checkout the RMagick documentation (http://www.simplesystems.org/RMagick/doc/constants.html#CompositeOperator).
+      # To use a blend mode remove the +CompositeOp+ form the name and "unserscorize" the rest.  For instance,
+      # +MultiplyCompositeOp+ becomes :+multiply+, and +CopyBlackCompositeOp+ becomes :+copy_black+.
+      def symbol_to_blending_mode(mode)
+        "Magick::#{mode.to_s.camelize}CompositeOp".constantize
+      rescue NameError
+        raise ArgumentError, ":#{mode} is not a valid blending mode."
+      end
+      
+      def symbol_to_gravity(gravity_name)
+        gravity = GRAVITIES[gravity_name]
+        
+        if gravity
+          gravity
+        else
+          raise ArgumentError, ":#{gravity_name} is not a valid gravity name.\n\nValid names are :center, :top, :top_right, :right, :bottom_right, :bottom, :bottom_left, :left, :top_left"
+        end
+      end
+      
+        
+    end # Base
+    
+    # Conversion table for mapping alignment symbols to their equivalent RMagick gravity constants.
+    GRAVITIES = {
+      :center       => Magick::CenterGravity,
+      :top          => Magick::NorthGravity,
+      :top_right    => Magick::NorthEastGravity,
+      :right        => Magick::EastGravity,
+      :bottom_right => Magick::SouthEastGravity,
+      :bottom       => Magick::SouthGravity,
+      :bottom_left  => Magick::SouthWestGravity,
+      :left         => Magick::WestGravity,
+      :top_left     => Magick::NorthWestGravity,
+    } unless defined?(GRAVITIES)
+    
+  end # Operator
+end # Fleximage

data/lib/fleximage/operator/border.rb

@@ -0,0 +1,50 @@
+module Fleximage
+  module Operator
+        
+    # Add a border to the outside of the image
+    #
+    #   image.border(options = {})
+    # 
+    # Use the following keys in the +options+ hash:
+    #
+    # * +size+: Width of the border on each side.  You can use a 2 dimensional value ('5x10') if you want
+    #   different widths for the sides and top borders, but a single integer will apply the same border on 
+    #   all sides.
+    #   
+    # * +color+: the color of the border. Use an RMagick named color or use the +color+ method in 
+    #   FlexImage::Controller, or a Magick::Pixel object.
+    #   
+    # Example:
+    #   
+    #   @photo.operate do |image|
+    #     # Defaults
+    #     image.border(
+    #       :size  => 10,
+    #       :color => 'white'    # or color(255, 255, 255)
+    #     )
+    #     
+    #     # Big, pink and wide
+    #     image.border(
+    #       :size  => '200x100',
+    #       :color => color(255, 128, 128)
+    #     )
+    #   end
+    class Border < Operator::Base
+      def operate(options = {})
+        options = options.symbolize_keys if options.respond_to?(:symbolize_keys)
+        defaults = {
+          :size => '10',
+          :color => 'white'
+        }
+        options = options.is_a?(Hash) ? defaults.update(options) : defaults
+        
+        # Get border size
+        options[:size] = size_to_xy(options[:size])
+
+        # apply border
+        @image.border!(options[:size][0], options[:size][1], options[:color])
+      end
+    end
+    
+  end
+end

data/lib/fleximage/operator/crop.rb

@@ -0,0 +1,58 @@
+module Fleximage
+  module Operator
+    
+    # Crops the image without doing any resizing first.  The operation crops from the :+from+ coordinate,
+    # and returns an image of size :+size+ down and right from there.
+    # 
+    #   image.crop(options = {})
+    #
+    # Use the following keys in the +options+ hash:
+    #
+    # * +gravity+: Select gravity for the crop. Default is :top_left (Magick::NorthWestGravity)
+    #   Choose from GRAVITITES constant defined in base.rb.
+    # * +from+: coorinates for the upper left corner of resulting image.
+    # * +size+: The size of the resulting image, going down and to the right of the :+from+ coordinate.
+    # 
+    #  size and from options are *required*.
+    #
+    # Example:
+    #
+    #   @photo.operate do |image|
+    #     image.crop(
+    #       :from => '100x50',
+    #       :size => '500x350'
+    #     )
+    #   end
+    #
+    # or
+    #
+    #   @photo.operate do |image|
+    #     image.crop(
+    #       :gravity => :center,
+    #       :from    => '100x50',
+    #       :size    => '500x350'
+    #     )
+    #   end
+    class Crop < Operator::Base
+      def operate(options = {})
+        options = options.symbolize_keys
+        options.reverse_merge!(:gravity => :top_left)
+
+        # required integer keys
+        [:from, :size].each do |key|
+          raise ArgumentError, ":#{key} must be included in crop options" unless options[key]
+          options[key] = size_to_xy(options[key])
+        end
+
+        # width and height must not be zero
+        options[:size].each do |dimension|
+          raise ArgumentError, ":size must not be zero for X or Y" if dimension.zero?
+        end
+
+        # crop
+        @image.crop!(symbol_to_gravity(options[:gravity]), options[:from][0], options[:from][1], options[:size][0], options[:size][1], true)
+      end
+    end
+    
+  end
+end

data/lib/fleximage/operator/image_overlay.rb

@@ -0,0 +1,85 @@
+module Fleximage
+  module Operator
+    
+    # Adds an overlay to the base image.  It's useful for things like attaching a logo,
+    # watermark, or even a border to the image.  It will work best with a 24-bit PNG with
+    # alpha channel since it will properly deal with partial transparency.
+    # 
+    #   image.resize(image_overlay_path, options = {})
+    # 
+    # +image_overlay_path+ is the path, relative to +RAILS_ROOT+ where the image you want superimposed
+    # can be found.
+    # 
+    # Use the following keys in the +options+ hash:
+    # 
+    # * +size+: The size of the overlayed image, as <tt>'123x456'</tt> or <tt>[123, 456]</tt>.  
+    #   By default the overlay is not resized before compositing.
+    #   Use this options if you want to resize the overlay, perhaps to have a small
+    #   logo on thumbnails and a big logo on full size images.  Other than just numerical dimensions, the
+    #   size parameter takes 2 special values :+scale_to_fit+ and :+stretch_to_fit+.  :+scale_to_fit+ will 
+    #   make the overlay fit as 
+    #   much as it can inside the image without changing the aspect ratio.  :+stretch_to_fit+
+    #   will make the overlay the exact same size as the image but with a distorted aspect ratio to make
+    #   it fit.  :+stretch_to_fit+ is designed to add border to images.
+    # 
+    # * +alignment+: A symbol that tells Fleximage where to put the overlay.  Can be any of the following:
+    #   <tt>:center, :top, :top_right, :right, :bottom_right, :bottom, :bottom_left, :left, :top_left</tt>.
+    #   Default is :+center+
+    # 
+    # * +offset+: the number of pixels to offset the overlay from it's :+alignment+ anchor, in 
+    #   <tt>'123x456'</tt> or <tt>[123, 456]</tt> format.  Useful to give a bit a space between your logo 
+    #   and the edge of the image, for instance.
+    #   *NOTE:* Due to some unexpected (buggy?) RMagick behaviour :+offset+ will work strangely
+    #   if :+alignment+ is set to a non-corner value, such as :+top+ or :+center+.  Using :+offset+ in
+    #   these cases will force the overlay into a corner anyway.
+    # 
+    # * +blending+: The blending mode governs how the overlay gets composited onto the image.  You can 
+    #   get some funky effects with modes like :+copy_cyan+ or :+screen+.  For a full list of blending
+    #   modes checkout the RMagick documentation (http://www.simplesystems.org/RMagick/doc/constants.html#CompositeOperator).
+    #   To use a blend mode remove the +CompositeOp+ form the name and "unserscorize" the rest.  For instance,
+    #   +MultiplyCompositeOp+ becomes :+multiply+, and +CopyBlackCompositeOp+ becomes :+copy_black+.
+    #
+    # Example:
+    # 
+    #   @photo.operate do |image|
+    #     image.image_overlay('images/my_logo_with_alpha.png',
+    #       :size => '25x25',
+    #       :alignment => :top_right,
+    #       :blending => :screen
+    #     )
+    #   end
+    class ImageOverlay < Operator::Base
+      def operate(image_overlay_path, options = {})
+        options = options.symbolize_keys
+      
+        #load overlay
+        overlay = Magick::Image.read(image_overlay_path).first
+      
+        #resize overlay
+        if options[:size]
+          if options[:size] == :scale_to_fit || options[:size] == :stretch_to_fit
+            x, y = @image.columns, @image.rows
+          else
+            x, y = size_to_xy(options[:size])
+          end
+        
+          method = options[:size] == :stretch_to_fit ? :stretch : :scale
+          send(method, [x, y], overlay)
+        end
+      
+        #prepare arguments for composite!
+        args = []
+        args << overlay                                               #overlay image
+        args << symbol_to_gravity(options[:alignment] || :center)     #gravity
+        args += size_to_xy(options[:offset]) if options[:offset]      #offset
+        args << symbol_to_blending_mode(options[:blending] || :over)  #compositing mode
+        
+        #composite
+        @image.composite!(*args)
+      
+        return @image
+      end
+    end
+    
+  end
+end

data/lib/fleximage/operator/resize.rb

@@ -0,0 +1,92 @@
+module Fleximage
+  module Operator
+        
+    # Resize this image, constraining proportions.  Options allow cropping, stretching, upsampling and
+    # padding.
+    # 
+    #   image.resize(size, options = {})
+    # 
+    # +size+ is size of the output image after the resize operation.  Accepts either <tt>'123x456'</tt>
+    # format or <tt>[123, 456]</tt> format.
+    #
+    # Use the following keys in the +options+ hash:
+    #   
+    # * +crop+: pass true to this option to make the ouput image exactly 
+    #   the same dimensions as +size+.  The default behaviour will resize the image without
+    #   cropping any part meaning the image will be no bigger than the +size+.  When <tt>:crop</tt>
+    #   is true the final image is resized to fit as much as possible in the frame, and then crops it 
+    #   to make it exactly the dimensions declared by the +size+ argument.
+    #  
+    # * +upsample+: By default the image will never display larger than its original dimensions, 
+    #   no matter how large the +size+ argument is.  Pass +true+ to use this option to allow
+    #   upsampling, disabling the default behaviour.
+    #
+    # * +padding+: This option will pad the space around your image with a solid color to make it exactly the requested
+    #   size.  Pass +true+, for the default of +white+, or give it a text or pixel color like <tt>"red"</tt> or 
+    #   <tt>color(255, 127, 0)</tt>.  This is like the opposite of the +crop+ option.  Instead of trimming the 
+    #   image to make it exactly the requested size, it will make sure the entire image is visible, but adds space 
+    #   around the edges to make it the right dimensions.
+    #
+    # * +stretch+: Set this option to true and the image will not preserve its aspect ratio.  The final image will
+    #   stretch to fit the requested +size+.  The resulting image is exactly the size you ask for.
+    # 
+    # Example:
+    # 
+    #   @photo.operate do |image|
+    #     image.resize '200x200', :crop => true
+    #   end
+    class Resize < Operator::Base
+      def operate(size, options = {})
+        options = options.symbolize_keys
+        
+        # Find dimensions
+        x, y = size_to_xy(size)
+
+        # prevent upscaling unless :usample param exists.
+        unless options[:upsample]
+          x = @image.columns if x > @image.columns
+          y = @image.rows    if y > @image.rows
+        end
+
+        # Perform image resize
+        case
+        when options[:crop] && !options[:crop].is_a?(Hash) && @image.respond_to?(:crop_resized!)
+          # perform resize and crop
+          scale_and_crop([x, y])
+
+        when options[:stretch]
+          # stretch the image, ignoring aspect ratio
+          stretch([x, y])
+
+        else
+          # perform the resize without crop
+          scale([x, y])
+
+        end
+
+        # apply padding if necesary
+        if padding_color = options[:padding]
+          # get color
+          padding_color = 'white' if padding_color == true
+
+          # get original x and y.  This makes it play nice if the requested size is larger 
+          # than the image and upsampling is not allowed.
+          x, y = size_to_xy(size)
+
+          # get proper border sizes
+          x_border = [0, (x - @image.columns + 1) / 2].max
+          y_border = [0, (y - @image.rows    + 1) / 2].max
+
+          # apply padding
+          @image.border!(x_border, y_border, padding_color)
+
+          # crop to remove possible extra pixel
+          @image.crop!(0, 0, x, y, true)
+        end
+        
+        return @image
+      end
+    end
+    
+  end
+end