smartcropper 0.6.0

data/README.md

@@ -0,0 +1,60 @@
+# croptoelie
+
+Content aware cropping.
+
+Crops images based on entropy: leaving the most interesting part intact.
+
+Don't expect this to be a replacement for human cropping, it is an algorythm and not an extremely smart one at that :).
+
+Best results achieved in combination with scaling: the cropping is then only used to square the image, cutting off the least interesting part. 
+The trimming simply chops off te edge that is least interesting, and continues doing so, untill it reached the requested size.
+
+## Usage
+
+Use it in [carrierwave][1], in a custom `manipulate!` block. For example, carrierwave in a Rails project:
+
+File *uploaders/attachement_uploader.rb*: 
+
+    def smart_crop_and_scale(width, height)
+      manipulate! do |img|
+        img = CropToelie.new(img)
+        img = img.smart_crop_and_scale(width, height)
+        img = yield(img) if block_given?
+        img
+      end
+    end
+
+    # Create different versions of your uploaded files:
+    version :thumb do
+      process :smart_crop_and_scale => [80, 80]
+    end
+
+## Contributing to croptoelie
+
+* This is one of my first more complex Ruby gems. So any help in general improvement is welcome. If you read the code and thing "OMG, what was he thinking, the answer is probably 'I wasn't'". Feel free to tell me so.
+* RMagick is not the cleanest and leanest of all image-manipulation libraries in Ruby, but it was the only one where I found enough documentation and that had the features I needed (such as histograms). If you have better ideas, feel free to tell me them.
+* I only use this gem with [carrierwave][1], so other implementations are probably not well done. If you want to use it in any other project, please tell me what I should change to make your life easier. 
+* The integration in carrierwave should be simpler. I would love to be able to say `process :smart_crop_and_scale` instead of having to use the smartcropper as class in a custom carrierwave `manipulate!` block. My knowledge of Ruby, Carrierwave and how to get this integration done properly is limited, if you have a patch, or a suggestion, that would be great!
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Changelog
+2011-04-19: Replace crop with crop! avoids copying large chunks of images around.
+2011-04-18: Limit to N steps, instead of step_size.
+2011-04-16: Introduce tests and a profiler script, to profile performance.
+
+## Todo
+Improved algorythm: first @image.scale by F, investigate the entropy on that, most-interesting square by factor F is to-be-cropped area.
+
+## Copyright
+
+Copyright (c) 2011 Bèr Kessels. See LICENSE.txt for
+further details.
+
+[1]: https://github.com/jnicklas/carrierwave
+

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 = "smartcropper"
+  gem.homepage = "http://github.com/berkes/smartcropper"
+  gem.license = "GPL"
+  gem.summary = %Q{Content aware cropper.}
+  gem.description = %Q{Crops images based on entropy: leaving the most interesting part intact. Don't expect this to be a replacement for human cropping, it is an algorythm and not an extremely smart one at that :). Best results achieved in combination with scaling: the cropping is then only used to square the image, cutting off the least interesting part. The trimming simply chops off te edge that is least interesting, and continues doing so, untill it reached the requested size.}
+  gem.email = "ber@webschuur.com"
+  gem.authors = ["Bèr Kessels"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  
+  gem.add_runtime_dependency 'rmagick', '> 2.11.0'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "smartcropper #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.6.0

data/lib/smartcropper.rb

@@ -0,0 +1,144 @@
+require 'RMagick'
+class SmartCropper
+  include Magick
+
+  attr_accessor :orig
+  attr_accessor :steps
+
+  # Create a new SmartCropper object from a ImageList single image object.
+  #  If you want to provide a file by its path use SmartCropper.from_file('/path/to/image.png').
+  def initialize(image)
+    @image = image
+
+    # Hardcoded (but overridable) defaults.
+    @steps  = 10
+
+    # Preprocess image.
+    @image = @image.quantize
+
+    # Prepare some often-used internal variables.
+    @rows = @image.rows
+    @columns = @image.columns
+  end
+
+  # Open create a smartcropper from a file on disk.
+  def self.from_file(image_path)
+    image = ImageList.new(image_path).last
+    return SmartCropper.new(image)
+  end
+
+  # Crops an image to width x height
+  def smart_crop(width, height)
+    sq = square(width, height)
+    return @image.crop!(sq[:left], sq[:top], width, height, true)
+  end
+
+  # Squares an image (with smart_square) and then scales that to width, heigh
+  def smart_crop_and_scale(width, height)
+    smart_square
+    return @image.scale!(width, height)
+  end
+
+  # Squares an image by slicing off the least interesting parts.
+  # Usefull for squaring images such as thumbnails. Usefull before scaling.
+  def smart_square
+    if @rows != @columns #None-square images must be shaved off.
+      if @rows < @columns #landscape
+        crop_height = crop_width = @rows
+      else # portrait
+        crop_height = crop_width = @columns
+      end
+
+      sq = square(crop_width, crop_height)
+      @image.crop!(sq[:left], sq[:top], crop_width, crop_height, true)
+    end
+
+    @image
+  end
+
+  # Finds the most interesting square with size width x height.
+  #
+  # Returns a hash {:left => left, :top => top, :right => right, :bottom => bottom}
+  def square(width, height)
+    return smart_crop_by_trim(width, height)
+  end
+
+  private
+    # Determines if the image should be cropped.
+    # Image should be cropped if original is larger then requested size.
+    # In all other cases, it should not.
+    def should_crop?
+      return (@columns > @width) && (@rows < @height)
+    end
+
+    def smart_crop_by_trim(requested_x, requested_y)
+      left, top = 0, 0
+      right, bottom = @columns, @rows
+      width, height = right, bottom
+      step_size = step_size(requested_x, requested_y)
+
+      # Avoid attempts to slice less then one pixel.
+      if step_size > 0
+        # Slice from left and right edges until the correct width is reached.
+        while (width > requested_x)
+          slice_width = [(width - requested_x), step_size].min
+
+          left_entropy  = entropy_slice(@image, left, 0, slice_width, bottom)
+          right_entropy = entropy_slice(@image, (right - slice_width), 0, slice_width, bottom)
+
+          #remove the slice with the least entropy
+          if left_entropy < right_entropy
+            left += slice_width
+          else
+            right -= slice_width
+          end
+
+          width = (right - left)
+        end
+
+        # Slice from top and bottom edges until the correct height is reached.
+        while (height > requested_y)
+          slice_height = [(height - step_size), step_size].min
+
+          top_entropy    = entropy_slice(@image, 0, top, @columns, slice_height)
+          bottom_entropy = entropy_slice(@image, 0, (bottom - slice_height), @columns, slice_height)
+
+          #remove the slice with the least entropy
+          if top_entropy < bottom_entropy
+            top += slice_height
+          else
+            bottom -= slice_height
+          end
+
+          height = (bottom - top)
+        end
+      end
+
+      square = {:left => left, :top => top, :right => right, :bottom => bottom}
+    end
+
+    # Compute the entropy of an image slice.
+    def entropy_slice(image_data, x, y, width, height)
+      slice = image_data.crop(x, y, width, height)
+      entropy = entropy(slice)
+    end
+
+    # Compute the entropy of an image, defined as -sum(p.*log2(p)).
+    #  Note: instead of log2, only available in ruby > 1.9, we use
+    #  log(p)/log(2). which has the same effect.
+    def entropy(image_slice)
+      hist = image_slice.color_histogram
+      hist_size = hist.values.inject{|sum,x| sum ? sum + x : x }.to_f
+
+      entropy = 0
+      hist.values.each do |h|
+        p = h.to_f / hist_size
+        entropy += (p * (Math.log(p)/Math.log(2))) if p != 0
+      end
+      return entropy * -1
+    end
+
+    def step_size(requested_x, requested_y)
+      ((([@rows - requested_x, @columns - requested_y].max)/2)/@steps).to_i
+    end
+end

data/smartcropper.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{smartcropper}
+  s.version = "0.6.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Bèr Kessels"]
+  s.date = %q{2011-04-19}
+  s.description = %q{Crops images based on entropy: leaving the most interesting part intact. Usefull for automatic cropping or resizing of images. }
+  s.email = %q{ber@webschuur.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rvmrc",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "smartcropper.gemspec",
+    "lib/smartcropper.rb",
+  ]
+  s.homepage = %q{http://github.com/berkes/smartcropper}
+  s.licenses = ["GPL"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.5.2}
+  s.summary = %q{Content aware image cropping in Ruby and Carrierwave}
+  s.test_files = [
+    "test/helper.rb",
+    "test/profiler.rb",
+    "test/test_croptoelie.rb",
+    "test/fixtures/*"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rmagick>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_runtime_dependency(%q<rmagick>, ["> 2.11.0"])
+    else
+      s.add_dependency(%q<rmagick>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rmagick>, ["> 2.11.0"])
+    end
+  else
+    s.add_dependency(%q<rmagick>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rmagick>, ["> 2.11.0"])
+  end
+end
+

data/test/fixtures/entropyish.txt

@@ -0,0 +1 @@
+This is not an image.

data/test/helper.rb

@@ -0,0 +1,17 @@
+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 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'smartcropper'
+

data/test/profiler.rb

@@ -0,0 +1,37 @@
+require 'ruby-prof'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'smartcropper'
+
+tests = {
+  :smart_crop_by_trim => {:method => :smart_crop, :params => [100, 100]}, 
+#  :smart_crop_by_search => {:method => :smart_crop, :params => [100, 100, :by_search]},
+  :smart_crop_and_scale => {:method => :smart_crop_and_scale, :params => [100, 100]},
+  :smart_square => {:method => :smart_square, :params => []}
+}
+#result = RubyProf.profile do
+  tests.each do |id, test|
+    filename = File.join(File.expand_path(File.dirname(__FILE__)), "../doc/tyto.jpg")
+    
+    2.times do |i|
+#      result = RubyProf.profile do
+        img = SmartCropper.from_file(filename)
+        img.send(test[:method], *test[:params])
+        img = nil
+#      end
+
+  #    # Print a flat profile to text
+  #    puts "Run #{i}:\t #{id} ------------------------"
+  #    #file = File.new("./#{id}-#{i}.txt", "w")
+  #    printer = RubyProf::FlatPrinter.new(result)
+  #    printer.print(STDOUT, {:min_percent => 10})
+  #    print = nil
+    end
+  end
+#end
+#    # Print a flat profile to text
+#    puts "Run #{i}:\t #{id} ------------------------"
+#    #file = File.new("./#{id}-#{i}.txt", "w")
+#    printer = RubyProf::FlatPrinter.new(result)
+#    printer.print(STDOUT, {:min_percent => 10})
+#    print = nil

data/test/test_croptoelie.rb

@@ -0,0 +1,79 @@
+require 'helper'
+
+class TestSmartcropper < Test::Unit::TestCase
+  def setup
+    @filename = File.join(File.expand_path(File.dirname(__FILE__)), "fixtures", "entropyish.png")
+    @image    = Magick::ImageList.new(@filename).last
+
+    @twenty_twenty = Magick::ImageList.new(
+      File.join(File.expand_path(File.dirname(__FILE__)), "fixtures", "20x20.png")
+    ).last
+  end
+
+  should "initialize a smartcropper image from an ImageList item" do
+    img = SmartCropper.new(@image)
+    assert_equal(img.class, SmartCropper)
+  end
+  should "create a smartcropper from an imagefile" do
+    img = SmartCropper.from_file(@filename)
+    assert_equal(img.class, SmartCropper)
+  end
+
+  should "fail on creating a smartcropper image from a textfile" do
+    assert_raise Magick::ImageMagickError, NoMethodError do
+       SmartCropper.new(File.join(File.expand_path(File.dirname(__FILE__)), "fixtures","entropyish.txt"))
+    end
+  end
+
+  should "crop to 100x100 without scaling with smart_crop" do
+    img = SmartCropper.new(@image)
+    img = img.smart_crop(100, 100)
+    size = [img.rows, img.columns]
+    assert_equal(size, [100, 100])
+  end
+
+  should "crop to 100x100 with scaling with smart_crop_and_scale" do
+    img = SmartCropper.new(@image)
+    img = img.smart_crop_and_scale(100, 100)
+    size = [img.rows, img.columns]
+    assert_equal(size, [100, 100])
+  end
+
+  should "square image without scaling" do
+    img = SmartCropper.new(@image)
+    img = img.smart_square
+    assert_equal(img.rows, img.columns)
+  end
+
+  should "not crop small images" do
+    img = SmartCropper.new(@twenty_twenty)
+    img = img.smart_crop(100, 100)
+    size = [img.rows, img.columns]
+    assert_equal([20, 20], size)
+  end
+
+  should "still crop a slice of one pixel" do
+    img = SmartCropper.new(@twenty_twenty)
+    img = img.smart_crop(19, 19)
+    size = [img.rows, img.columns]
+    assert_equal([19, 19], size)
+  end
+
+  ###########################################################################
+  #                   Images reported to fail by issue #5                   #
+  ###########################################################################
+  [:smart_crop, :smart_crop_and_scale, :smart_square].each do |method|
+    full_path = File.join File.dirname(__FILE__), "fixtures", "errors"
+    Dir.open(full_path).select{|f| !File.directory?(f)}.each do |file|
+
+      should "'not fail on reported-as-broken image '#{file}' with '#{method}'" do
+          realpath = File.realpath(File.join full_path, file)
+
+          img = SmartCropper.new(Magick::ImageList.new(realpath).last)
+          img = img.smart_crop(200, 200)
+          size = [img.rows, img.columns]
+          assert_equal(size, [200, 200])
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: smartcropper
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+  prerelease: 
+platform: ruby
+authors:
+- Bèr Kessels
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+- !ruby/object:Gem::Dependency
+  name: rcov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+description: ! 'Crops images based on entropy: leaving the most interesting part intact.
+  Don''t expect this to be a replacement for human cropping, it is an algorythm and
+  not an extremely smart one at that :). Best results achieved in combination with
+  scaling: the cropping is then only used to square the image, cutting off the least
+  interesting part. The trimming simply chops off te edge that is least interesting,
+  and continues doing so, untill it reached the requested size.'
+email: ber@webschuur.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/smartcropper.rb
+- smartcropper.gemspec
+- test/fixtures/20x20.png
+- test/fixtures/entropyish.png
+- test/fixtures/entropyish.txt
+- test/fixtures/errors/flo-rida.png
+- test/fixtures/errors/hollywood-undead.jpg
+- test/fixtures/errors/maroon-5.jpg
+- test/fixtures/errors/yo-gotti.jpg
+- test/helper.rb
+- test/profiler.rb
+- test/test_croptoelie.rb
+homepage: http://github.com/berkes/smartcropper
+licenses:
+- GPL
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 949373039
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Content aware cropper.
+test_files:
+- test/helper.rb
+- test/profiler.rb
+- test/test_croptoelie.rb