quick_magick_hooopo 0.8.1

data/Manifest

@@ -0,0 +1,15 @@
+Manifest
+README.rdoc
+Rakefile
+lib/quick_magick.rb
+lib/quick_magick/image.rb
+lib/quick_magick/image_list.rb
+quick_magick_hooopo.gemspec
+test/9.gif
+test/badfile.xxx
+test/image_list_test.rb
+test/image_test.rb
+test/multipage.tif
+test/test_magick.rb
+test/test_quick_magick.rb
+test/warnings.tiff

data/README.rdoc

@@ -0,0 +1,195 @@
+= Quick Magick
+
+== What is QuickMagick
+QuickMagick is a gem built by BadrIT (http://www.badrit.com) for easily accessing ImageMagick command line tools from Ruby programs.
+
+== When to use QuickMagick
+QuickMagick is a library that allows you to create and manipulate images.
+When you are faced with a problem that requires high quality manipulation of images you can use QuickMagick.
+Use QuickMagick to:
+* Check uploaded images dimensions.
+* Generate captchas.
+* Generate graphical reports and charts.
+* Convert uploaded images formats.
+* Display pdfs as images.
+
+== Features
+* Open an existing image from disk and determine basic info like width, height.
+* Open an image from blob. For example, an image read from an upload form.
+* Do basic and advanced operations on images like resize, rotate, shear, motion blur and other.
+* Create an image from scratch and draw basic elements on it like line, circle and text. This allows making captchas for example.
+* Combine images using ImageList to make a multipage or animated images.
+* API is very simple and powerful.
+* Minimizes disk access by calling command line tools only when required.
+
+== How to install
+First, you should install ImageMagick (http://www.imagemagick.org/) on your machine.
+Command line tools of ImageMagick must be in your system path.
+You can check this by running the command:
+  identify -version
+Now to install QuickMagick just type at your command line:
+  gem install quick_magick
+... and it's done.
+You don't have to install any libraries or compile code from source.
+
+== What is different?
+But what's different from other gems like RMagick and mini-magick?
+
+The story begins when I was working on a project at BadrIT (http://www.badrit.com) using Ruby on Rails.
+In this projects users were uploading images in many formats like pdf, tiff and png.
+We were using Flex as a front end to display and annotate these images.
+Flex has a limitation in that it can open images up to 8192x8192.
+Unfortunately, users were uploading images much larger than this.
+Another issue is that Flex can only open .jpg, .png and .gif files.
+The solution was to convert all images uploaded to one of these formats and resizing them down to at most 8192x8192.
+
+First, I used ImageMagick as a command line tool and was calling it using system calls.
+This accomplished the work perfectly but my source code was a rubbish.
+It has many lines of code to handle creating temporary files and accessing multipage tiff and pdf files.
+I found RMagick at that time and decided to use it.
+It caused the code to be much simple without affecting performance notably.
+It worked with me well while I was using my application with test images.
+Once I decided to test it with real images it failed.
+For example, when I transform a tiff image from 14400x9600 to 8192x8192 while transforming it to gif, my machine runs out of memory (2GB RAM).
+When I tried to make the same operation from command line using (convert) it was working much better.
+It did not finish in a second but at least it worked correctly.
+The solution was to return back to command line.
+
+I searched for alternatives and found MiniMagick.
+MiniMagick is a gem that allows you to perform basic operations using ImageMagick through command line tools.
+I tried to use it but it was not good enough.
+First, it writes temporary images and files as it is working which makes it slow for nothing.
+Second, it doesn't handle multipage images.
+I tried it with a .pdf file and I found that it handled the first page only.
+Third, it doesn't give an API to draw images from scratch.
+Actually, I didn't need this feature, but I may need it in the future.
+
+At this point I decided to make my own gem and QuickMagick was born.
+I addressed the problems of MiniMagick while using the same main idea.
+First, QuickMagick doesn't write any temporary image files to disk.
+It doesn't issue any command line commands till the very end when you are saving the image.
+Second, I made an API similar to RMagick which allows for accessing multipage images.
+Third, I added API commands to create images from scratch and drawing simple primitives on images.
+I tested my gem, compared it to MiniMagick and RMagick and it pleased me.
+
+== Comparison
+I've made some test benches to compare the speed of QuickMagick, MiniMagick and RMagick.
+All denoted numbers are in seconds.
+Here are the results:
+
+===Test 1: resize a normal image
+                  user     system      total        real
+  mini          0.030000   0.040000   3.640000 (  3.585617)
+  quick         0.010000   0.030000   3.330000 (  3.295369)
+  rmagick       1.680000   1.660000   3.340000 (  3.150202)
+
+It's clear that QuickMagick is faster than MiniMagick.
+RMagick was the fastest as it accesses the requested operations directly without the need to load an executable file or parse a command line.
+
+===Test 2: resize a large image
+                  user     system      total        real
+  mini          0.000000   0.040000  57.150000 (130.609229)
+  quick         0.010000   0.010000  56.510000 ( 58.426361)
+
+Again QuickMagick is faster than MiniMagick.
+However, RMagick has failed to pass this test.
+It kept working and eating memory, cpu and harddisk till I had to unplug my computer to stop it.
+So, I removed it from this test bench.
+
+===Test 3: generate random captchas
+                  user     system      total        real
+  quick         0.000000   0.000000   0.290000 (  3.623418)
+  rmagick       0.150000   0.120000   0.270000 (  3.171975)
+
+In this last test, RMagick was about 12% faster than QuickMagick.
+This is normal because it works in memory and doesn't have to parse a command line string to know what to draw.
+I couldn't test MiniMagick for this because it doesn't support an API for drawing functions.
+
+== Conclusion
+QuickMagick is very easy to install, very easy to use and allows you to access most features of ImageMagick.
+RMagick is a bit faster but it's a bit hard to install.
+Also RMagick sometimes fail when it tries to handle large images.
+MiniMagick is proved to be slower than QuickMagick with no advantage.
+So, it's better to use QuickMagick when your application is not image-centric.
+This means, you're not going to build an image manipulation tool or something like this.
+For normal operations like resize, rotate, generating captchas ... etc, QuickMagick will be a good friend of you.
+
+== Examples
+Determine image information
+  i = QuickMagick::Image.read('test.jpg').first
+  i.width # Retrieves width in pixels
+  i.height # Retrieves height in pixels
+
+Resize an image
+  i = QuickMagick::Image.read('test.jpg').first
+  i.resize "300x300!"
+  i.save "resized_image.jpg"
+	
+	or
+  i.append_to_operators 'resize', "300x300!"
+	
+	or 
+  i.resize 300, 300, nil, nil, QuickMagick::AspectGeometry
+	
+
+Access multipage image
+  i = QuickMagick::Image.read("multipage.pdf") {|image| image.density = 300}
+  i.size # number of pages
+  i.each_with_index do |page, i|
+    i.save "page_#{i}.jpg"
+  end
+
+From blob
+  i = QuickMagick::Image.from_blob(blob_data).first
+  i.sample "100x100!"
+  i.save
+
+Modify a file (mogrify)
+  i = QuickMagick::Image.read('test.jpg')
+  i.resize "100x100!"
+  i.save!
+
+You can also display an image to Xserver
+  i = QuickMagick::Image.read('test.jpg')
+  i.display
+
+QuickMagick supports also ImageList s
+  # Batch convert a list of jpg files to gif while resizing them
+  il = QuickMagick::ImageList.new('test.jpg', 'test2.jpg')
+  il << QuickMagick::Image.read('test3.jpg')
+  il.format = 'gif'
+  il.resize "300x300>"
+  il.save!
+
+You can also create images from scratch
+  # Create a 300x300 gradient image from yellow to red
+  i1 = QuickMagick::Image::gradient(300, 300, QuickMagick::RadialGradient, :yellow, :red)
+  i1.save 'gradient.png'
+	
+  # Create a 100x200 CheckerBoard image
+  i1 = QuickMagick::Image::pattern(100, 200, :checkerboard)
+  i1.display
+
+... and draw primitives on them
+  i = QuickMagick::Image::solid(100, 100, :white)
+  i.draw_line(0,0,50,50)
+  i.draw_text(30, 30, "Hello world!", :rotate=>45)
+  i.save 'hello.jpg'
+
+... you can then convert it to blob using
+  i.to_blob
+  
+(new) You can now access single pixels using QuickMagick
+  # Create a 300x300 gradient image from yellow to red
+  i1 = QuickMagick::Image::gradient(300, 300, QuickMagick::RadialGradient, :yellow, :red)
+  i1.save 'gradient.png'
+	
+  # Now you can access single pixel values
+  i1.get_pixel(10,10) # [255, 0, 0]
+  i1.get_pixel(50,50) # [255, 15, 0]
+
+For more information on drawing API visit:
+http://www.imagemagick.org/Usage/draw/
+
+Check all command line options of ImageMagick at:
+http://www.imagemagick.org/script/convert.php

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+ 
+Echoe.new('quick_magick_hooopo', '0.8.1') do |p|
+  p.description    = "QuickMagick allows you to access ImageMagick command line functions using Ruby interface."
+  p.summary        = "A gem build by BadrIT to access ImageMagick command line functions easily and quickly"
+  p.url            = "http://quickmagick.rubyforge.org/"
+  p.author         = "Ahmed ElDawy"
+  p.email          = "ahmed.eldawy@badrit.com"
+  p.project				 = "quickmagick"
+end
+ 
+#Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }
+

data/lib/quick_magick.rb

@@ -0,0 +1,208 @@
+# Define quick magick error
+module QuickMagick
+  class QuickMagickError < RuntimeError; end
+end
+
+# check if ImageMagick is installed
+begin
+  x = `identify -version 2>&1`
+  raise(QuickMagick::QuickMagickError, "ImageMagick not installed") unless x.index('ImageMagick') 
+rescue Errno::ENOENT
+  # For Windows machines
+  raise(QuickMagick::QuickMagickError, "ImageMagick not installed")
+end
+
+module QuickMagick
+  # Normally the attributes are treated as pixels.
+  # Use this flag when the width and height attributes represent percentages.
+  # For example, 125x75 means 125% of the height and 75% of the width.
+  # The x and y attributes are not affected by this flag.  
+  PercentGeometry = "%"
+  
+  # Use this flag when you want to force the new image to have exactly the size specified by the the width and height attributes.
+  AspectGeometry  = "!"
+  
+  # Use this flag when you want to change the size of the image only if both its width and height
+  # are smaller the values specified by those attributes. The image size is changed proportionally.
+  LessGeometry = "<"
+  
+  # Use this flag when you want to change the size of the image if either its width and height
+  # exceed the values specified by those attributes. The image size is changed proportionally.
+  GreaterGeometry = ">"
+  
+  # This flag is useful only with a single width attribute.
+  # When present, it means the width attribute represents the total area of the image in pixels.
+  AreaGeometry = "@"
+  
+  # Use ^ to set a minimum image size limit.
+  # The geometry 640x480^, for example, means the image width will not be less than 640 and
+  # the image height will not be less than 480 pixels after the resize.
+  # One of those dimensions will match the requested size,
+  # but the image will likely overflow the space requested to preserve its aspect ratio.
+  MinimumGeometry = "^"
+  
+  # Command for solid color
+  SolidColor = "xc"
+  # Command for linear gradient
+  LinearGradient = "gradient"
+  # Command for radial gradient
+  RadialGradient = "radial-gradient"
+
+  # Different possible patterns
+  Patterns = %w{bricks checkerboard circles crosshatch crosshatch30 crosshatch45 fishscales} +
+    (0..20).collect {|level| "gray#{level}" } +
+    %w{hexagons horizontal horizontalsaw hs_bdiagonal hs_cross hs_diagcross hs_fdiagonal hs_horizontal
+    hs_vertical left30 left45 leftshingle octagons right30 right45 rightshingle smallfishscales
+    vertical verticalbricks verticalleftshingle verticalrightshingle verticalsaw}
+  
+  %w{NorthWest North NorthEast West Center East SouthWest South SouthEast}.each do |gravity_type|
+      const_set gravity_type+"Gravity", gravity_type
+    end
+  
+  
+  class << self
+    # Generate a random string of specified length.
+    # Used to generate random names for temp files
+    def random_string(length=10)
+      @@CHARS ||= ("a".."z").to_a + ("1".."9").to_a 
+      Array.new(length, '').collect{@@CHARS[rand(@@CHARS.size)]}.join
+    end
+
+    def verbose
+      defined?(@verbose) && @verbose
+    end
+
+    def verbose=(flag)
+      @verbose = flag
+    end
+    
+    # Encodes a geometry string with the given options
+    def geometry(width, height=nil, x=nil, y=nil, flag=nil)
+      geometry_string = ""
+      geometry_string << width.to_s if width
+      geometry_string << 'x' << height.to_s if height
+      geometry_string << '+' << x.to_s if x
+      geometry_string << '+' << y.to_s if y
+      geometry_string << flag if flag
+      geometry_string
+    end
+    
+    # Returns a formatted string for the color with the given components
+    # each component could take one of the following values
+    # * an integer from 0 to 255
+    # * a float from 0.0 to 1.0
+    # * a string showing percentage from "0%" to "100%"
+    def rgba_color(red, green, blue, alpha=255)
+      "#%02x%02x%02x%02x" % [red, green, blue, alpha].collect do |component|
+        case component
+          when Integer then component
+          when Float then Integer(component*255)
+          when String then Integer(component.sub('%', '')) * 255 / 100
+        end
+      end
+    end
+    
+    alias rgb_color rgba_color
+    
+    # Returns a formatted string for a gray color with the given level and alpha.
+    # level and alpha could take one of the following values
+    # * an integer from 0 to 255
+    # * a float from 0.0 to 1.0
+    # * a string showing percentage from "0%" to "100%"
+    def graya_color(level, alpha=255)
+      rgba_color(level, level, level, alpha)
+    end
+    
+    alias gray_color graya_color
+    
+    # HSL colors are encoding as a triple (hue, saturation, lightness).
+    # Hue is represented as an angle of the color circle (i.e. the rainbow represented in a circle).
+    # This angle is so typically measured in degrees that the unit is implicit in CSS;
+    # syntactically, only a number is given. By definition red=0=360,
+    # and the other colors are spread around the circle, so green=120, blue=240, etc.
+    # As an angle, it implicitly wraps around such that -120=240 and 480=120, for instance.
+    # (Students of trigonometry would say that "coterminal angles are equivalent" here;
+    # an angle (theta) can be standardized by computing the equivalent angle, (theta) mod 360.)
+    #
+    # Saturation and lightness are represented as percentages.
+    # 100% is full saturation, and 0% is a shade of grey.
+    # 0% lightness is black, 100% lightness is white, and 50% lightness is 'normal'.
+    #
+    # Hue can take one of the following values:
+    # * an integer from 0...360 representing angle in degrees
+    # * a float value from 0...2*PI represeting angle in radians
+    #
+    # saturation, lightness and alpha can take one of the following values:
+    # * an integer from 0 to 255
+    # * a float from 0.0 to 1.0
+    # * a string showing percentage from "0%" to "100%"
+    def hsla_color(hue, saturation, lightness, alpha=1.0)
+      components = [case hue
+        when Integer then hue
+        when Float then Integer(hue * 360 / 2 / Math::PI)
+      end]
+      components += [saturation, lightness].collect do |component|
+        case component
+          when Integer then (component * 100.0 / 255).round
+          when Float then Integer(component*100)
+          when String then Integer(component.sub('%', ''))
+        end
+      end
+      components << case alpha
+        when Integer then alpha * 100.0 / 255
+        when Float then alpha
+        when String then Float(alpha.sub('%', '')) / 100.0
+      end
+      "hsla(%d,%d%%,%d%%,%g)" % components
+    end
+    
+    alias hsl_color hsla_color
+    
+    # Escapes possible special chracters in command line
+    # by surrounding it with double quotes
+    def escape_commandline(str)
+      str =~ /^(\w|\.)*$/ ? str : "\"#{str}\""
+    end
+    
+    alias c escape_commandline
+
+    # Execute a command line and returns its results when it suceeds
+    # When the command fails, it throws QuickMagick::QuickMagickError
+    def exec3(command)
+      error_file = Tempfile.new('error')
+      error_filepath = error_file.path
+      error_file.close
+      puts "Run Command -> #{command}" if verbose
+      result = `#{command} 2>"#{error_filepath}"`
+      unless $?.success?
+        error_message = <<-ERROR
+          Error executing command: command
+          Result is: #{result}
+          Error is: #{File.read(error_filepath)}
+        ERROR
+        raise QuickMagick::QuickMagickError, error_message
+      end
+      result
+    end
+  end
+end
+
+# For backward compatibility with ruby < 1.8.7
+unless "".respond_to? :start_with?
+  class String
+    def start_with?(x)
+      self.index(x) == 0
+    end
+  end
+end
+
+unless "".respond_to? :end_with?
+  class String
+    def end_with?(x)
+      self.index(x) == self.length - 1
+    end
+  end
+end
+
+require 'quick_magick/image'
+require 'quick_magick/image_list'

data/lib/quick_magick/image.rb

@@ -0,0 +1,495 @@
+require "tempfile"
+
+module QuickMagick
+  
+  class Image
+    class << self
+      
+      # create an array of images from the given blob data
+      def from_blob(blob, &proc)
+        file = Tempfile.new(QuickMagick::random_string)
+        file.binmode
+        file.write(blob)
+        file.close
+        self.read(file.path, &proc)
+      end
+      
+      # create an array of images from the given file
+      def read(filename, &proc)
+        info = identify(filename)
+        info_lines = info.split(/[\r\n]/)
+        images = []
+        info_lines.each_with_index do |info_line, i|
+          images << Image.new(filename, i, info_line)
+        end
+        images.each(&proc) if block_given?
+        return images
+      end
+      
+      alias open read
+      
+      # Creates a new image initially set to gradient
+      # Default gradient is linear gradient from black to white
+      def gradient(width, height, type=QuickMagick::LinearGradient, color1=nil, color2=nil)
+        template_name = type + ":"
+        template_name << color1.to_s if color1
+        template_name << '-' << color2.to_s if color2
+        i = self.new(template_name, 0, nil, true)
+        i.size = QuickMagick::geometry(width, height)
+        yield(i) if block_given?
+        i
+      end
+      
+      # Creates an image with solid color
+      def solid(width, height, color=nil)
+        template_name = QuickMagick::SolidColor+":"
+        template_name << color.to_s if color
+        i = self.new(template_name, 0, nil, true)
+        i.size = QuickMagick::geometry(width, height)
+        yield(i) if block_given?
+        i
+      end
+      
+      # Creates an image from pattern
+      def pattern(width, height, pattern)
+        raise QuickMagick::QuickMagickError, "Invalid pattern '#{pattern.to_s}'" unless QuickMagick::Patterns.include?(pattern.to_s)
+        template_name = "pattern:#{pattern.to_s}"
+        i = self.new(template_name, 0, nil, true)
+        i.size = QuickMagick::geometry(width, height)
+        yield(i) if block_given?
+        i
+      end
+
+      # returns info for an image using <code>identify</code> command
+      def identify(filename)
+        QuickMagick.exec3 "identify #{QuickMagick.c filename}"
+      end
+
+    end
+
+    # append the given option, value pair to the settings of the current image
+    def append_to_settings(arg, value=nil)
+      @arguments << "-#{arg} #{QuickMagick.c value} "
+      @last_is_draw = false
+      self
+    end
+    
+    # append the given string as is. Used to append special arguments like +antialias or +debug
+    def append_basic(arg)
+      @arguments << arg << ' '
+    end
+
+    # Image settings supported by ImageMagick
+    IMAGE_SETTINGS_METHODS = %w{
+      adjoin affine alpha authenticate attenuate background bias black-point-compensation
+      blue-primary bordercolor caption channel colors colorspace comment compose compress define
+      delay depth display dispose dither encoding endian family fill filter font format fuzz gravity
+      green-primary intent interlace interpolate interword-spacing kerning label limit loop mask
+      mattecolor monitor orient ping pointsize preview quality quiet red-primary regard-warnings
+      remap respect-parentheses scene seed stretch stroke strokewidth style taint texture treedepth
+      transparent-color undercolor units verbose view virtual-pixel weight white-point
+
+      density page sampling-factor size tile-offset
+    }
+
+    # append the given option, value pair to the args for the current image
+    def append_to_operators(arg, value=nil)
+      is_draw = (arg == 'draw')
+      if @last_is_draw && is_draw
+        @arguments.insert(@arguments.rindex('"'), " #{value}")
+      else
+        @arguments << %Q<-#{arg} #{QuickMagick.c value} >
+      end
+      @last_is_draw = is_draw
+      self
+    end
+    
+    # Reverts this image to its last saved state.
+    # Note that you cannot revert an image created from scratch.
+    def revert!
+      raise QuickMagick::QuickMagickError, "Cannot revert a pseudo image" if @pseudo_image
+      @arguments = ""
+    end
+
+    # Image operators supported by ImageMagick
+    IMAGE_OPERATORS_METHODS = %w{
+      alpha auto-orient bench black-threshold bordercolor charcoal clip clip-mask clip-path colorize
+      contrast convolve cycle decipher deskew despeckle distort edge encipher emboss enhance equalize
+      evaluate flip flop function gamma identify implode layers level level-colors median modulate monochrome
+      negate noise normalize opaque ordered-dither NxN paint polaroid posterize print profile quantize
+      radial-blur Raise random-threshold recolor render rotate segment sepia-tone set shade solarize
+      sparse-color spread strip swirl threshold tile tint transform transparent transpose transverse trim
+      type unique-colors white-threshold
+
+      adaptive-blur adaptive-resize adaptive-sharpen annotate blur border chop contrast-stretch extent
+      extract frame gaussian-blur geometry lat linear-stretch liquid-rescale motion-blur region repage
+      resample resize roll sample scale selective-blur shadow sharpen shave shear sigmoidal-contrast
+      sketch splice thumbnail unsharp vignette wave
+      
+      append average clut coalesce combine composite deconstruct flatten fx hald-clut morph mosaic process reverse separate write
+      crop
+      }
+
+    # methods that are called with (=)
+    WITH_EQUAL_METHODS =
+      %w{alpha background bias black-point-compensation blue-primary border bordercolor caption
+        cahnnel colors colorspace comment compose compress depth density encoding endian family fill filter
+        font format frame fuzz geometry gravity label mattecolor page pointsize quality stroke strokewidth
+        undercolor units weight
+        brodercolor transparent type size}
+
+    # methods that takes geometry options
+    WITH_GEOMETRY_METHODS =
+      %w{density page sampling-factor size tile-offset adaptive-blur adaptive-resize adaptive-sharpen
+        annotate blur border chop contrast-stretch extent extract frame gaussian-blur
+        geometry lat linear-stretch liquid-rescale motion-blur region repage resample resize roll
+        sample scale selective-blur shadow sharpen shave shear sigmoidal-contrast sketch
+        splice thumbnail unsharp vignette wave crop}
+   
+    # Methods that need special treatment. This array is used just to keep track of them.
+    SPECIAL_COMMANDS =
+      %w{floodfill antialias draw}
+
+    IMAGE_SETTINGS_METHODS.each do |method|
+      if WITH_EQUAL_METHODS.include?(method)
+        define_method((method+'=').to_sym) do |arg|
+          append_to_settings(method, arg)
+        end
+      elsif WITH_GEOMETRY_METHODS.include?(method)
+        define_method((method).to_sym) do |*args|
+          append_to_settings(method, QuickMagick::geometry(*args) )
+        end
+      else
+        define_method(method.to_sym) do |*args|
+          append_to_settings(method, args.join(" "))
+        end
+      end
+    end
+    
+    IMAGE_OPERATORS_METHODS.each do |method|
+      if WITH_EQUAL_METHODS.include?(method)
+        define_method((method+'=').to_sym) do |arg|
+          append_to_operators(method, arg )
+        end
+      elsif WITH_GEOMETRY_METHODS.include?(method)
+        define_method((method).to_sym) do |*args|
+          append_to_operators(method, QuickMagick::geometry(*args) )
+        end
+      else
+        define_method(method.to_sym) do |*args|
+          append_to_operators(method, args.join(" "))
+        end
+      end
+    end
+
+    # Fills a rectangle with a solid color
+    def floodfill(width, height=nil, x=nil, y=nil, flag=nil, color=nil)
+      append_to_operators "floodfill", QuickMagick::geometry(width, height, x, y, flag), color
+    end
+    
+    # Enables/Disables flood fill. Pass a boolean argument.
+    def antialias=(flag)
+    	append_basic flag ? '-antialias' : '+antialias'
+    end
+    
+    # define attribute readers (getters)
+    attr_reader :image_filename
+    alias original_filename image_filename
+    
+    # constructor
+    def initialize(filename, index=0, info_line=nil, pseudo_image=false)
+      @image_filename = filename
+      @index = index
+      @pseudo_image = pseudo_image
+      if info_line
+        @image_infoline = info_line.split
+        @image_infoline[0..1] = @image_infoline[0..1].join(' ') while @image_infoline.size > 1 && !@image_infoline[0].start_with?(image_filename)
+      end
+      @arguments = ""
+    end
+    
+    # The command line so far that will be used to convert or save the image
+    def command_line
+      %Q< "(" #{@arguments} #{QuickMagick.c(image_filename + (@pseudo_image ? "" : "[#{@index}]"))} ")" >
+    end
+    
+    # An information line about the image obtained using 'identify' command line
+    def image_infoline
+      return nil if @pseudo_image
+      unless @image_infoline
+        @image_infoline = QuickMagick::Image::identify(command_line).split
+        @image_infoline[0..1] = @image_infoline[0..1].join(' ') while @image_infoline.size > 1 && !@image_infoline[0].start_with?(image_filename)
+      end
+      @image_infoline
+    end
+
+    # converts options passed to any primitive to a string that can be passed to ImageMagick
+    # options allowed are:
+    # * rotate          degrees
+    # * translate       dx,dy
+    # * scale           sx,sy
+    # * skewX           degrees
+    # * skewY           degrees
+    # * gravity         NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast
+    # * stroke          color
+    # * fill            color
+    # The rotate primitive rotates subsequent shape primitives and text primitives about the origin of the main image.
+    # If you set the region before the draw command, the origin for transformations is the upper left corner of the region.
+    # The translate primitive translates subsequent shape and text primitives.
+    # The scale primitive scales them.
+    # The skewX and skewY primitives skew them with respect to the origin of the main image or the region.
+    # The text gravity primitive only affects the placement of text and does not interact with the other primitives.
+    # It is equivalent to using the gravity method, except that it is limited in scope to the draw_text option in which it appears.
+    def options_to_str(options)
+      options.to_a.flatten.join " "
+    end
+
+    # Converts an array of coordinates to a string that can be passed to polygon, polyline and bezier
+    def points_to_str(points)
+      raise QuickMagick::QuickMagickError, "Points must be an even number of coordinates" if points.size.odd?
+      points_str = ""
+      points.each_slice(2) do |point|
+        points_str << point.join(",") << " "
+      end
+      points_str
+    end
+
+    # The shape primitives are drawn in the color specified by the preceding -fill setting.
+    # For unfilled shapes, use -fill none.
+    # You can optionally control the stroke (the "outline" of a shape) with the -stroke and -strokewidth settings.
+    
+    # draws a point at the given location in pixels
+    # A point primitive is specified by a single point in the pixel plane, that is, by an ordered pair
+    # of integer coordinates, x,y.
+    # (As it involves only a single pixel, a point primitive is not affected by -stroke or -strokewidth.)
+    def draw_point(x, y, options={})
+      append_to_operators("draw", "#{options_to_str(options)} point #{x},#{y}")
+    end
+    
+    # draws a line between the given two points
+    # A line primitive requires a start point and end point.
+    def draw_line(x0, y0, x1, y1, options={})
+      append_to_operators("draw", "#{options_to_str(options)} line #{x0},#{y0} #{x1},#{y1}")
+    end
+    
+    # draw a rectangle with the given two corners
+    # A rectangle primitive is specified by the pair of points at the upper left and lower right corners.
+    def draw_rectangle(x0, y0, x1, y1, options={})
+      append_to_operators("draw", "#{options_to_str(options)} rectangle #{x0},#{y0} #{x1},#{y1}")
+    end
+
+    # draw a rounded rectangle with the given two corners
+    # wc and hc are the width and height of the arc
+    # A roundRectangle primitive takes the same corner points as a rectangle
+    # followed by the width and height of the rounded corners to be removed.
+    def draw_round_rectangle(x0, y0, x1, y1, wc, hc, options={})
+      append_to_operators("draw", "#{options_to_str(options)} roundRectangle #{x0},#{y0} #{x1},#{y1} #{wc},#{hc}")
+    end
+    
+    # The arc primitive is used to inscribe an elliptical segment in to a given rectangle.
+    # An arc requires the two corners used for rectangle (see above) followed by
+    # the start and end angles of the arc of the segment segment (e.g. 130,30 200,100 45,90).
+    # The start and end points produced are then joined with a line segment and the resulting segment of an ellipse is filled.
+    def draw_arc(x0, y0, x1, y1, a0, a1, options={})
+      append_to_operators("draw", "#{options_to_str(options)} arc #{x0},#{y0} #{x1},#{y1} #{a0},#{a1}")
+    end
+
+    # Use ellipse to draw a partial (or whole) ellipse.
+    # Give the center point, the horizontal and vertical "radii"
+    # (the semi-axes of the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 0,360).
+    def draw_ellipse(x0, y0, rx, ry, a0, a1, options={})
+      append_to_operators("draw", "#{options_to_str(options)} ellipse #{x0},#{y0} #{rx},#{ry} #{a0},#{a1}")
+    end
+    
+    # The circle primitive makes a disk (filled) or circle (unfilled). Give the center and any point on the perimeter (boundary).
+    def draw_circle(x0, y0, x1, y1, options={})
+      append_to_operators("draw", "#{options_to_str(options)} circle #{x0},#{y0} #{x1},#{y1}")
+    end
+    
+    # The polyline primitive requires three or more points to define their perimeters.
+    # A polyline is simply a polygon in which the final point is not stroked to the start point.
+    # When unfilled, this is a polygonal line. If the -stroke setting is none (the default), then a polyline is identical to a polygon.
+    #  points - A single array with each pair forming a coordinate in the form (x, y).
+    # e.g. [0,0,100,100,100,0] will draw a polyline between points (0,0)-(100,100)-(100,0)
+    def draw_polyline(points, options={})
+      append_to_operators("draw", "#{options_to_str(options)} polyline #{points_to_str(points)}")
+    end
+
+    # The polygon primitive requires three or more points to define their perimeters.
+    # A polyline is simply a polygon in which the final point is not stroked to the start point.
+    # When unfilled, this is a polygonal line. If the -stroke setting is none (the default), then a polyline is identical to a polygon.
+    #  points - A single array with each pair forming a coordinate in the form (x, y). 
+    # e.g. [0,0,100,100,100,0] will draw a polygon between points (0,0)-(100,100)-(100,0)
+    def draw_polygon(points, options={})
+      append_to_operators("draw", "#{options_to_str(options)} polygon #{points_to_str(points)}")
+    end
+
+    # The Bezier primitive creates a spline curve and requires three or points to define its shape.
+    # The first and last points are the knots and these points are attained by the curve,
+    # while any intermediate coordinates are control points.
+    # If two control points are specified, the line between each end knot and its sequentially
+    # respective control point determines the tangent direction of the curve at that end.
+    # If one control point is specified, the lines from the end knots to the one control point
+    # determines the tangent directions of the curve at each end.
+    # If more than two control points are specified, then the additional control points
+    # act in combination to determine the intermediate shape of the curve.
+    # In order to draw complex curves, it is highly recommended either to use the path primitive
+    # or to draw multiple four-point bezier segments with the start and end knots of each successive segment repeated.
+    def draw_bezier(points, options={})
+      append_to_operators("draw", "#{options_to_str(options)} bezier #{points_to_str(points)}")
+    end
+    
+    # A path represents an outline of an object, defined in terms of moveto
+    # (set a new current point), lineto (draw a straight line), curveto (draw a Bezier curve),
+    # arc (elliptical or circular arc) and closepath (close the current shape by drawing a
+    # line to the last moveto) elements.
+    # Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by
+    # one or more line or curve operations) are possible to allow effects such as donut holes in objects.
+    # (See http://www.w3.org/TR/SVG/paths.html)
+    def draw_path(path_spec, options={})
+      append_to_operators("draw", "#{options_to_str(options)} path #{path_spec}")
+    end
+    
+    # Use image to composite an image with another image. Follow the image keyword
+    # with the composite operator, image location, image size, and filename
+    # You can use 0,0 for the image size, which means to use the actual dimensions found in the image header.
+    # Otherwise, it is scaled to the given dimensions. See -compose for a description of the composite operators.
+    def draw_image(operator, x0, y0, w, h, image_filename, options={})
+      append_to_operators("draw", "#{options_to_str(options)} image #{operator} #{x0},#{y0} #{w},#{h} \"#{image_filename}\"")
+    end
+    
+    # Use text to annotate an image with text. Follow the text coordinates with a string.
+    def draw_text(x0, y0, text, options={})
+      append_to_operators("draw", "#{options_to_str(options)} text #{x0},#{y0} '#{text.gsub('"', '\"').gsub("'", "\\\\'")}'")
+    end
+    
+    # saves the current image to the given filename
+    def save(output_filename)
+      result = QuickMagick.exec3 "convert #{command_line} #{QuickMagick.c output_filename}" 
+    	if @pseudo_image
+    		# since it's been saved, convert it to normal image (not pseudo)
+    		initialize(output_filename)
+	    	revert!
+    	end
+      return result 
+    end
+    
+    alias write save
+    alias convert save
+    
+    # saves the current image overwriting the original image file
+    def save!
+      raise QuickMagick::QuickMagickError, "Cannot mogrify a pseudo image" if @pseudo_image
+      result = QuickMagick.exec3 "mogrify #{command_line}"
+      # remove all operations to avoid duplicate operations
+      revert!
+      return result 
+    end
+
+    alias write! save!
+    alias mogrify! save!
+    
+    def to_blob
+    	tmp_file = Tempfile.new(QuickMagick::random_string)
+    	if command_line =~ /-format\s(\S+)\s/
+    		# use format set up by user
+    		blob_format = $1
+    	elsif !@pseudo_image
+    		# use original image format
+    		blob_format = self.format
+    	else
+		  	# default format is jpg
+		  	blob_format = 'jpg'
+    	end
+    	save "#{blob_format}:#{tmp_file.path}"
+    	blob = nil
+    	File.open(tmp_file.path, 'rb') { |f| blob = f.read}
+    	blob
+    end
+
+    # image file format
+    def format
+      image_infoline[1]
+    end
+    
+    # columns of image in pixels
+    def columns
+      image_infoline[2].split('x').first.to_i
+    end
+    
+    alias width columns
+    
+    # rows of image in pixels
+    def rows
+      image_infoline[2].split('x').last.to_i
+    end
+    
+    alias height rows
+    
+    # Bit depth
+    def bit_depth
+      image_infoline[4].to_i
+    end
+    
+    # Number of different colors used in this image
+    def colors
+      image_infoline[6].to_i
+    end
+    
+    # returns size of image in bytes
+    def size
+      File.size?(image_filename)
+    end
+    
+    # Reads a pixel from the image.
+    # WARNING: This is done through command line which is very slow.
+    # It is not recommended at all to use this method for image processing for example.
+    def get_pixel(x, y)
+      result = QuickMagick.exec3("identify -verbose -crop #{QuickMagick::geometry(1,1,x,y)} #{QuickMagick.c image_filename}[#{@index}]")
+      result =~ /Histogram:\s*\d+:\s*\(\s*(\d+),\s*(\d+),\s*(\d+)\)/
+      return [$1.to_i, $2.to_i, $3.to_i]
+    end
+
+    # Returns details of the image as found by "identify -verbose" command
+    def details
+      str_details = QuickMagick.exec3("identify -verbose #{QuickMagick.c image_filename}[#@index]")
+      # This is something like breadcrumb for hashes visited at any time
+      hash_stack = []
+      # Current indentation. Used to infer nesting using indentation
+      current_indent = ""
+      # Last key inserted in the hash. Used to determine which key is the parent of a nested hash
+      last_key = nil
+      # Start with top level empty hash
+      hash_stack.push({})
+      str_details.each_line do |line|
+        key, value = line.split(":", 2)
+        key_indent = key[/^\s*/]
+        if key_indent.length < current_indent.length
+          # Must go one level up
+          hash_stack.pop
+        elsif key_indent.length > current_indent.length
+          # Must go one level deeper using last key
+          hash_stack.last[last_key] = {}
+          hash_stack.push hash_stack.last[last_key]
+        end
+        current_indent = key_indent
+
+        key = key.strip
+        value = value.strip
+        hash_stack.last[key] = value
+        last_key = key
+      end
+      hash_stack.first
+    end
+    
+    # displays the current image as animated image
+    def animate
+      `animate #{command_line}`
+    end
+    
+    # displays the current image to the x-windowing system
+    def display
+      `display #{command_line}`
+    end
+  end
+end