insano_image_resizer 0.3.0

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@insano_image_resizer

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+
+group :development, :test do
+  gem 'rspec'
+  gem 'jeweler'
+  gem 'pry'
+  gem 'pry-nav'
+  gem 'pry-stack_explorer'
+end

data/Gemfile.lock

@@ -0,0 +1,45 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    binding_of_caller (0.6.7)
+    coderay (1.0.6)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    method_source (0.7.1)
+    pry (0.9.8.4)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    pry-nav (0.2.0)
+      pry (~> 0.9.8.1)
+    pry-stack_explorer (0.4.1)
+      binding_of_caller (~> 0.6.2)
+      pry (~> 0.9.8.2)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
+    slop (2.4.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  pry
+  pry-nav
+  pry-stack_explorer
+  rspec

data/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+Copyright (c) 2012 J. Benjamin Gotow
+Development sponsored by Populr, Inc
+http://www.populr.me
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+Insano Image Resizer
+====================
+
+The Insano image resizer allows you to create resized versions of images, specifying a 
+desired width and height as well as a point of interest that the resizer will keep centered
+in the frame when possible. The resizer is built on top of the VIPS command-line tool, 
+and is designed to be as fast as possible. In our tests, VIPS is faster than ImageMagick for any 
+image larger than ~300x300px, and is exponentially faster for very large images. 
+
+![A brief overview of the Insano processing function](insano_image_resizer/raw/master/samples/explanation.png)
+
+Output formats: The Insano image resizer will produce either a PNG or JPG image, depending
+on whether the source image includes transparency.
+
+* Insano is the fastest waterslide in the world. This isn't a waterslide, but it's similarly fast.
+
+Usage
+=====
+
+In your Gemfile:
+
+    gem 'insano_resizer'
+
+Example:
+
+    # Specify an existing image in any format supported by VIPS
+    input_path = 'samples/test.jpg'
+
+    # Create a new instance of the Image processor
+    processor = ImageResizer::Processor.new
+    
+    # Process the image, creating a temporary file.
+    output_path = processor.process(input_path, {w: 100, h: 200}, {x:986, y:820, region: 0.5})
+    
+    # Move the image to an output path
+    FileUtils.mv(output_path, 'samples/output/test.jpg')
+
+Input parameters:
+
+The `process` method is the main function of the Insano gem. Using different parameters,
+you can produce a wide range of resized images. Each of the parameters is explained below. 
+
+The first argument is an input file path. Because the Insano image resizer uses the VIPS
+command line, it is not possible to transform an image that has been loaded into memory.
+
+The second argument is a viewport hash containing width and height keys.
+You can specify both width and height to produce an output image of a specific size, or provide
+only width or height to have the resizer compute the other dimension based
+on the aspect ratio of the image. Finally, you can pass an empty hash to use 
+the current width and height of the image. Note that the image resizer will
+never distort an image: the output image will always fill the viewport you provide,
+scaling up only if absolutely necessary.
+
+The third parameter is the point of interest that you'd like to keep centered if possible.
+Imagine that an 4:3 image contains a person's face on the left side. When you create a 
+square thumbnail of the image, the persons face is half chopped off, because the processor
+trims off the left and right uniformly. Specifying a point of interest allows you to correct
+for this problem. 
+
+By default, the POI is used only when cropping the image and deciding which sides 
+should be cropped off. However, specifying the optional :region parameter with a value 
+less than 1, you can make the image resizer zoom in around the POI, cropping the image 
+so that an area of size (region * image size) around the POI is visible. 
+
+Note that the output image may show more of the source image than you specify using the
+interest region. The region is only meant to indicate what region you'd like to ensure makes
+it into the output. For example, if you have a 200 x 200px image and request an output image of 
+100 x 100px, showing the 50px region around 150px x 150px, the output will contain more than
+just that region, since filling a 100px square with a 50px region would require enlarging the 
+source image.
+
+Credits
+=======
+
+This project is loosely based off of the ImageResizer gem previously authored by Daniel Nelson of Populr.me.
+It draws heavily on the VIPS im_affinei command line function to resize images using an affine transform.
+

data/Rakefile

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "insano_image_resizer"
+  gem.homepage = "http://github.com/populr/insano_image_resizer"
+  gem.license = "MIT"
+  gem.summary = %Q{An image resizing gem that calls through to VIPS on the command line.}
+  gem.description = %Q{An image resizing gem that generates smaller versions of requested 
+                    images. Calls through to VIPS on the command line to perform processing,
+                    and automatically handles cropping and scaling the requested image, taking
+                    a point of interest into account if requested.}
+  gem.email = "ben@populr.me"
+  gem.authors = ["Ben Gotow"]
+  # dependencies defined in Gemfile
+  gem.files.exclude 'spec'
+  gem.files.exclude 'samples'
+  gem.files.exclude 'tmp'
+  gem.files.exclude 'demo.rb'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "image_resizer #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/image_resizer/configurable.rb

@@ -0,0 +1,206 @@
+module ImageResizer
+  module Configurable
+
+    # Exceptions
+    class NotConfigured < RuntimeError; end
+    class BadConfigAttribute < RuntimeError; end
+
+    def self.included(klass)
+      klass.class_eval do
+        include Configurable::InstanceMethods
+        extend Configurable::ClassMethods
+      end
+    end
+
+    class DeferredBlock # Inheriting from Proc causes errors in some versions of Ruby
+      def initialize(blk)
+        @blk = blk
+      end
+
+      def call
+        @blk.call
+      end
+    end
+
+    module InstanceMethods
+
+      def configure(&block)
+        yield ConfigurationProxy.new(self)
+        self
+      end
+
+      def configure_with(config, *args, &block)
+        config = saved_config_for(config) if config.is_a?(Symbol)
+        config.apply_configuration(self, *args)
+        configure(&block) if block
+        self
+      end
+
+      def has_config_method?(method_name)
+        config_methods.include?(method_name.to_sym)
+      end
+      
+      def configuration
+        @configuration ||= {}
+      end
+            
+      def config_methods
+        @config_methods ||= self.class.config_methods.dup
+      end
+      
+      def default_configuration
+        @default_configuration ||= self.class.default_configuration.dup
+      end
+
+      def set_config_value(key, value)
+        configuration[key] = value
+        child_configurables.each{|c| c.set_if_unset(key, value) }
+        value
+      end
+      
+      def use_as_fallback_config(other_configurable)
+        other_configurable.add_child_configurable(self)
+        self.fallback_configurable = other_configurable
+      end
+
+      protected
+
+      def add_child_configurable(obj)
+        child_configurables << obj
+        config_methods.push(*obj.config_methods)
+        fallback_configurable.config_methods.push(*obj.config_methods) if fallback_configurable
+      end
+
+      def set_if_unset(key, value)
+        set_config_value(key, value) unless set_locally?(key)
+      end
+
+      private
+      
+      attr_accessor :fallback_configurable
+      
+      def child_configurables
+        @child_configurables ||= []
+      end
+      
+      def set_locally?(key)
+        instance_variable_defined?("@#{key}")
+      end
+      
+      def default_value(key)
+        if default_configuration[key].is_a?(DeferredBlock)
+          default_configuration[key] = default_configuration[key].call
+        end
+        default_configuration[key]
+      end
+
+      def saved_configs
+        self.class.saved_configs
+      end
+
+      def saved_config_for(symbol)
+        config = saved_configs[symbol]
+        if config.nil?
+          raise ArgumentError, "#{symbol.inspect} is not a known configuration - try one of #{saved_configs.keys.join(', ')}"
+        end
+        config = config.call if config.respond_to?(:call)
+        config
+      end
+
+    end
+
+    module ClassMethods
+
+      def default_configuration
+        @default_configuration ||= configurable_ancestors.reverse.inject({}) do |default_config, klass|
+          default_config.merge!(klass.default_configuration)
+          default_config
+        end
+      end
+
+      def config_methods
+        @config_methods ||= configurable_ancestors.inject([]) do |conf_methods, klass|
+          conf_methods |= klass.config_methods
+          conf_methods
+        end
+      end
+
+      def nested_configurables
+        @nested_configurables ||= []
+      end
+
+      def register_configuration(name, config=nil, &config_in_block) 
+        saved_configs[name] = config_in_block || config
+      end
+
+      def saved_configs
+        @saved_configs ||= {}
+      end
+
+      def configurable_ancestors
+        @configurable_ancestors ||= ancestors.select{|a| a.included_modules.include?(Configurable) } - [self]
+      end
+
+      private
+
+      def configurable_attr attribute, default=nil, &blk
+        default_configuration[attribute] = blk ? DeferredBlock.new(blk) : default
+
+        # Define the reader
+        define_method(attribute) do
+          configuration.has_key?(attribute) ? configuration[attribute] : default_value(attribute)
+        end
+
+        # Define the writer
+        define_method("#{attribute}=") do |value|
+          instance_variable_set("@#{attribute}", value)
+          set_config_value(attribute, value)
+        end
+
+        configuration_method attribute
+        configuration_method "#{attribute}="
+      end
+
+      def configuration_method(*method_names)
+        config_methods.push(*method_names.map{|n| n.to_sym }).uniq!
+      end
+      
+      def nested_configurable(*method_names)
+        nested_configurables.push(*method_names)
+      end
+
+    end
+
+    class ConfigurationProxy
+
+      def initialize(owner)
+        @owner = owner
+      end
+
+      def method_missing(method_name, *args, &block)
+        if owner.has_config_method?(method_name)
+          attribute = method_name.to_s.tr('=','').to_sym
+          if method_name.to_s =~ /=$/ && owner.has_config_method?(attribute) # a bit hacky - if it has both getter and setter, assume it's a configurable_attr
+            owner.set_config_value(attribute, args.first)
+          else
+            owner.send(method_name, *args, &block)
+          end
+        elsif nested_configurable?(method_name)
+          owner.send(method_name)
+        else
+          raise BadConfigAttribute, "You tried to configure using '#{method_name.inspect}',  but the valid config attributes are #{owner.config_methods.map{|a| %('#{a.inspect}') }.sort.join(', ')}"
+        end
+      end
+
+      private
+
+      attr_reader :owner
+
+      def nested_configurable?(method)
+        owner.class.nested_configurables.include?(method.to_sym)
+      end
+
+    end
+
+  end
+end

data/lib/image_resizer/loggable.rb

@@ -0,0 +1,28 @@
+require 'logger'
+
+module ImageResizer
+  module Loggable
+
+    def log
+      case @log_object
+      when nil
+        @log_object = Logger.new($stdout)
+      when Proc
+        @log_object[]
+      when Logger
+        @log_object
+      end
+    end
+
+    def log=(object)
+      @log_object = object
+    end
+
+    attr_reader :log_object
+
+    def use_same_log_as(object)
+      self.log = proc{ object.log }
+    end
+
+  end
+end

data/lib/image_resizer/processor.rb

@@ -0,0 +1,199 @@
+require 'yaml'
+require 'shellwords'
+
+module ImageResizer
+  class Processor
+
+    include Configurable
+    include Shell
+    include Loggable
+    
+    def process(input_path, viewport_size = {}, interest_point = {})
+      input_properties = fetch_image_properties(input_path)
+      input_has_alpha = (input_properties["bands"] == 4)
+
+      output_tmp = Tempfile.new(["img", input_has_alpha ? ".png" : ".jpg"])
+
+      transform = calculate_transform(input_path, input_properties, viewport_size, interest_point)
+      run_transform(input_path, output_tmp.path, transform)
+
+      return output_tmp.path
+    end
+
+    def fetch_image_properties(input_path)
+      # read in the image headers to discover the width and height of the image.
+      # There's actually some extra metadata we ignore here, but this seems to be
+      # the only way to get width and height from VIPS.
+      result = run("vips im_printdesc '#{input_path}'")
+
+      # for some reason, the response isn't just YAML. It's one line of text in parenthesis 
+      # followed by YAML. Let's chop off the first line to get to the good stuff.
+      result = result[(result.index(')') + 2)..-1]
+      return YAML::load(result)
+    end
+
+    def calculate_transform(input_path, input_properties, viewport_size, interest_point)
+
+      # Pull out the properties we're interested in
+      image_size = {w: input_properties["width"].to_f, h: input_properties["height"].to_f}
+
+      # By default, the interest size is 30% of the total image size.
+      # In the future, this could be a parameter, and you'd pass the # of pixels around
+      # the POI you are interested in.
+      if (interest_point[:xf])
+        interest_point[:x] = image_size[:w] * interest_point[:xf]
+      end
+      
+      if (interest_point[:yf])
+        interest_point[:y] = image_size[:h] * interest_point[:yf]
+      end
+
+      if (interest_point[:region] == nil)
+        interest_point[:region] = 1
+      end
+
+      if (interest_point[:x] == nil)
+        interest_point[:x] = image_size[:w] * 0.5
+        interest_point[:region] = 1
+      end
+      if (interest_point[:y] == nil)
+        interest_point[:y] = image_size[:h] * 0.5
+        interest_point[:region] = 1
+      end
+
+      interest_size = {w: image_size[:w] * interest_point[:region], h: image_size[:h] * interest_point[:region]}
+
+      # Has the user specified both the width and the height of the viewport? If they haven't,
+      # let's go ahead and fill in the missing properties for them so that they get output at 
+      # the original aspect ratio of the image.
+      if ((viewport_size[:w] == nil) && (viewport_size[:h] == nil))
+        viewport_size = {w: input_properties["width"], h: input_properties["height"]}
+      
+      elsif (viewport_size[:w] == nil)
+        viewport_size[:w] = viewport_size[:h] * (input_properties["width"] / input_properties["height"])
+
+      elsif (viewport_size[:h] == nil)
+        viewport_size[:h] = viewport_size[:w] * (input_properties["height"] / input_properties["width"])
+      end
+
+      # how can we take our current image and fit it into the viewport? Time for
+      # some fun math! First, let's determine a scale such that the image fits
+      # within the viewport. There are a few rules we want to apply:
+      # 1) The image should _always_ fill the viewport.
+      # 2) The 1/3 of the image around the interest_point should always be visible.
+      #    This means that if we try to cram a massive image into a tiny viewport,
+      #    we won't get a simple scale-to-fill. We'll get a more zoomed-in version
+      #    showing just the 1/3 around the interest_point.
+
+      scale_to_fill = [viewport_size[:w] / image_size[:w], viewport_size[:h] / image_size[:h]].max
+      
+      scale_to_interest = [interest_size[:w] / image_size[:w], interest_size[:h] / image_size[:h]].max
+
+      log.debug("POI: ")
+      log.debug(interest_point)
+      log.debug("Image size: ")
+      log.debug(image_size)
+      log.debug("Requested viewport size: ")
+      log.debug(viewport_size)
+      log.debug("scale_to_fill: %f" % scale_to_fill)
+      log.debug("scale_to_interest: %f" % scale_to_interest)
+
+
+      scale_for_best_region = [scale_to_fill, scale_to_interest].max
+
+      # cool! Now, let's figure out what the content offset within the image should be.
+      # We want to keep the point of interest in view whenever possible. First, let's 
+      # compute an optimal frame around the POI:
+      best_region = {x: interest_point[:x].to_f - (image_size[:w] * scale_for_best_region) / 2, 
+                     y: interest_point[:y].to_f - (image_size[:h] * scale_for_best_region) / 2,
+                     w: image_size[:w] * scale_for_best_region,
+                     h: image_size[:h] * scale_for_best_region}
+      
+      # Up to this point, we've been using 'scale_for_best_region' to be the preferred scale of the image. 
+      # So, scale could be 1/3 if we want to show the area around the POI, or 1 if we're fitting a whole image
+      # in a viewport that is exactly the same aspect ratio.
+
+      # The next step is to compute a scale that should be applied to the image to make this desired section of 
+      # the image fit within the viewport. This is different from the previous scale—if we wanted to fit 1/3 of
+      # the image in a 100x100 pixel viewport, we computed best_region using that 1/3, and now we need to find
+      # the scale that will fit it into 100px.
+      scale = [scale_to_fill, viewport_size[:w] / best_region[:w], viewport_size[:h] / best_region[:h]].max
+
+      # Next, we scale the best_region so that it is in final coordinates. When we perform the affine transform, 
+      # it will SCALE the entire image and then CROP it to a region, so our transform rect needs to be in the 
+      # coordinate space of the SCALED image, not the initial image.
+      transform = {}
+      transform[:x] = best_region[:x] * scale
+      transform[:y] = best_region[:y] * scale
+      transform[:w] = best_region[:w] * scale
+      transform[:h] = best_region[:h] * scale
+      transform[:scale] = scale
+
+      # transform now represents the region we'd like to have in the final image. All of it, or part of it, may
+      # not actually be within the bounds of the image! We're about to apply some constraints, but first let's 
+      # trim the best_region so that it's the SHAPE of the viewport, not just the SCALE of the viewport. Remember,
+      # since the region is still centered around the POI, we can just trim equally on either the W or H as necessary.
+      transform[:x] -= (viewport_size[:w] - transform[:w]) / 2
+      transform[:y] -= (viewport_size[:h] - transform[:h]) / 2
+      transform[:w] = viewport_size[:w]
+      transform[:h] = viewport_size[:h]
+
+      # alright—now our transform most likely extends beyond the bounds of the image
+      # data. Let's add some constraints that push it within the bounds of the image.
+      if (transform[:x] + transform[:w] > image_size[:w] * scale)
+        transform[:x] = image_size[:w] * scale - transform[:w]
+      end
+
+      if (transform[:y] + transform[:h] > image_size[:h] * scale)
+        transform[:y] = image_size[:h] * scale - transform[:h]
+      end
+
+      if (transform[:x] < 0)
+        transform[:x] = 0.0
+      end
+
+      if (transform[:y] < 0)
+        transform[:y] = 0.0
+      end
+
+      log.debug("The transform properties:")
+      log.debug(transform)
+
+      return transform
+    end
+
+    def run_transform(input_path, output_path, transform)
+      # Call through to VIPS:
+      # int im_affinei(in, out, interpolate, a, b, c, d, dx, dy, x, y, w, h)
+      # The first six params are a transformation matrix. A and D are used for X and Y
+      # scale, the other two are b = Y skew and c = X skew.  TX and TY are translations
+      # but don't seem to be used.
+      # The last four params define a rect of the source image that is transformed.
+      log.debug(output_path[-3..-1])
+
+      if ((transform[:scale] < 0.5) && (output_path[-3..-1] == "jpg"))
+        scale = transform[:scale]
+        size = [transform[:w], transform[:h]].max
+
+        transform[:scale] = scale * 2
+        transform[:x] *= 2
+        transform[:y] *= 2
+        transform[:w] *= 2
+        transform[:h] *= 2
+
+
+        log.debug("Using two-pass transform")
+        run("vips im_affinei '#{input_path}' '#{output_path}' bilinear #{transform[:scale]} 0 0 #{transform[:scale]} 0 0 #{transform[:x]} #{transform[:y]} #{transform[:w]} #{transform[:h]}")
+        run("vipsthumbnail -s #{size} --nosharpen -o '%s_thumb.jpg:65' '#{output_path}'")
+        FileUtils.mv(output_path[0..-5]+"_thumb.jpg", output_path)
+
+      else 
+        run("vips im_affinei '#{input_path}' '#{output_path}' bilinear #{transform[:scale]} 0 0 #{transform[:scale]} 0 0 #{transform[:x]} #{transform[:y]} #{transform[:w]} #{transform[:h]}")
+
+      end
+
+      return output_path
+    end
+  end
+end
+