chunky_png 0.9.0 → 0.9.1

data/.gitignore

@@ -3,4 +3,5 @@ spec/resources/_*.png
 /pkg
 /tmp
 /doc
-.yardoc
+/.yardoc
+/.bundle

data/BENCHMARKS.rdoc

@@ -0,0 +1,31 @@
+= ChunkyPNG benchmark suite
+
+This small benchmark suite is intended to test the speed of PNG decoding 
+and encoding against different ruby interpreters. You can set the number 
+of runs by passing the N environment variable. You can execute them as
+rake task or as standalone script.
+
+    rake benchmark:encoding
+    rake benchmark:decoding
+    
+    rake benchmark N=10           # Run all of them, using n=10
+
+Use rvm to simply run the tests against different interpreters. Of course, 
+make sure that the chunky_png is installed for all your interpreters.
+
+    rvm 1.8.7,1.9.1,rbx rake benchmark N=10
+
+== Results
+
+Some of my benchmark (N=50) result on my 2007 iMac can be found in this gist:
+http://gist.github.com/495323
+
+== Why is this relevant?
+
+ChunkyPNG is a pure Ruby library to handle PNG files. Decoding a PNG requires
+a lot of integer math and bitwise operations, and moderate use of the unpack
+method to read binary data. Encoding is a good test for Array#pack, and
+depending on the encoding options, also requires a lot of calculations.
+Therefore, the library is a good benchmark candidate for these methods and
+algorithms. It has been used to improve the Array#pack and String#unpack
+methods in Rubinius.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    chunky_png (0.9.0)
+    chunky_png (0.9.1)
 
 GEM
   remote: http://rubygems.org/

data/README.rdoc

@@ -5,8 +5,8 @@ maximum portability. Let me rephrase: it does NOT require RMagick or any other
 memory leaking image library.
 
 Source code:: http://github.com/wvanbergen/chunky_png/tree
-RDoc:: http://rdoc.info/projects/wvanbergen/chunky_png
-Wiki:: http://wiki.github.com/wvanbergen/chunky_png
+RDoc:: http://rdoc.info/github/wvanbergen/chunky_png/master/file/README.rdoc
+Wiki:: http://github.com/wvanbergen/chunky_png/wiki
 Issue tracker:: http://github.com/wvanbergen/chunky_png/issues
 
 == Features
@@ -60,6 +60,9 @@ The main classes and modules used within ChunkyPNG are:
   png_stream = ChunkyPNG::Datastream.from_file('filename.png')
   png_stream.each_chunk { |chunk| p chunk.type }
 
+For more information, see the project wiki on http://github.com/wvanbergen/chunky_png/wiki
+or the RDOC documentation on http://rdoc.info/github/wvanbergen/chunky_png/master/file/README.rdoc.
+
 == About
 
 The library is written by Willem van Bergen for Floorplanner.com, and released

data/Rakefile

@@ -1,9 +1,9 @@
-Dir['tasks/*.rake'].each { |file| load(file) }
-
 require 'rubygems'
 require 'bundler'
 
 Bundler.setup
 
+Dir['tasks/*.rake'].each { |file| load(file) }
+
 GithubGem::RakeTasks.new(:gem)
 task :default => [:spec]

data/benchmarks/decoding_benchmark.rb

@@ -0,0 +1,34 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.setup
+
+require 'benchmark'
+require 'chunky_png'
+
+def image_file(name)
+  File.join(File.dirname(__FILE__), '..', 'spec', 'resources', name)
+end
+
+def image_data(name)
+  data = nil
+  File.open(image_file(name), 'rb') { |f| data = f.read }
+  data
+end
+
+png_stream       = image_data('pixelstream_reference.png')
+rgba_pixelstream = image_data('pixelstream.rgba')
+rgb_pixelstream  = image_data('pixelstream.rgb')
+
+n = (ENV['N'] || '5').to_i
+
+puts "---------------------------------------------"
+puts "ChunkyPNG (#{ChunkyPNG::VERSION}) decoding benchmark (n=#{n})"
+puts "---------------------------------------------"
+puts
+
+Benchmark.bmbm do |x|
+  x.report('From PNG stream')       { n.times { ChunkyPNG::Image.from_blob(png_stream) } }
+  x.report('From RGBA pixelstream') { n.times { ChunkyPNG::Image.from_rgba_stream(240, 180, rgba_pixelstream) } }
+  x.report('From RGB pixelstream')  { n.times { ChunkyPNG::Image.from_rgb_stream(240, 180, rgb_pixelstream) } }
+end

data/benchmarks/encoding_benchmark.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.setup
+
+require 'benchmark'
+require 'chunky_png'
+
+image = ChunkyPNG::Image.new(240, 180, ChunkyPNG::Color::TRANSPARENT)
+
+# set some random pixels
+image[10, 20] = ChunkyPNG::Color.rgba(255,   0,   0, 255)
+image[50, 87] = ChunkyPNG::Color.rgba(  0, 255,   0, 255)
+image[33, 99] = ChunkyPNG::Color.rgba(  0,   0, 255, 255)
+
+n = (ENV['N'] || '5').to_i
+
+puts "---------------------------------------------"
+puts "ChunkyPNG (#{ChunkyPNG::VERSION}) encoding benchmark (n=#{n})"
+puts "---------------------------------------------"
+puts
+
+Benchmark.bmbm do |x|
+  x.report('Default (indexed)')  { n.times { image.to_blob } }
+
+  # Presets
+  x.report(':fast_rgba')         { n.times { image.to_blob(:fast_rgba) } }
+  x.report(':fast_rgb')          { n.times { image.to_blob(:fast_rgb) } }
+  x.report(':best_compression')  { n.times { image.to_blob(:best_compression) } }
+  
+  # Some options
+  x.report(':rgb')        { n.times { image.to_blob(:color_mode => ChunkyPNG::COLOR_TRUECOLOR) } }
+  x.report(':rgba')       { n.times { image.to_blob(:color_mode => ChunkyPNG::COLOR_TRUECOLOR_ALPHA) } }
+  x.report(':indexed')    { n.times { image.to_blob(:color_mode => ChunkyPNG::COLOR_INDEXED) } }
+  x.report(':interlaced') { n.times { image.to_blob(:interlaced => true) } }
+  
+  # Exports
+  x.report('to RGBA pixelstream') { n.times { image.to_rgba_stream } }
+  x.report('to RGB pixelstream')  { n.times { image.to_rgb_stream } }
+end

data/chunky_png.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
 
   # Do not change the version and date fields by hand. This will be done
   # automatically by the gem release script.
-  s.version = "0.9.0"
-  s.date    = "2010-08-18"
+  s.version = "0.9.1"
+  s.date    = "2010-09-16"
 
   s.summary     = "Pure ruby library for read/write, chunk-level access to PNG files"
   s.description = <<-EOT
@@ -31,10 +31,10 @@ Gem::Specification.new do |s|
   s.add_development_dependency('gemcutter')
 
   s.rdoc_options << '--title' << s.name << '--main' << 'README.rdoc' << '--line-numbers' << '--inline-source'
-  s.extra_rdoc_files = ['README.rdoc']
+  s.extra_rdoc_files = ['README.rdoc', 'BENCHMARKS.rdoc']
 
   # Do not change the files and test_files fields by hand. This will be done
   # automatically by the gem release script.
-  s.files      = %w(.bundle/config .gitignore Gemfile Gemfile.lock LICENSE README.rdoc Rakefile chunky_png.gemspec lib/chunky_png.rb lib/chunky_png/canvas.rb lib/chunky_png/canvas/adam7_interlacing.rb lib/chunky_png/canvas/drawing.rb lib/chunky_png/canvas/operations.rb lib/chunky_png/canvas/png_decoding.rb lib/chunky_png/canvas/png_encoding.rb lib/chunky_png/canvas/stream_exporting.rb lib/chunky_png/canvas/stream_importing.rb lib/chunky_png/chunk.rb lib/chunky_png/color.rb lib/chunky_png/datastream.rb lib/chunky_png/image.rb lib/chunky_png/palette.rb lib/chunky_png/rmagick.rb spec/chunky_png/canvas/adam7_interlacing_spec.rb spec/chunky_png/canvas/drawing_spec.rb spec/chunky_png/canvas/operations_spec.rb spec/chunky_png/canvas/png_decoding_spec.rb spec/chunky_png/canvas/png_encoding_spec.rb spec/chunky_png/canvas_spec.rb spec/chunky_png/color_spec.rb spec/chunky_png/datastream_spec.rb spec/chunky_png/image_spec.rb spec/chunky_png/rmagick_spec.rb spec/chunky_png_spec.rb spec/resources/16x16_interlaced.png spec/resources/16x16_non_interlaced.png spec/resources/adam7.png spec/resources/clock.png spec/resources/clock_base.png spec/resources/clock_flip_horizontally.png spec/resources/clock_flip_vertically.png spec/resources/clock_mask.png spec/resources/clock_mask_updated.png spec/resources/clock_rotate_180.png spec/resources/clock_rotate_left.png spec/resources/clock_rotate_right.png spec/resources/clock_stubbed.png spec/resources/clock_updated.png spec/resources/composited.png spec/resources/cropped.png spec/resources/damaged_chunk.png spec/resources/damaged_signature.png spec/resources/gray_10x10.png spec/resources/gray_10x10_grayscale.png spec/resources/gray_10x10_grayscale_alpha.png spec/resources/gray_10x10_indexed.png spec/resources/gray_10x10_truecolor.png spec/resources/gray_10x10_truecolor_alpha.png spec/resources/indexed_4bit.png spec/resources/lines.png spec/resources/operations.png spec/resources/pixelstream.rgb spec/resources/pixelstream.rgba spec/resources/pixelstream_reference.png spec/resources/rect.png spec/resources/replaced.png spec/resources/text_chunk.png spec/resources/transparent_gray_10x10.png spec/resources/ztxt_chunk.png spec/spec_helper.rb tasks/github-gem.rake)
-  s.test_files = %w(spec/chunky_png/canvas/adam7_interlacing_spec.rb spec/chunky_png/canvas/drawing_spec.rb spec/chunky_png/canvas/operations_spec.rb spec/chunky_png/canvas/png_decoding_spec.rb spec/chunky_png/canvas/png_encoding_spec.rb spec/chunky_png/canvas_spec.rb spec/chunky_png/color_spec.rb spec/chunky_png/datastream_spec.rb spec/chunky_png/image_spec.rb spec/chunky_png/rmagick_spec.rb spec/chunky_png_spec.rb)
+  s.files      = %w(tasks/github-gem.rake lib/chunky_png/canvas.rb spec/resources/composited.png lib/chunky_png/canvas/drawing.rb spec/resources/gray_10x10_grayscale_alpha.png spec/resources/cropped.png LICENSE spec/resources/clock_mask_updated.png spec/resources/pixelstream.rgba Gemfile spec/resources/clock_rotate_right.png spec/resources/ztxt_chunk.png spec/resources/transparent_gray_10x10.png lib/chunky_png/canvas/png_decoding.rb lib/chunky_png/image.rb spec/resources/lines.png spec/resources/clock_mask.png spec/resources/clock_stubbed.png spec/resources/pixelstream.rgb tasks/benchmarks.rake spec/resources/indexed_4bit.png spec/resources/text_chunk.png chunky_png.gemspec benchmarks/decoding_benchmark.rb spec/resources/gray_10x10_truecolor_alpha.png lib/chunky_png/color.rb spec/resources/damaged_chunk.png spec/resources/rect.png README.rdoc lib/chunky_png/canvas/stream_exporting.rb spec/resources/clock_flip_horizontally.png lib/chunky_png/canvas/stream_importing.rb spec/chunky_png/canvas/adam7_interlacing_spec.rb spec/spec_helper.rb lib/chunky_png/rmagick.rb Gemfile.lock Rakefile spec/chunky_png/canvas/png_decoding_spec.rb lib/chunky_png.rb lib/chunky_png/canvas/png_encoding.rb .gitignore spec/resources/16x16_interlaced.png spec/chunky_png/canvas/drawing_spec.rb spec/chunky_png/canvas/png_encoding_spec.rb spec/resources/adam7.png lib/chunky_png/palette.rb spec/resources/gray_10x10_indexed.png spec/chunky_png/canvas_spec.rb spec/resources/clock.png benchmarks/encoding_benchmark.rb spec/chunky_png/image_spec.rb spec/resources/clock_rotate_180.png spec/resources/clock_rotate_left.png BENCHMARKS.rdoc spec/resources/16x16_non_interlaced.png lib/chunky_png/chunk.rb spec/chunky_png/canvas/operations_spec.rb spec/resources/gray_10x10_truecolor.png spec/resources/gray_10x10_grayscale.png spec/resources/pixelstream_reference.png spec/chunky_png_spec.rb spec/resources/operations.png spec/resources/clock_flip_vertically.png spec/chunky_png/rmagick_spec.rb lib/chunky_png/datastream.rb spec/resources/clock_base.png lib/chunky_png/canvas/operations.rb spec/resources/replaced.png spec/resources/clock_updated.png spec/resources/damaged_signature.png spec/chunky_png/datastream_spec.rb lib/chunky_png/canvas/adam7_interlacing.rb spec/chunky_png/color_spec.rb spec/resources/gray_10x10.png)
+  s.test_files = %w(spec/chunky_png/canvas/adam7_interlacing_spec.rb spec/chunky_png/canvas/png_decoding_spec.rb spec/chunky_png/canvas/drawing_spec.rb spec/chunky_png/canvas/png_encoding_spec.rb spec/chunky_png/canvas_spec.rb spec/chunky_png/image_spec.rb spec/chunky_png/canvas/operations_spec.rb spec/chunky_png_spec.rb spec/chunky_png/rmagick_spec.rb spec/chunky_png/datastream_spec.rb spec/chunky_png/color_spec.rb)
 end

data/lib/chunky_png.rb

@@ -27,7 +27,7 @@ module ChunkyPNG
 
   # The current version of ChunkyPNG. This value will be updated automatically
   # by them gem:release rake task.
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 
   ###################################################
   # PNG international standard defined constants

data/lib/chunky_png/canvas/operations.rb

@@ -1,17 +1,49 @@
 module ChunkyPNG
   class Canvas
+    
+    # The ChunkyPNG::Canvas::Operations module defines methods to perform operations
+    # on a {ChunkyPNG::Canvas}. The module is included into the Canvas class so all
+    # these methods are available on every canvas.
+    #
+    # Note that some of these operations modify the canvas, while some operations return 
+    # a new canvas and leave the original intact.
+    #
+    # @see ChunkyPNG::Canvas
     module Operations
-      def compose(new_foreground, dx = 0, dy = 0)
-        check_size_constraints!(new_foreground, dx, dy)
+      
+      # Composes another image onto this image using alpha blending.
+      #
+      # If you simply want to replace pixels or when the other image does not have
+      # transparency, it is faster to use {#replace}.
+      #
+      # @param [ChunkyPNG::Canvas] other The foreground canvas to compose on the
+      #     current canvas, using alpha compositing.
+      # @param [Integer] offset_x The x-offset to apply the new forgeround on.
+      # @param [Integer] offset_y The y-offset to apply the new forgeround on.
+      # @return [ChunkyPNG::Canvas] Returns itself, but with the other canvas composed onto it.
+      # @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on this one,
+      #     given the offset and size of the other canavs.
+      # @see #replace
+      def compose(other, offset_x = 0, offset_y = 0)
+        check_size_constraints!(other, offset_x, offset_y)
 
-        for y in 0...new_foreground.height do
-          for x in 0...new_foreground.width do
-            self[x+dx, y+dy] = ChunkyPNG::Color.compose(new_foreground[x, y], self[x+dx, y+dy])
+        for y in 0...other.height do
+          for x in 0...other.width do
+            self[x + offset_x, y + offset_y] = ChunkyPNG::Color.compose(other[x, y], self[x + offset_x, y + offset_y])
           end
         end
         self
       end
 
+      # Replaces pixels on this image by pixels from another pixels, on a given offset.
+      #
+      # This will completely replace the pixels of the background image. If you want to blend
+      # them with semi-transparent pixels from the foreground image, see {#compose}.
+      #
+      # @return [ChunkyPNG::Canvas] Returns itself, but with the other canvas composed onto it.
+      # @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on this one,
+      #     given the offset and size of the other canavs.
+      # @see #compose
       def replace(other, offset_x = 0, offset_y = 0)
         check_size_constraints!(other, offset_x, offset_y)
 
@@ -21,7 +53,22 @@ module ChunkyPNG
         self
       end
 
+      # Crops an image, given the coordinates and size of the image that needs to be cut out.
+      # This will leave the original image intact and return a new, cropped image with pixels
+      # copied from the original image.
+      #
+      # @param [Integer] x The x-coordinate of the top left corner of the image to be cropped.
+      # @param [Integer] y The y-coordinate of the top left corner of the image to be cropped.
+      # @param [Integer] crop_width The width of the image to be cropped.
+      # @param [Integer] crop_height The height of the image to be cropped.
+      # @return [ChunkyPNG::Canvas] Returns the newly created cropped image.
+      # @raise [ChunkyPNG::OutOfBounds] when the crop dimensions plus the given coordinates 
+      #     are bigger then the original image.
       def crop(x, y, crop_width, crop_height)
+        
+        raise ChunkyPNG::OutOfBounds, "Image width is too small!" if crop_width + x > width
+        raise ChunkyPNG::OutOfBounds, "Image width is too small!" if crop_height + y > height
+        
         new_pixels = []
         for cy in 0...crop_height do
           new_pixels += pixels.slice((cy + y) * width + x, crop_width)
@@ -29,13 +76,52 @@ module ChunkyPNG
         ChunkyPNG::Canvas.new(crop_width, crop_height, new_pixels)
       end
       
+      # Creates a new image, based on the current image but with a new theme color.
+      #
+      # This method will replace one color in an image with another image. This is done by
+      # first extracting the pixels with a color close to the original theme color as a mask
+      # image, changing the color of this mask image and then apply it on the original image.
+      #
+      # Mask extraction works best when the theme colored pixels are clearly distinguishable
+      # from a background color (preferably white). You can set a tolerance level to influence
+      # the extraction process.
+      #
+      # @param [Integer] old_theme_color The original theme color in this image.
+      # @param [Integer] new_theme_color The color to replace the old theme color with.
+      # @param [Integer] The backrgound color opn which the theme colored pixels are placed.
+      # @param [Integer] tolerance The tolerance level to use when extracting the mask image. Five is 
+      #    the default; increase this if the masked image does not extract all the required pixels, 
+      #    decrease it if too many pixels get extracted.
+      # @return [ChunkyPNG::Canvas] Returns itself, but with the theme colored pixels changed.
+      # @see #change_theme_color!
+      # @see #change_mask_color!
       def change_theme_color!(old_theme_color, new_theme_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5)
         base, mask = extract_mask(old_theme_color, bg_color, tolerance)
         mask.change_mask_color!(new_theme_color)
         self.replace(base.compose(mask))
       end
       
-      def extract_mask(mask_color, bg_color, tolerance = 5)
+      # Creates a base image and a mask image from an original image that has a particular theme color.
+      # This can be used to easily change a theme color in an image.
+      #
+      # It will extract all the pixels that look like the theme color (with a tolerance level) and put
+      # these in a mask image. All the other pixels will be stored in a base image. Both images will be
+      # of the exact same size as the original image. The original image will be left untouched.
+      #
+      # The color of the mask image can be changed with {#change_mask_color!}. This new mask image can 
+      # then be composed upon the base image to create an image with a new theme color. A call to 
+      # {#change_theme_color!} will perform this in one go.
+      #
+      # @param [Integer] mask_color The current theme color.
+      # @param [Integer] bg_color The background color on which the theme colored pxiels are applied.
+      # @param [Integer] tolerance The tolerance level to use when extracting the mask image. Five is 
+      #    the default; increase this if the masked image does not extract all the required pixels, 
+      #    decrease it if too many pixels get extracted.
+      # @return [Array<ChunkyPNG::Canvas, ChunkyPNG::Canvas>] An array with the base canvas and the mask 
+      #    canvas as elements.
+      # @see #change_theme_color!
+      # @see #change_mask_color!
+      def extract_mask(mask_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5)
         base_pixels = []
         mask_pixels = []
 
@@ -52,11 +138,30 @@ module ChunkyPNG
         [ self.class.new(width, height, base_pixels), self.class.new(width, height, mask_pixels) ]
       end
       
+      # Changes the color of a mask image.
+      #
+      # This method works on acanavs extracte out of another image using the {#extract_mask} method.
+      # It can then be applied on the extracted base image. See {#change_theme_color!} to perform
+      # these operations in one go.
+      #
+      # @param [Integer] new_color The color to replace the original mask color with.
+      # @raise [ChunkyPNG::ExpectationFailed] when this canvas is not a mask image, i.e. its palette
+      #    has more than once color, disregarding transparency.
+      # @see #change_theme_color!
+      # @see #extract_mask
       def change_mask_color!(new_color)
         raise ChunkyPNG::ExpectationFailed, "This is not a mask image!" if palette.opaque_palette.size != 1
         pixels.map! { |pixel| (new_color & 0xffffff00) | ChunkyPNG::Color.a(pixel) }
+        self
       end
       
+      # Flips the image horizontally.
+      #
+      # This will flip the image on its horizontal axis, e.g. pixels on the top will now
+      # be pixels on the bottom. Chaining this method twice will return the original canvas.
+      # This method will leave the original object intact and return a new canvas.
+      #
+      # @return [ChunkyPNG::Canvas] The flipped image
       def flip_horizontally
         self.class.new(width, height).tap do |flipped|
           for y in 0...height do
@@ -65,6 +170,13 @@ module ChunkyPNG
         end
       end
       
+      # Flips the image horizontally.
+      #
+      # This will flip the image on its vertical axis, e.g. pixels on the left will now
+      # be pixels on the right. Chaining this method twice will return the original canvas.
+      # This method will leave the original object intact and return a new canvas.
+      #
+      # @return [ChunkyPNG::Canvas] The flipped image
       def flip_vertically
         self.class.new(width, height).tap do |flipped|
           for x in 0...width do
@@ -73,6 +185,10 @@ module ChunkyPNG
         end
       end
 
+      # Rotates the image 90 degrees clockwise.
+      # This method will leave the original object intact and return a new canvas.
+      #
+      # @return [ChunkyPNG::Canvas] The rotated image
       def rotate_right
         self.class.new(height, width).tap do |rotated|
           for i in 0...width do
@@ -81,6 +197,10 @@ module ChunkyPNG
         end
       end
       
+      # Rotates the image 90 degrees counter-clockwise.
+      # This method will leave the original object intact and return a new canvas.
+      #
+      # @return [ChunkyPNG::Canvas] The rotated image.
       def rotate_left
         self.class.new(height, width).tap do |rotated|
           for i in 0...width do
@@ -89,6 +209,10 @@ module ChunkyPNG
         end
       end
       
+      # Rotates the image 180 degrees.
+      # This method will leave the original object intact and return a new canvas.
+      #
+      # @return [ChunkyPNG::Canvas] The rotated image.
       def rotate_180
         self.class.new(width, height).tap do |flipped|
           for y in 0...height do
@@ -98,10 +222,16 @@ module ChunkyPNG
       end
 
       protected
-
+      
+      # Checks whether another image has the correct dimension to be used for an operation
+      # on the current image, given an offset coordinate to work with.
+      # @param [ChunkyPNG::Canvas] other The other canvas
+      # @param [Integer] offset_x The x offset on which the other image will be applied.
+      # @param [Integer] offset_y The y offset on which the other image will be applied.
+      # @raise [ChunkyPNG::OutOfBounds] when the other image doesn't fit.
       def check_size_constraints!(other, offset_x, offset_y)
-        raise ChunkyPNG::ExpectationFailed, "Background image width is too small!"  if width  < other.width  + offset_x
-        raise ChunkyPNG::ExpectationFailed, "Background image height is too small!" if height < other.height + offset_y
+        raise ChunkyPNG::OutOfBounds, "Background image width is too small!"  if width  < other.width  + offset_x
+        raise ChunkyPNG::OutOfBounds, "Background image height is too small!" if height < other.height + offset_y
       end
     end
   end

data/lib/chunky_png/datastream.rb

@@ -37,7 +37,6 @@ module ChunkyPNG
     # @return [ChunkyPNG::Chunk::Header]
     attr_accessor :end_chunk
 
-
     # Initializes a new Datastream instance.
     def initialize
       @other_chunks = []
@@ -94,6 +93,7 @@ module ChunkyPNG
       # This method reads the PNG signature from the stream, setting the current position
       # of the stream directly after the signature, where the IHDR chunk should begin.
       #
+      # @param [IO] io The stream to read the PNG signature from.
       # @raise [RuntimeError] An exception is raised if the PNG signature is not found at
       #    the beginning of the stream.
       def verify_signature!(io)
@@ -133,6 +133,7 @@ module ChunkyPNG
     end
     
     # Returns all the textual metadata key/value pairs as hash.
+    # @return [Hash] A hash containing metadata fields and their values.
     def metadata
       metadata = {}
       other_chunks.select do |chunk|

data/lib/chunky_png/image.rb

@@ -1,24 +1,45 @@
 module ChunkyPNG
 
-  # Image class
+  # ChunkyPNG::Image is an extension of the {ChunkyPNG::Canvas} class, that
+  # also includes support for metadata.
   #
+  # @see ChunkyPNG::Canvas
   class Image < Canvas
 
+    # The minimumsize of bytes the value of a metadata field should be before compression
+    # is enabled for the chunk.
     METADATA_COMPRESSION_TRESHOLD = 300
     
+    # @return [Hash] The hash of metadata fields for this PNG image.
     attr_accessor :metadata
     
-    def initialize(width, height, initial = ChunkyPNG::Color::TRANSPARENT, metadata = {})
-      super(width, height, initial)
+    # Initializes a new ChunkyPNG::Image instance.
+    # @param [Integer] width The width of the new image.
+    # @param [Integer] height The height of the new image.
+    # @param [Integer] bg_color The background color of the new image.
+    # @param [Hash] metadata A hash of metadata fields and values for this image.
+    # @see ChunkyPNG::Canvas#initialize
+    def initialize(width, height, bg_color = ChunkyPNG::Color::TRANSPARENT, metadata = {})
+      super(width, height, bg_color)
       @metadata = metadata
-      @metadata_compression_treshhold = 300
     end
     
+    # Initializes a copy of another ChunkyPNG::Image instance.
+    #
+    # @param [ChunkyPNG::Image] other The other image to copy.
     def initialize_copy(other)
       super(other)
-      @metdata = other.metadata
+      @metadata = other.metadata
     end
     
+    # Returns the metadata for this image as PNG chunks.
+    #
+    # Chunks will either be of the {ChunkyPNG::Chunk::Text} type for small
+    # values (in bytes), or of the {ChunkyPNG::Chunk::CompressedText} type
+    # for values that are larger in size.
+    #
+    # @return [Array<ChunkyPNG::Chunk>] An array of metadata chunks.
+    # @see ChunkyPNG::Image::METADATA_COMPRESSION_TRESHOLD
     def metadata_chunks
       metadata.map do |key, value|
         if value.length >= METADATA_COMPRESSION_TRESHOLD
@@ -29,12 +50,26 @@ module ChunkyPNG
       end
     end
     
+    # Encodes the image to a PNG datastream for saving to disk or writing to an IO stream.
+    #
+    # Besides encoding the canvas, it will also encode the metadata fields to text chunks.
+    #
+    # @param [Hash] constraints The constraints to use when encoding the canvas.
+    # @return [ChunkyPNG::Datastream] The datastream that contains this image.
+    # @see ChunkyPNG::Canvas::PNGEncoding#to_datastream
+    # @see #metadata_chunks
     def to_datastream(constraints = {})
       ds = super(constraints)
       ds.other_chunks += metadata_chunks
       return ds
     end
     
+    # Reads a ChunkyPNG::Image intance from a data stream.
+    #
+    # Besides decoding the canvas, this will also read the metadata fields
+    # from the datastream.
+    #
+    # @param [ChunkyPNG::Datastream] The datastream to read from.
     def self.from_datastream(ds)
       image = super(ds)
       image.metadata = ds.metadata

data/spec/chunky_png/canvas/operations_spec.rb

@@ -2,19 +2,21 @@ require 'spec_helper'
 
 describe ChunkyPNG::Canvas::Operations do
   describe '#crop' do
-    before(:each) do
-      @canvas = ChunkyPNG::Canvas.from_file(resource_file('operations.png'))
-    end
+    before { @canvas = reference_canvas('operations') }
 
     it "should crop the right pixels from the original canvas" do
       cropped = @canvas.crop(10, 5, 4, 8)
       cropped.should == reference_canvas('cropped')
     end
+    
+    it "should raise an exception when the cropped image falls outside the oiginal image" do
+      lambda { @canvas.crop(16, 16, 2, 2) }.should raise_error(ChunkyPNG::OutOfBounds)
+    end
   end
 
   describe '#compose' do
     it "should compose pixels correctly" do
-      canvas = ChunkyPNG::Canvas.from_file(resource_file('operations.png'))
+      canvas = reference_canvas('operations')
       subcanvas = ChunkyPNG::Canvas.new(4, 8, ChunkyPNG::Color.rgba(0, 0, 0, 75))
       canvas.compose(subcanvas, 8, 4)
       canvas.should == reference_canvas('composited')
@@ -25,18 +27,24 @@ describe ChunkyPNG::Canvas::Operations do
       mask = reference_canvas('clock_mask_updated')
       base.compose(mask).should == reference_canvas('clock_updated')
     end
+    
+    it "should raise an exception when the pixels to compose fall outside the image" do
+      lambda { reference_canvas('operations').compose(ChunkyPNG::Canvas.new(1,1), 16, 16) }.should raise_error(ChunkyPNG::OutOfBounds)
+    end
   end
 
   describe '#replace' do
-    before(:each) do
-      @canvas = ChunkyPNG::Canvas.from_file(resource_file('operations.png'))
-    end
+    before { @canvas = reference_canvas('operations') }
 
     it "should replace the correct pixels" do
       subcanvas = ChunkyPNG::Canvas.new(3, 2, ChunkyPNG::Color.rgb(200, 255, 0))
       @canvas.replace(subcanvas, 5, 4)
       @canvas.should == reference_canvas('replaced')
     end
+    
+    it "should raise an exception when the pixels to replace fall outside the image" do
+      lambda { @canvas.replace(ChunkyPNG::Canvas.new(1,1), 16, 16) }.should raise_error(ChunkyPNG::OutOfBounds)
+    end
   end
   
   describe '#change_theme_color!' do
@@ -86,35 +94,80 @@ describe ChunkyPNG::Canvas::Operations do
       @mask.change_mask_color!(@new_color)
       @mask.palette.opaque_palette.size.should == 1
     end
+    
+    it "should raise an exception when the mask image has more than once color" do
+      not_a_mask = reference_canvas('operations')
+      lambda { not_a_mask.change_mask_color!(@new_color) }.should raise_error(ChunkyPNG::ExpectationFailed)
+    end
   end
-  
+end
+
+describe ChunkyPNG::Canvas::Operations do
+  before { @stubbed = reference_canvas('clock_stubbed') }
+
   describe '#flip_horizontally' do
     it "should flip the pixels horizontally" do
-      reference_canvas('clock_stubbed').flip_horizontally.should == reference_canvas('clock_flip_horizontally')
+      @stubbed.flip_horizontally.should == reference_canvas('clock_flip_horizontally')
+    end
+    
+    it "should return itself when applied twice" do
+      @stubbed.flip_horizontally.flip_horizontally.should == @stubbed
     end
   end
-  
+
   describe '#flip_vertically' do
     it "should flip the pixels vertically" do
-      reference_canvas('clock_stubbed').flip_vertically.should == reference_canvas('clock_flip_vertically')
+      @stubbed.flip_vertically.should == reference_canvas('clock_flip_vertically')
+    end
+    
+    it "should return itself when applied twice" do
+      @stubbed.flip_vertically.flip_vertically.should == @stubbed
     end
   end
 
   describe '#rotate_left' do
     it "should rotate the pixels 90 degrees counter-clockwise" do
-      reference_canvas('clock_stubbed').rotate_left.should == reference_canvas('clock_rotate_left')
+      @stubbed.rotate_left.should == reference_canvas('clock_rotate_left')
+    end
+    
+    it "it should rotate 180 degrees when applied twice" do
+      @stubbed.rotate_left.rotate_left.should == reference_canvas('clock_rotate_180')
+    end
+    
+    it "it should rotate right when applied three times" do
+      @stubbed.rotate_left.rotate_left.rotate_left.should == reference_canvas('clock_rotate_right')
+    end
+    
+    it "should return itself when applied four times" do
+      @stubbed.rotate_left.rotate_left.rotate_left.rotate_left.should == @stubbed
     end
   end
-  
+
   describe '#rotate_right' do
     it "should rotate the pixels 90 degrees clockwise" do
-      reference_canvas('clock_stubbed').rotate_right.should == reference_canvas('clock_rotate_right')
+      @stubbed.rotate_right.should == reference_canvas('clock_rotate_right')
+    end
+    
+    it "it should rotate 180 degrees when applied twice" do
+      @stubbed.rotate_right.rotate_right.should == reference_canvas('clock_rotate_180')
+    end
+    
+    it "it should rotate left when applied three times" do
+      @stubbed.rotate_right.rotate_right.rotate_right.should == reference_canvas('clock_rotate_left')
+    end
+    
+    it "should return itself when applied four times" do
+      @stubbed.rotate_right.rotate_right.rotate_right.rotate_right.should == @stubbed
     end
   end
-  
+
   describe '#rotate_180' do
     it "should rotate the pixels 180 degrees" do
-      reference_canvas('clock_stubbed').rotate_180.should == reference_canvas('clock_rotate_180')
+      @stubbed.rotate_180.should == reference_canvas('clock_rotate_180')
+    end
+    
+    it "should return itself when applied twice" do
+      @stubbed.rotate_180.rotate_180.should == @stubbed
     end
   end
 end

data/tasks/benchmarks.rake

@@ -0,0 +1,26 @@
+all_benchamrk_tasks = []
+
+namespace(:benchmark) do
+  
+  Dir[File.join(File.dirname(__FILE__), '..', 'benchmarks', '*_benchmark.rb')]. each do |benchmark_file|
+    task_name = File.basename(benchmark_file, '_benchmark.rb').to_sym
+    
+    desc "Run the #{task_name} benchmark."
+    task(task_name, :n) do |task, args|
+      ENV['N'] = args[:n] if args[:n]
+      load(File.expand_path(benchmark_file))
+    end
+    
+    all_benchamrk_tasks << "benchmark:#{task_name}"
+  end
+end
+
+unless all_benchamrk_tasks.empty?
+  desc 'Run the whole benchmark suite'
+  task(:benchmark, :n) do |task, args|
+    all_benchamrk_tasks.each do |t| 
+      task(t).invoke(args[:n])
+      puts
+    end
+  end
+end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: chunky_png
 version: !ruby/object:Gem::Version 
+  hash: 57
   prerelease: false
   segments: 
   - 0
   - 9
-  - 0
-  version: 0.9.0
+  - 1
+  version: 0.9.1
 platform: ruby
 authors: 
 - Willem van Bergen
@@ -14,62 +15,66 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-18 00:00:00 -04:00
+date: 2010-09-16 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rake
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
+  requirement: *id001
   type: :development
+  name: rake
   prerelease: false
-  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rspec
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 9
         segments: 
         - 1
         - 3
         version: "1.3"
+  requirement: *id002
   type: :development
+  name: rspec
   prerelease: false
-  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: git
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
+  requirement: *id003
   type: :development
+  name: git
   prerelease: false
-  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: gemcutter
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
+  requirement: *id004
   type: :development
+  name: gemcutter
   prerelease: false
-  version_requirements: *id004
 description: "    This pure Ruby library can read and write PNG images without depending on an external \n    image library, like RMagick. It tries to be memory efficient and reasonably fast.\n    \n    It supports reading and writing all PNG variants that are defined in the specification, \n    with one limitation: only 8-bit color depth is supported. It supports all transparency, \n    interlacing and filtering options the PNG specifications allows. It can also read and \n    write textual metadata from PNG files. Low-level read/write access to PNG chunks is\n    also possible.\n    \n    This library supports simple drawing on the image canvas and simple operations like alpha composition\n    and cropping. Finally, it can import from and export to RMagick for interoperability. \n"
 email: 
 - willem@railsdoctors.com
@@ -79,78 +84,82 @@ extensions: []
 
 extra_rdoc_files: 
 - README.rdoc
+- BENCHMARKS.rdoc
 files: 
-- .bundle/config
-- .gitignore
-- Gemfile
-- Gemfile.lock
-- LICENSE
-- README.rdoc
-- Rakefile
-- chunky_png.gemspec
-- lib/chunky_png.rb
+- tasks/github-gem.rake
 - lib/chunky_png/canvas.rb
-- lib/chunky_png/canvas/adam7_interlacing.rb
+- spec/resources/composited.png
 - lib/chunky_png/canvas/drawing.rb
-- lib/chunky_png/canvas/operations.rb
+- spec/resources/gray_10x10_grayscale_alpha.png
+- spec/resources/cropped.png
+- LICENSE
+- spec/resources/clock_mask_updated.png
+- spec/resources/pixelstream.rgba
+- Gemfile
+- spec/resources/clock_rotate_right.png
+- spec/resources/ztxt_chunk.png
+- spec/resources/transparent_gray_10x10.png
 - lib/chunky_png/canvas/png_decoding.rb
-- lib/chunky_png/canvas/png_encoding.rb
+- lib/chunky_png/image.rb
+- spec/resources/lines.png
+- spec/resources/clock_mask.png
+- spec/resources/clock_stubbed.png
+- spec/resources/pixelstream.rgb
+- tasks/benchmarks.rake
+- spec/resources/indexed_4bit.png
+- spec/resources/text_chunk.png
+- chunky_png.gemspec
+- benchmarks/decoding_benchmark.rb
+- spec/resources/gray_10x10_truecolor_alpha.png
+- lib/chunky_png/color.rb
+- spec/resources/damaged_chunk.png
+- spec/resources/rect.png
+- README.rdoc
 - lib/chunky_png/canvas/stream_exporting.rb
+- spec/resources/clock_flip_horizontally.png
 - lib/chunky_png/canvas/stream_importing.rb
-- lib/chunky_png/chunk.rb
-- lib/chunky_png/color.rb
-- lib/chunky_png/datastream.rb
-- lib/chunky_png/image.rb
-- lib/chunky_png/palette.rb
-- lib/chunky_png/rmagick.rb
 - spec/chunky_png/canvas/adam7_interlacing_spec.rb
-- spec/chunky_png/canvas/drawing_spec.rb
-- spec/chunky_png/canvas/operations_spec.rb
+- spec/spec_helper.rb
+- lib/chunky_png/rmagick.rb
+- Gemfile.lock
+- Rakefile
 - spec/chunky_png/canvas/png_decoding_spec.rb
-- spec/chunky_png/canvas/png_encoding_spec.rb
-- spec/chunky_png/canvas_spec.rb
-- spec/chunky_png/color_spec.rb
-- spec/chunky_png/datastream_spec.rb
-- spec/chunky_png/image_spec.rb
-- spec/chunky_png/rmagick_spec.rb
-- spec/chunky_png_spec.rb
+- lib/chunky_png.rb
+- lib/chunky_png/canvas/png_encoding.rb
+- .gitignore
 - spec/resources/16x16_interlaced.png
-- spec/resources/16x16_non_interlaced.png
+- spec/chunky_png/canvas/drawing_spec.rb
+- spec/chunky_png/canvas/png_encoding_spec.rb
 - spec/resources/adam7.png
+- lib/chunky_png/palette.rb
+- spec/resources/gray_10x10_indexed.png
+- spec/chunky_png/canvas_spec.rb
 - spec/resources/clock.png
-- spec/resources/clock_base.png
-- spec/resources/clock_flip_horizontally.png
-- spec/resources/clock_flip_vertically.png
-- spec/resources/clock_mask.png
-- spec/resources/clock_mask_updated.png
+- benchmarks/encoding_benchmark.rb
+- spec/chunky_png/image_spec.rb
 - spec/resources/clock_rotate_180.png
 - spec/resources/clock_rotate_left.png
-- spec/resources/clock_rotate_right.png
-- spec/resources/clock_stubbed.png
-- spec/resources/clock_updated.png
-- spec/resources/composited.png
-- spec/resources/cropped.png
-- spec/resources/damaged_chunk.png
-- spec/resources/damaged_signature.png
-- spec/resources/gray_10x10.png
-- spec/resources/gray_10x10_grayscale.png
-- spec/resources/gray_10x10_grayscale_alpha.png
-- spec/resources/gray_10x10_indexed.png
+- BENCHMARKS.rdoc
+- spec/resources/16x16_non_interlaced.png
+- lib/chunky_png/chunk.rb
+- spec/chunky_png/canvas/operations_spec.rb
 - spec/resources/gray_10x10_truecolor.png
-- spec/resources/gray_10x10_truecolor_alpha.png
-- spec/resources/indexed_4bit.png
-- spec/resources/lines.png
-- spec/resources/operations.png
-- spec/resources/pixelstream.rgb
-- spec/resources/pixelstream.rgba
+- spec/resources/gray_10x10_grayscale.png
 - spec/resources/pixelstream_reference.png
-- spec/resources/rect.png
+- spec/chunky_png_spec.rb
+- spec/resources/operations.png
+- spec/resources/clock_flip_vertically.png
+- spec/chunky_png/rmagick_spec.rb
+- lib/chunky_png/datastream.rb
+- spec/resources/clock_base.png
+- lib/chunky_png/canvas/operations.rb
 - spec/resources/replaced.png
-- spec/resources/text_chunk.png
-- spec/resources/transparent_gray_10x10.png
-- spec/resources/ztxt_chunk.png
-- spec/spec_helper.rb
-- tasks/github-gem.rake
+- spec/resources/clock_updated.png
+- spec/resources/damaged_signature.png
+- spec/chunky_png/datastream_spec.rb
+- lib/chunky_png/canvas/adam7_interlacing.rb
+- spec/chunky_png/color_spec.rb
+- spec/resources/gray_10x10.png
 has_rdoc: true
 homepage: http://wiki.github.com/wvanbergen/chunky_png
 licenses: []
@@ -170,7 +179,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 2219291082232343403
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -179,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 2219291082232343403
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -192,13 +201,13 @@ specification_version: 3
 summary: Pure ruby library for read/write, chunk-level access to PNG files
 test_files: 
 - spec/chunky_png/canvas/adam7_interlacing_spec.rb
-- spec/chunky_png/canvas/drawing_spec.rb
-- spec/chunky_png/canvas/operations_spec.rb
 - spec/chunky_png/canvas/png_decoding_spec.rb
+- spec/chunky_png/canvas/drawing_spec.rb
 - spec/chunky_png/canvas/png_encoding_spec.rb
 - spec/chunky_png/canvas_spec.rb
-- spec/chunky_png/color_spec.rb
-- spec/chunky_png/datastream_spec.rb
 - spec/chunky_png/image_spec.rb
-- spec/chunky_png/rmagick_spec.rb
+- spec/chunky_png/canvas/operations_spec.rb
 - spec/chunky_png_spec.rb
+- spec/chunky_png/rmagick_spec.rb
+- spec/chunky_png/datastream_spec.rb
+- spec/chunky_png/color_spec.rb

data/.bundle/config

@@ -1,2 +0,0 @@
---- 
-BUNDLE_DISABLE_SHARED_GEMS: "1"