imagery 0.0.6 → 0.2.0

data/README.markdown

@@ -1,8 +1,6 @@
 Imagery
 =======
 
-(See documentation at [http://labs.sinefunc.com/imagery/doc](http://labs.sinefunc.com/imagery/doc))
-
 ## Image manipulation should be simple. It should be customizable. It should allow for flexibility. Imagery attempts to solve these.
 
 ### Imagery favors:
@@ -14,13 +12,13 @@ Imagery
 
 1. Simplicity and Explicitness
 ------------------------------
-To get started using Imagery you only need ImageMagick, ruby and Imagery of 
+To get started using Imagery you only need GraphicsMagick, ruby and Imagery of 
 course.
     
     # on debian based systems
-    sudo apt-get install imagemagick
-    # or maybe using macports
-    sudo port install ImageMagick
+    sudo apt-get install graphicsmagick
+    # or maybe using homebrew
+    brew install graphicsmagick
     [sudo] gem install imagery
 
 Then you may proceed using it.
@@ -28,28 +26,13 @@ Then you may proceed using it.
     require 'rubygems'
     require 'imagery'
 
-    Photo = Class.new(Struct.new(:id))
-    
-    i = Imagery.new(Photo.new(1001))
-    i.root = '/some/path/here'
-    i.sizes = { :thumb => ["48x48^", "48x48"], :large => ["480x320"] }
+    i = Imagery.new(:photo, "1001", thumb: ["48x48^", "48x48"])
     i.save(File.open('/some/path/to/image.jpg'))
 
-    File.exist?('/some/path/here/public/system/photo/1001/thumb.png')
-    # => true
-
-    File.exist?('/some/path/here/public/system/photo/1001/large.png')
+    File.exist?('public/photo/1001/thumb.jpg')
     # => true
 
-    File.exist?('/some/path/here/public/system/photo/1001/original.png')
-    # => true
-
-    # the defaut is to use the .id and the name of the class passed,
-    # but you can specify a different scheme.
-
-    i = Imagery.new(Photo.new(1001), `uuidgen`.strip, "photos")
-    i.root = '/some/path/here'
-    i.file == '/some/path/here/public/system/photos/1c2030a6-6bfa-11df-8997-67a71f1f84c7/original.png'
+    File.exist?('public/photo/1001/original.jpg')
     # => true
 
 2. OOP Principles (that we already know)
@@ -57,9 +40,6 @@ Then you may proceed using it.
 
 ### Ohm example (See [http://ohm.keyvalue.org](http://ohm.keyvalue.org))
     
-    # Imagery will use ROOT_DIR if its available
-    ROOT_DIR = "/u/apps/site/current"
-
     class User < Ohm::Model
       include Ohm::Callbacks
       
@@ -70,15 +50,14 @@ Then you may proceed using it.
       end
 
       def avatar
-        @avatar ||= 
-          Imagery.new(self).tap do |i|
-            i.sizes = { :thumb => ["48x48^", "48x48"], :medium => ["120x120"] }
-          end
+        Imagery.new :avatar, id, 
+          :thumb => ["48x48^", "48x48"],
+          :medium => ["120x120"]
       end
 
     protected
       def write_avatar
-        avatar.save(@avatar_fp[:tempfile])  if @avatar_fp
+        avatar.save(@avatar_fp[:tempfile]) if @avatar_fp
       end
     end
 
@@ -89,31 +68,30 @@ Then you may proceed using it.
       attribute :height
 
       def photo
-        @photo ||= 
-          Imagery.new(self).tap do |i|
-            i.sizes = { :thumb => ["%sx%s" % [width, height]] }
-          end
+        Imagery.new :photo, id, :thumb => ["%sx%s" % [width, height]]
       end
     end
     
     # For cases where we want to use S3 for some and normal filesystem for others
-    class S3Photo < Imagery::Model
+    class S3Photo < Imagery
       include Imagery::S3
-      s3_bucket 'my-bucket'
+
+      s3_bucket "my-bucket"
     end
 
     # then maybe some other files are using cloudfront
-    class CloudfrontPhoto < Imagery::Model
+    class CloudfrontPhoto < Imagery
       include Imagery::S3
-      s3_bucket 'my-bucket'
-      s3_distribution_domain 'assets.site.com'
+
+      s3_bucket "my-bucket"
+      s3_distribution_domain "assets.site.com"
     end
 
     # some might be using S3 EU, in which case you can specify the s3_host
     class CustomS3Host < Imagery::Model
       include Imagery::S3
-      s3_host 'http://my.custom.host'
-      s3_bucket 'my-bucket-name'
+      s3_host "http://my.custom.host"
+      s3_bucket "my-bucket-name"
     end
 
 3. Flexibility and Extensibility
@@ -131,21 +109,18 @@ The access credentials are assumed to be stored in
 you can do this by setting it on your .bash_profile / .bashrc or just
 manually setting them somewhere in your appication
 
-    ENV["AMAZON_ACCESS_KEY_ID"] = '_access_key_id_'
-    ENV["AMAZON_SECRET_ACCESS_KEY"] = '_secret_access_key_'
+    ENV["AMAZON_ACCESS_KEY_ID"] = "_access_key_id_"
+    ENV["AMAZON_SECRET_ACCESS_KEY"] = "_secret_access_key_"
 
 Now you can just start using it:
   
-    Photo = Class.new(Struct.new(:id))
-
-    class Imagery::Model
+    class Imagery
       include Imagery::S3
-      s3_bucket 'my-bucket'
+      s3_bucket "my-bucket"
     end
 
-    i = Imagery.new(Photo.new(1001))
-    i.root = '/tmp'
-    i.save(File.open('/some/path/to/image.jpg'))
+    i = Imagery.new :photo, 1001
+    i.save(File.open("/some/path/to/image.jpg"))
 
 #### Imagery::Faking
 
@@ -173,12 +148,12 @@ of testing / faking on an opt-in basis.
     end
     
     # now when you do some testing... (User assumes the user example above)
-    imagery do |is_real|
-      user = User.new(:avatar => { tempfile: File.open('avatar.jpg') })
+    imagery do |enabled|
+      user = User.new(:avatar => { tempfile: File.open("avatar.jpg") })
       user.save
 
-      if is_real
-        assert File.exist?(user.avatar.file)
+      if enabled
+        assert File.exist?(user.avatar.root("original.jpg"))
       end
     end
 
@@ -193,7 +168,7 @@ Imagery doesn't run.
 By making use of standard Ruby idioms, we can easily do lots with it. 
 Exensibility is addressed via Ruby modules for example:
 
-    module Imagery
+    class Imagery
       module MogileStore
         def self.included(base)
           class << base
@@ -214,12 +189,10 @@ Exensibility is addressed via Ruby modules for example:
       end
     end
 
-    # Now just include the module however, whenever you want
-    module Imagery
-      class Model
-        include Imagery::MogileStore
-        self.mogile_config = { :foo => :bar }
-      end
+    # Now just include the module to use it.
+    class Imagery
+      include Imagery::MogileStore
+      self.mogile_config = { :foo => :bar }
     end
 
 

data/imagery.gemspec

@@ -1,73 +1,10 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
-
 Gem::Specification.new do |s|
-  s.name = %q{imagery}
-  s.version = "0.0.6"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Cyril David"]
-  s.date = %q{2010-07-06}
-  s.description = %q{Uses ImageMagick directly underneath. Nuff said.}
-  s.email = %q{cyx.ucron@gmail.com}
-  s.extra_rdoc_files = [
-    "LICENSE",
-     "README.markdown"
-  ]
-  s.files = [
-    ".document",
-     ".gitignore",
-     "LICENSE",
-     "README.markdown",
-     "Rakefile",
-     "VERSION",
-     "imagery.gemspec",
-     "lib/imagery.rb",
-     "lib/imagery/faking.rb",
-     "lib/imagery/missing.rb",
-     "lib/imagery/model.rb",
-     "lib/imagery/s3.rb",
-     "lib/imagery/test.rb",
-     "test/fixtures/lake.jpg",
-     "test/helper.rb",
-     "test/test_imagery.rb",
-     "test/test_missing.rb",
-     "test/test_with_s3.rb"
-  ]
-  s.homepage = %q{http://github.com/sinefunc/imagery}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Image resizing without all the bloat}
-  s.test_files = [
-    "test/helper.rb",
-     "test/test_imagery.rb",
-     "test/test_missing.rb",
-     "test/test_with_s3.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<escape>, [">= 0"])
-      s.add_development_dependency(%q<contest>, [">= 0"])
-      s.add_development_dependency(%q<aws-s3>, [">= 0"])
-      s.add_development_dependency(%q<mocha>, [">= 0"])
-    else
-      s.add_dependency(%q<escape>, [">= 0"])
-      s.add_dependency(%q<contest>, [">= 0"])
-      s.add_dependency(%q<aws-s3>, [">= 0"])
-      s.add_dependency(%q<mocha>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<escape>, [">= 0"])
-    s.add_dependency(%q<contest>, [">= 0"])
-    s.add_dependency(%q<aws-s3>, [">= 0"])
-    s.add_dependency(%q<mocha>, [">= 0"])
-  end
+  s.name              = "imagery"
+  s.version           = "0.2.0"
+  s.summary           = "POROS + GraphicsMagick."
+  s.description       = "Provide a clean and light interface around GraphicsMagick."
+  s.authors           = ["Cyril David"]
+  s.email             = ["me@cyrildavid.com"]
+  s.homepage          = "http://github.com/cyx/imagery"
+  s.files = ["LICENSE", "README.markdown", "lib/imagery/faking.rb", "lib/imagery/s3.rb", "lib/imagery/test.rb", "lib/imagery.rb", "imagery.gemspec", "test/faking.rb", "test/helper.rb", "test/imagery.rb", "test/s3.rb"]
 end
-

data/lib/imagery.rb

@@ -1,20 +1,178 @@
-require 'escape'
-require 'fileutils'
-
-module Imagery
-  VERSION = "0.0.6"
-  
-  autoload :Model,   "imagery/model"
-  autoload :Faking,  "imagery/faking"
-  autoload :S3,      "imagery/s3"
-  autoload :Missing, "imagery/missing"
-  autoload :Test,    "imagery/test"
-  
-  # Syntactic sugar for Imagery::Model::new
-  # @yield Imagery::Model
-  # @see Imagery::Model#initialize for details
-  def new(*args)
-    Model.new(*args).tap { |model| yield model  if block_given? }
+require "fileutils"
+require "tempfile"
+
+class Imagery
+  VERSION = "0.2.0"
+
+  autoload :S3,     "imagery/s3"
+  autoload :Faking, "imagery/faking"
+  autoload :Test,   "imagery/test"
+
+  # Raised during Imagery#save if the image can't be recognized.
+  InvalidImage = Class.new(StandardError)
+
+  # Acts as a namespace, e.g. `photos`.
+  attr :prefix
+
+  # A unique id for the image.
+  attr :key
+
+  # A hash of name => tuple pairs. The name describes the size, e.g. `small`.
+  #
+  # - The first element if the tuple is the resize geometry.
+  # - The second (optional) element describes the extent.
+  #
+  # @example
+  #
+  #     Imagery.new(:photos, "1001", tiny: ["90x90^", "90x90"])
+  #
+  # @see http://www.graphicsmagick.org/GraphicsMagick.html#details-geometry
+  # @see http://www.graphicsmagick.org/GraphicsMagick.html#details-extent
+  attr :sizes
+
+  # In order to facilitate a plugin architecture, all overridable methods
+  # are placed in the `Core` module. Imagery::S3 demonstrates overriding
+  # in action.
+  module Core
+    def initialize(prefix, key = nil, sizes = {})
+      @prefix   = prefix.to_s
+      @key      = key.to_s
+      @sizes    = sizes
+      @original = :original      # Used as the filename for the raw image.
+      @ext      = :jpg           # We default to jpg for the image format.
+    end
+
+    # Returns the url for a given size, which defaults to `:original`.
+    #
+    # If the key is nil, a missing path is returned.
+    def url(file = @original)
+      return "/missing/#{prefix}/#{ext(file)}" if key.to_s.empty?
+
+      "/#{prefix}/#{key}/#{ext(file)}"
+    end
+
+    # Accepts an `IO` object, typically taken from an input[type=file].
+    #
+    # The second optional `key` argument is used when you want to force
+    # a new resource, useful in conjunction with cloudfront / high cache
+    # scenarios where updating an existing image won't suffice.
+    #
+    # @example
+    #   # Let's say we're in the context of a Sinatra handler,
+    #   # and a file was submitted to params[:file]
+    #
+    #   post "upload" do
+    #     im = Imagery.new(:avatar, current_user.id, thumb: ["20x20"])
+    #     im.save(params[:file][:tempfile])
+    #
+    #     # At this point we have two files, original.jpg and thumb.jpg
+    #
+    #     { original: im.url, thumb: im.url(:thumb) }.to_json
+    #   end
+    #
+    def save(io, key = nil)
+      GM.identify(io) or raise(InvalidImage)
+
+      # We delete the existing object iff:
+      # 1. A key was passed
+      # 2. The key passed is different from the existing key.
+      delete if key && key != self.key
+
+      # Now we can assign the new key passed, with the assurance that the
+      # old key has been deleted and won't be used anymore.
+      @key = key.to_s if key
+
+      # Ensure that the path to all images is created.
+      FileUtils.mkdir_p(root)
+
+      # Write the original filename as binary using the `IO` object's data.
+      File.open(root(ext(@original)), "wb") { |file| file.write(io.read) }
+
+      # We resize the original raw image to different sizes which we
+      # defined in the constructor. GraphicsMagick is assumed to exist
+      # within the machine.
+      sizes.each do |size, (resize, extent)|
+        GM.convert root(ext(@original)), root(ext(size)), resize, extent
+      end
+    end
+
+    # A very simple and destructive method. Deletes the entire folder
+    # for the current prefix/key combination.
+    def delete
+      FileUtils.rm_rf(root)
+    end
+  end
+  include Core
+
+  # Returns the base filename together with the extension,
+  # which defaults to jpg.
+  def ext(file)
+    "#{file}.#{@ext}"
+  end
+
+  def root(*args)
+    self.class.root(prefix, key, *args)
+  end
+
+  def self.root(*args)
+    File.join(@root, *args)
+  end
+
+  def self.root=(path)
+    @root = path
+  end
+  self.root = File.join(Dir.pwd, "public")
+
+  module GM
+    # -size tells GM to only read from a given dimension.
+    # -resize is the target dimension, and understands geometry strings.
+    # -quality we force it to 80, which is very reasonable and practical.
+    CONVERT = "gm convert -size '%s' '%s' -resize '%s' %s -quality 80 '%s'"
+
+    # 2 is the file descriptor for stderr, which `gm identify`
+    # happily chucks out information to, regardless if the image
+    # was identified or not.
+    #
+    # We utilize the fact that gm identify exits with a status of 1 if
+    # it fails to identify the image.
+    #
+    # @see for an explanation of file descriptions and redirection.
+    #   http://stackoverflow.com/questions/818255/in-the-bash-shell-what-is-21
+    IDENTIFY = "gm identify '%s' 2> /dev/null"
+
+    def self.convert(src, dst, resize, extent = nil)
+      system(sprintf(CONVERT, dim(resize), src, resize, extent(extent), dst))
+    end
+
+    def self.identify(io)
+      file = Tempfile.new("imagery")
+      file.write(io.read)
+      file.close
+
+      `gm identify #{io.path} 2> /dev/null`
+
+      return $?.success?
+    ensure
+      # Very important, else `io.read` will return "".
+      io.rewind
+
+      # Tempfile quickly runs out of names, so best to avoid that.
+      file.unlink
+    end
+
+    # Return the cleaned dimension representation minus the
+    # geometry directives.
+    def self.dim(dim)
+      dim.gsub(/\^><!/, "")
+    end
+
+    # Cropping and all that nice presentation kung-fu.
+    #
+    # @see http://www.graphicsmagick.org/GraphicsMagick.html#details-extent
+    def self.extent(dim)
+      if dim
+        "-background black -compose Copy -gravity center -extent '#{dim}'"
+      end
+    end
   end
-  module_function :new
 end