chunky_png 1.0.0.rc1 → 1.0.0.rc2

data/.yardopts

@@ -1,3 +1,5 @@
 --title "ChunkyPNG - The pure Ruby PNG library"
 lib/**/*.rb -
 BENCHMARKS.rdoc
+--no-private
+--hide-void-return

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 = "1.0.0.rc1"
-  s.date    = "2011-02-24"
+  s.version = "1.0.0.rc2"
+  s.date    = "2011-03-02"
 
   s.summary     = "Pure ruby library for read/write, chunk-level access to PNG files"
   s.description = <<-EOT

data/lib/chunky_png.rb

@@ -4,59 +4,96 @@ require 'zlib'
 require 'stringio'
 require 'enumerator'
 
-# Ruby 1.8 / 1.9 compatibility
-require 'chunky_png/compatibility'
-
-# PNG file structure
-require 'chunky_png/datastream'
-require 'chunky_png/chunk'
-
-# Colors
-require 'chunky_png/palette'
-require 'chunky_png/color'
-
-# Geometry
-require 'chunky_png/point'
-require 'chunky_png/vector'
-require 'chunky_png/dimension'
-
-# Canvas / Image classes
-require 'chunky_png/canvas'
-require 'chunky_png/image'
-
-# ChunkyPNG - the pury ruby library to access PNG files.
+# ChunkyPNG - the pure ruby library to access PNG files.
 #
 # The ChunkyPNG module defines some constants that are used in the
-# PNG specification.
+# PNG specification, specifies some exception classes, and serves as 
+# a namespace for all the other modules and classes in this library.
+#
+# {ChunkyPNG::Image}::      class to represent PNG images, including metadata.
+# {ChunkyPNG::Canvas}::     class to represent the image's canvas.
+# {ChunkyPNG::Color}::      module to work with color values.
+# {ChunkyPNG::Palette}::    represents the palette of colors used on a {ChunkyPNG::Canvas}.
+# {ChunkyPNG::Datastream}:: represents the internal structure of a PNG {ChunkyPNG::Image}.
+# {ChunkyPNG::Color}::      represents one chunk of data within a {ChunkyPNG::Datastream}.
+# {ChunkyPNG::Point}::      geometry helper class representing a 2-dimensional point.
+# {ChunkyPNG::Dimension}::  geometry helper class representing a dimension (i.e. width x height).
+# {ChunkyPNG::Vector}::     geometry helper class representing a series of points.
 #
 # @author Willem van Bergen
 module ChunkyPNG
 
-  # The current version of ChunkyPNG. This value will be updated automatically
-  # by them gem:release rake task.
-  VERSION = "1.0.0.rc1"
+  # The current version of ChunkyPNG. This value will be updated 
+  # automatically by them <tt>gem:release</tt> rake task.
+  VERSION = "1.0.0.rc2"
 
   ###################################################
   # PNG international standard defined constants
   ###################################################
 
+  # Indicates that the PNG image uses grayscale colors, i.e. only a 
+  # single teint channel.
+  # @private
   COLOR_GRAYSCALE       = 0
+  
+  # Indicates that the PNG image uses true color, composed of a red
+  # green and blue channel.
+  # @private
   COLOR_TRUECOLOR       = 2
+  
+  # Indicates that the PNG image uses indexed colors, where the values
+  # point to colors defined on a palette.
+  # @private
   COLOR_INDEXED         = 3
+  
+  # Indicates that the PNG image uses grayscale colors with opacity, i.e.
+  # a teint channel with an alpha channel.
+  # @private
   COLOR_GRAYSCALE_ALPHA = 4
+  
+  # Indicates that the PNG image uses true color with opacity, composed of 
+  # a red, green and blue channel, and an alpha value.
+  # @private
   COLOR_TRUECOLOR_ALPHA = 6
 
-  FILTERING_DEFAULT     = 0
-
+  # Indicates that the PNG specification's default compression
+  # method is used (Zlib/Deflate)
+  # @private
   COMPRESSION_DEFAULT   = 0
 
+  # Indicates that the image does not use interlacing.
+  # @private
   INTERLACING_NONE      = 0
+  
+  # Indicates that the image uses Adam7 interlacing.
+  # @private  
   INTERLACING_ADAM7     = 1
 
+  ### Filter method constants
+
+  # Indicates that the PNG specification's default filtering are
+  # being used in the image.
+  # @private
+  FILTERING_DEFAULT     = 0
+
+  # Indicates that no filtering is used for the scanline.
+  # @private
   FILTER_NONE           = 0
+  
+  # Indicates that SUB filtering is used for the scanline.
+  # @private
   FILTER_SUB            = 1
+  
+  # Indicates that UP filtering is used for the scanline.
+  # @private
   FILTER_UP             = 2
+  
+  # Indicates that AVERAGE filtering is used for the scanline.
+  # @private
   FILTER_AVERAGE        = 3
+  
+  # Indicates that PAETH filtering is used for the scanline.
+  # @private
   FILTER_PAETH          = 4
 
   ###################################################
@@ -88,6 +125,35 @@ module ChunkyPNG
   class OutOfBounds < ChunkyPNG::ExpectationFailed
   end
   
+  # Empty byte array. This basically is an empty string, but with the encoding
+  # set correctly to ASCII-8BIT (binary) in Ruby 1.9.
+  # @return [String] An empty string, with encoding set to binary in Ruby 1.9
+  # @private
   EMPTY_BYTEARRAY = String.method_defined?(:force_encoding) ? "".force_encoding('ASCII-8BIT').freeze : "".freeze
-  EXTRA_BYTE      = String.method_defined?(:force_encoding) ? "\0".force_encoding('ASCII-8BIT') : "\0"
+
+  # Null-byte, with the encoding set correctly to ASCII-8BIT (binary) in Ruby 1.9.
+  # @return [String] A binary string, consisting of one NULL-byte. 
+  # @private
+  EXTRA_BYTE = String.method_defined?(:force_encoding) ? "\0".force_encoding('ASCII-8BIT') : "\0"
 end
+
+
+# Ruby 1.8 / 1.9 compatibility
+require 'chunky_png/compatibility'
+
+# PNG file structure
+require 'chunky_png/datastream'
+require 'chunky_png/chunk'
+
+# Colors
+require 'chunky_png/palette'
+require 'chunky_png/color'
+
+# Geometry
+require 'chunky_png/point'
+require 'chunky_png/vector'
+require 'chunky_png/dimension'
+
+# Canvas / Image classes
+require 'chunky_png/canvas'
+require 'chunky_png/image'

data/lib/chunky_png/canvas.rb

@@ -71,17 +71,17 @@ module ChunkyPNG
 
       @width, @height = width, height
 
-      if initial.kind_of?(Integer)
-        @pixels = Array.new(width * height, initial)
-      elsif initial.kind_of?(Array) && initial.length == width * height
+      if initial.kind_of?(Array) && initial.length == width * height
         @pixels = initial
       else
-        raise ChunkyPNG::ExpectationFailed, "Cannot use this value as initial #{width}x#{height} canvas: #{initial.inspect}!"
+        @pixels = Array.new(width * height, ChunkyPNG::Color(initial))
       end
     end
     
     # Initializes a new Canvas instances when being cloned.
     # @param [ChunkyPNG::Canvas] other The canvas to duplicate
+    # @return [void]
+    # @private
     def initialize_copy(other)
       @width, @height = other.width, other.height
       @pixels = other.pixels.dup
@@ -184,7 +184,7 @@ module ChunkyPNG
     # Returns a single pixel from this canvas, without checking bounds. The return value for
     # this method is undefined if the coordinates are out of bounds.
     # @param (see #[])
-    # @return [ChunkyPNG::Color] The current pixel at the provided coordinates.
+    # @return [Integer] The current pixel at the provided coordinates.
     def get_pixel(x, y)
       @pixels[y * width + x]
     end
@@ -208,6 +208,7 @@ module ChunkyPNG
     # Replaces a row of pixels on this canvas.
     # @param [Integer] y The 0-based row index.
     # @param [Array<Integer>] vector The vector of pixels to replace the row with.
+    # @return [void]
     def replace_row!(y, vector)
       assert_y!(y) && assert_width!(vector.length)
       pixels[y * width, width] = vector
@@ -216,6 +217,7 @@ module ChunkyPNG
     # Replaces a column of pixels on this canvas.
     # @param [Integer] x The 0-based column index.
     # @param [Array<Integer>] vector The vector of pixels to replace the column with.
+    # @return [void]
     def replace_column!(x, vector)
       assert_x!(x) && assert_height!(vector.length)
       for y in 0...height do
@@ -227,7 +229,7 @@ module ChunkyPNG
     # @param [ChunkyPNG::Point, Array, Hash, String] point_like The point to check.
     # @return [true, false] True if the x and y coordinates of the point are  
     #    within the limits of this canvas.
-    # @see ChunkyPNG::Point.single
+    # @see ChunkyPNG.Point
     def include_point?(*point_like)
       dimension.include?(ChunkyPNG::Point(*point_like))
     end
@@ -279,6 +281,7 @@ module ChunkyPNG
     
     # Alternative implementation of the inspect method.
     # @return [String] A nicely formatted string representation of this canvas.
+    # @private
     def inspect
       inspected = "<#{self.class.name} #{width}x#{height} ["
       for y in 0...height
@@ -291,7 +294,7 @@ module ChunkyPNG
     
     # Replaces the image, given a new width, new height, and a new pixel array.
     def replace_canvas!(new_width, new_height, new_pixels)
-      raise ChunkyPNG::ExpectationFailed, "The provided pixel array should have #{new_width * new_height} items" unless new_pixels.length == new_width * new_height
+      raise ArgumentError, "The provided pixel array should have #{new_width * new_height} items" unless new_pixels.length == new_width * new_height
       @width, @height, @pixels = new_width, new_height, new_pixels
       return self
     end

data/lib/chunky_png/canvas/drawing.rb

@@ -22,7 +22,8 @@ module ChunkyPNG
       def compose_pixel(*args)
         point = args.length == 2 ? ChunkyPNG::Point(args.first) : ChunkyPNG::Point(args[0], args[1])
         return unless include?(point)
-        set_pixel(point.x, point.y, ChunkyPNG::Color.compose(args.last, get_pixel(point.x, point.y)))
+        color = ChunkyPNG::Color(args.last)
+        set_pixel(point.x, point.y, ChunkyPNG::Color.compose(color, get_pixel(point.x, point.y)))
       end
       
       # Draws an anti-aliased line using Xiaolin Wu's algorithm.
@@ -36,6 +37,9 @@ module ChunkyPNG
       #    Set to false when drawing multiplelines in a path.
       # @return [ChunkyPNG::Canvas] Itself, with the line drawn.
       def line_xiaolin_wu(x0, y0, x1, y1, stroke_color, inclusive = true)
+        
+        stroke_color = ChunkyPNG::Color(stroke_color)
+        
         dx = x1 - x0
         sx = dx < 0 ? -1 : 1
         dx *= sx
@@ -103,7 +107,10 @@ module ChunkyPNG
       def polygon(path, stroke_color = ChunkyPNG::Color::BLACK, fill_color = ChunkyPNG::Color::TRANSPARENT)
         
         vector = ChunkyPNG::Vector(*path)
-        raise ChunkyPNG::ExpectationFailed, "A polygon requires at least 3 points" if path.length < 3
+        raise ArgumentError, "A polygon requires at least 3 points" if path.length < 3
+
+        stroke_color = ChunkyPNG::Color(stroke_color)
+        fill_color   = ChunkyPNG::Color(fill_color)
 
         # Fill
         unless fill_color == ChunkyPNG::Color::TRANSPARENT
@@ -143,6 +150,9 @@ module ChunkyPNG
       # @return [ChunkyPNG::Canvas] Itself, with the rectangle drawn.
       def rect(x0, y0, x1, y1, stroke_color = ChunkyPNG::Color::BLACK, fill_color = ChunkyPNG::Color::TRANSPARENT)
       
+        stroke_color = ChunkyPNG::Color(stroke_color)
+        fill_color   = ChunkyPNG::Color(fill_color)
+      
         # Fill
         unless fill_color == ChunkyPNG::Color::TRANSPARENT
           [x0, x1].min.upto([x0, x1].max) do |x|
@@ -171,6 +181,9 @@ module ChunkyPNG
       # @return [ChunkyPNG::Canvas] Itself, with the circle drawn.
       def circle(x0, y0, radius, stroke_color = ChunkyPNG::Color::BLACK, fill_color = ChunkyPNG::Color::TRANSPARENT)
 
+        stroke_color = ChunkyPNG::Color(stroke_color)
+        fill_color   = ChunkyPNG::Color(fill_color)
+
         f = 1 - radius
         ddF_x = 1
         ddF_y = -2 * radius

data/lib/chunky_png/canvas/operations.rb

@@ -110,15 +110,7 @@ module ChunkyPNG
       # @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)
-        end
-        ChunkyPNG::Canvas.new(crop_width, crop_height, new_pixels)
+        dup.crop!(x, y, crop_width, crop_height)
       end
       
       # Crops an image, given the coordinates and size of the image that needs to be cut out.
@@ -208,30 +200,58 @@ module ChunkyPNG
       alias_method :mirror!, :flip_vertically!
       alias_method :mirror,  :flip_vertically
 
-      # Rotates the image 90 degrees clockwise.
-      # This method will leave the original object intact and return a new canvas.
+      # Returns a new canvas instance that is rotated 90 degrees clockwise.
+      #
+      # This method will return a new canvas and leaves the original intact. 
+      # See {#rotate_right!} for the in place version.
       #
-      # @return [ChunkyPNG::Canvas] The rotated image
+      # @return [ChunkyPNG::Canvas] A clockwise-rotated copy.
       def rotate_right
+        dup.rotate_right!
+      end
+
+      # Rotates the image 90 degrees clockwise in place.
+      #
+      # This method will change the current canvas. See {#rotate_right} for
+      # a version that leaves th current canvas intact
+      #
+      # @return [ChunkyPNG::Canvas] Itself, but rotated clockwise.
+      def rotate_right!
         rotated = self.class.new(height, width)
-        for i in 0...width do
-          rotated.replace_row!(i, column(i).reverse)
-        end
-        return rotated
+        new_pixels = []
+        0.upto(width - 1) { |i| new_pixels += column(i).reverse }
+        replace_canvas!(height, width, new_pixels)
       end
       
-      # Rotates the image 90 degrees counter-clockwise.
+      alias_method :rotate_clockwise,  :rotate_right
+      alias_method :rotate_clockwise!, :rotate_right!
+      
+      # Returns an image that is rotated 90 degrees counter-clockwise.
+      #
       # This method will leave the original object intact and return a new canvas.
+      # See {#rotate_left!} for the in place version.
       #
-      # @return [ChunkyPNG::Canvas] The rotated image.
+      # @return [ChunkyPNG::Canvas] A rotated copy of itself.
       def rotate_left
-        rotated = self.class.new(height, width)
-        for i in 0...width do
-          rotated.replace_row!(width - (i + 1), column(i))
-        end
-        return rotated
+        dup.rotate_left!
       end
-
+      
+      # Rotates the image 90 degrees counter-clockwise in place.
+      #
+      # This method will change the original canvas. See {#rotate_left} for a
+      # version that leaves the canvas intact and returns a new rototed canvas
+      # instead.
+      #
+      # @return [ChunkyPNG::Canvas] Itself, but rotated.
+      def rotate_left!
+        new_pixels = []
+        (width - 1).downto(0) { |i| new_pixels += column(i) }
+        replace_canvas!(height, width, new_pixels)
+      end
+      
+      alias_method :rotate_counter_clockwise,  :rotate_left
+      alias_method :rotate_counter_clockwise!, :rotate_left!
+      
       # Rotates the image 180 degrees.
       # This method will leave the original object intact and return a new canvas.
       #

data/lib/chunky_png/canvas/png_decoding.rb

@@ -409,7 +409,7 @@ module ChunkyPNG
       #     if this is the first scanline of the image.
       # @param [Integer] line_length The number of bytes in the scanline, discounting the filter method byte.
       # @param [Integer] pixel_size The number of bytes used per pixel, based on the color mode.
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline(stream, pos, prev_pos, line_length, pixel_size)
         case stream.getbyte(pos)
           when ChunkyPNG::FILTER_NONE;    # noop
@@ -423,7 +423,7 @@ module ChunkyPNG
 
       # Decodes a scanline that wasn't encoded using filtering. This is a no-op.
       # @params (see #decode_png_str_scanline)
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline_sub_none(stream, pos, prev_pos, line_length, pixel_size)
         # noop - this method shouldn't get called.
       end
@@ -431,7 +431,7 @@ module ChunkyPNG
       # Decodes a scanline in a pxielstream that was encoded using SUB filtering.
       # This will chnage the pixelstream to have unfiltered values.
       # @params (see #decode_png_str_scanline)
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline_sub(stream, pos, prev_pos, line_length, pixel_size)
         for i in 1..line_length do
           stream.setbyte(pos + i, (stream.getbyte(pos + i) + (i > pixel_size ? stream.getbyte(pos + i - pixel_size) : 0)) & 0xff)
@@ -441,7 +441,7 @@ module ChunkyPNG
       # Decodes a scanline in a pxielstream that was encoded using UP filtering.
       # This will chnage the pixelstream to have unfiltered values.
       # @params (see #decode_png_str_scanline)
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline_up(stream, pos, prev_pos, line_length, pixel_size)
         for i in 1..line_length do
           up = prev_pos ? stream.getbyte(prev_pos + i) : 0
@@ -452,7 +452,7 @@ module ChunkyPNG
       # Decodes a scanline in a pxielstream that was encoded using AVERAGE filtering.
       # This will chnage the pixelstream to have unfiltered values.
       # @params (see #decode_png_str_scanline)
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline_average(stream, pos, prev_pos, line_length, pixel_size)
         for i in 1..line_length do
           a = (i > pixel_size) ? stream.getbyte(pos + i - pixel_size) : 0
@@ -464,7 +464,7 @@ module ChunkyPNG
       # Decodes a scanline in a pxielstream that was encoded using PAETH filtering.
       # This will chnage the pixelstream to have unfiltered values.
       # @params (see #decode_png_str_scanline)
-      # @return [nil]
+      # @return [void]
       def decode_png_str_scanline_paeth(stream, pos, prev_pos, line_length, pixel_size)
         for i in 1..line_length do
           cur_pos = pos + i

data/lib/chunky_png/canvas/png_encoding.rb

@@ -30,6 +30,7 @@ module ChunkyPNG
       # Writes the canvas to an IO stream, encoded as a PNG image.
       # @param [IO] io The output stream to write to.
       # @param constraints (see ChunkyPNG::Canvas::PNGEncoding#to_datastream)
+      # @return [void]
       def write(io, constraints = {})
         to_datastream(constraints).write(io)
       end
@@ -37,6 +38,7 @@ module ChunkyPNG
       # Writes the canvas to a file, encoded as a PNG image.
       # @param [String] filname The file to save the PNG image to.
       # @param constraints (see ChunkyPNG::Canvas::PNGEncoding#to_datastream)
+      # @return [void]
       def save(filename, constraints = {})
         File.open(filename, 'wb') { |io| write(io, constraints) }
       end
@@ -379,14 +381,14 @@ module ChunkyPNG
       # @param [Integer] line_width The number of bytes in this scanline, without counting the filtering
       #     method byte.
       # @param [Integer] pixel_size The number of bytes used per pixel.
-      # @return [nil]
+      # @return [void]
       def encode_png_str_scanline_none(stream, pos, prev_pos, line_width, pixel_size)
         # noop - this method shouldn't get called at all.
       end
 
       # Encodes a scanline of a pixelstream using SUB filtering. This will modify the stream.
       # @param (see #encode_png_str_scanline_none)
-      # @return [nil]
+      # @return [void]
       def encode_png_str_scanline_sub(stream, pos, prev_pos, line_width, pixel_size)
         line_width.downto(1) do |i|
           a = (i > pixel_size) ? stream.getbyte(pos + i - pixel_size) : 0
@@ -397,7 +399,7 @@ module ChunkyPNG
 
       # Encodes a scanline of a pixelstream using UP filtering. This will modify the stream.
       # @param (see #encode_png_str_scanline_none)
-      # @return [nil]
+      # @return [void]
       def encode_png_str_scanline_up(stream, pos, prev_pos, line_width, pixel_size)
         line_width.downto(1) do |i|
           b = prev_pos ? stream.getbyte(prev_pos + i) : 0
@@ -408,7 +410,7 @@ module ChunkyPNG
       
       # Encodes a scanline of a pixelstream using AVERAGE filtering. This will modify the stream.
       # @param (see #encode_png_str_scanline_none)
-      # @return [nil]
+      # @return [void]
       def encode_png_str_scanline_average(stream, pos, prev_pos, line_width, pixel_size)
         line_width.downto(1) do |i|
           a = (i > pixel_size) ? stream.getbyte(pos + i - pixel_size) : 0
@@ -420,7 +422,7 @@ module ChunkyPNG
       
       # Encodes a scanline of a pixelstream using PAETH filtering. This will modify the stream.
       # @param (see #encode_png_str_scanline_none)
-      # @return [nil]
+      # @return [void]
       def encode_png_str_scanline_paeth(stream, pos, prev_pos, line_width, pixel_size)
         line_width.downto(1) do |i|
           a = (i > pixel_size) ? stream.getbyte(pos + i - pixel_size) : 0