chunky_png 0.0.2 → 0.0.3

data/.gitignore

@@ -2,3 +2,5 @@
 spec/resources/testing.png
 /pkg
 /tmp
+/doc
+.yardoc

data/README.rdoc

@@ -1,19 +1,46 @@
 = Chunky PNG
 
 This library can read and write PNG files. It is written in pure Ruby for
-maximum portability. It requires the standard Zlib library.
+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
+Issue tracker:: http://github.com/wvanbergen/chunky_png/issues
+
+== Features
+
+* Decodes almost any image that the PNG standard allows, except for images 
+  that use a different color depth than 8 bits. This includes all standard  
+  color modes and all transparency, interlacing and filtering options.
+* Encodes images supports all color modes (true color, grayscale and indexed)
+  and transparency for all these color modes. The best color mode will be
+  chosen automatically, based on the image's colors.
+* R/W access to the image's pixels.
+* R/W access to all image metadata that is stored in chunks.
+
+== Classes
+
+The main classes used within ChunkyPNG are:
+
+<tt>ChunkyPNG::Image</tt> :: create PNG images from scratch or based on another PNG image.
+<tt>ChunkyPNG::Datastream</tt> :: low-level read and write access to PNG images from or to a file or stream.
+<tt>ChunkyPNG::PixelMatrix</tt> :: represents an images as a matrix of pixels.
+<tt>ChunkyPNG::Pixel</tt> :: represents a single pixel or color value.
 
 == Usage
 
   require 'chunky_png'
   
-  png = ChunkyPNG.load('filename.png')
-  puts png.chunks.inspect
-  puts png.pixel_matrix.inspect
-  
-  # do something with the PNG file
-  
-  File.open('out.png', 'w') { |f| png.write(f) }
+  # Creating an image from scratch
+  png = ChunkyPNG::Image.new(16, 16, ChunkyPNG::Pixel::TRANSPARENT)
+  png[1,1] = ChunkyPNG::Pixel.rgba(255, 255, 255, 128)
+  png[2,1] = ChunkyPNG::Pixel.rgba(255, 255, 255, 128)
+  png.save('filename.png')
+
+  # Modify an image - TODO
+  # Inspecting metadata - TODO
 
 (Note: this is subject to change while work is in progress)
 
@@ -21,4 +48,6 @@ maximum portability. It requires the standard Zlib library.
 
 The library is written by Willem van Bergen for Floorplanner.com, and released
 under the MIT license (see LICENSE). Please contact me for questions or
-remarks. Patches are greatly appreciated! :-)
+remarks. Patches are greatly appreciated! :-)
+
+P.S.: _why is why this library is so chunky.

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.0.2"
-  s.date    = "2010-01-12"
+  s.version = "0.0.3"
+  s.date    = "2010-01-13"
 
   s.summary     = "Pure ruby library for read/write, chunk-level access to PNG files"
   s.description = "Pure ruby library for read/write, chunk-level access to PNG files"
@@ -20,6 +20,6 @@ Gem::Specification.new do |s|
 
   # Do not change the files and test_files fields by hand. This will be done
   # automatically by the gem release script.
-  s.files      = %w(spec/spec_helper.rb spec/resources/gray_10x10_grayscale.png spec/resources/gray_10x10.png .gitignore spec/resources/gray_10x10_truecolor_alpha.png lib/chunky_png/pixel_matrix.rb LICENSE spec/resources/gray_10x10_truecolor.png lib/chunky_png/pixel_matrix/decoding.rb lib/chunky_png/chunk.rb spec/unit/encoding_spec.rb Rakefile README.rdoc spec/resources/gray_10x10_indexed.png spec/integration/image_spec.rb lib/chunky_png/pixel.rb lib/chunky_png/palette.rb lib/chunky_png/datastream.rb chunky_png.gemspec tasks/github-gem.rake spec/unit/decoding_spec.rb spec/resources/gray_10x10_grayscale_alpha.png lib/chunky_png/pixel_matrix/encoding.rb lib/chunky_png/image.rb spec/unit/pixel_spec.rb spec/unit/pixel_matrix_spec.rb lib/chunky_png.rb)
+  s.files      = %w(spec/spec_helper.rb spec/resources/gray_10x10_grayscale.png spec/resources/gray_10x10.png .gitignore spec/resources/gray_10x10_truecolor_alpha.png lib/chunky_png/pixel_matrix.rb LICENSE spec/resources/gray_10x10_truecolor.png lib/chunky_png/pixel_matrix/decoding.rb lib/chunky_png/chunk.rb spec/unit/encoding_spec.rb Rakefile spec/resources/transparent_gray_10x10.png README.rdoc spec/resources/gray_10x10_indexed.png spec/resources/16x16_non_interlaced.png spec/integration/image_spec.rb lib/chunky_png/pixel.rb lib/chunky_png/palette.rb lib/chunky_png/datastream.rb chunky_png.gemspec tasks/github-gem.rake spec/unit/decoding_spec.rb spec/resources/gray_10x10_grayscale_alpha.png spec/resources/16x16_interlaced.png spec/resources/adam7.png lib/chunky_png/pixel_matrix/encoding.rb lib/chunky_png/image.rb spec/unit/pixel_spec.rb spec/unit/pixel_matrix_spec.rb lib/chunky_png.rb)
   s.test_files = %w(spec/unit/encoding_spec.rb spec/integration/image_spec.rb spec/unit/decoding_spec.rb spec/unit/pixel_spec.rb spec/unit/pixel_matrix_spec.rb)
 end

data/lib/chunky_png.rb

@@ -10,9 +10,36 @@ require 'chunky_png/pixel_matrix/decoding'
 require 'chunky_png/pixel_matrix'
 require 'chunky_png/image'
 
+# ChunkyPNG
+#
+# The ChunkyPNG module defines some constants that are used in the
+# PNG specification.
 module ChunkyPNG
   extend self
 
+  ###################################################
+  # PNG international standard defined constants
+  ###################################################
+
+  COLOR_GRAYSCALE       = 0
+  COLOR_TRUECOLOR       = 2
+  COLOR_INDEXED         = 3
+  COLOR_GRAYSCALE_ALPHA = 4
+  COLOR_TRUECOLOR_ALPHA = 6
+
+  FILTERING_DEFAULT     = 0
+
+  COMPRESSION_DEFAULT   = 0
+
+  INTERLACING_NONE      = 0
+  INTERLACING_ADAM7     = 1
+
+  FILTER_NONE           = 0
+  FILTER_SUB            = 1
+  FILTER_UP             = 2
+  FILTER_AVERAGE        = 3
+  FILTER_PAETH          = 4
+
   def load_from_io(io)
     ChunkyPNG::Datastream.read(io)
   end

data/lib/chunky_png/chunk.rb

@@ -45,21 +45,15 @@ module ChunkyPNG
     
     class Header < Base
       
-      COLOR_GRAYSCALE       = 0
-      COLOR_TRUECOLOR       = 2
-      COLOR_INDEXED         = 3
-      COLOR_GRAYSCALE_ALPHA = 4
-      COLOR_TRUECOLOR_ALPHA = 6
-      
       attr_accessor :width, :height, :depth, :color, :compression, :filtering, :interlace
       
       def initialize(attrs = {})
         super('IHDR', attrs)
         @depth       ||= 8
-        @color       ||= COLOR_TRUECOLOR
-        @compression ||= 0
-        @filtering   ||= 0
-        @interlace   ||= 0
+        @color       ||= ChunkyPNG::COLOR_TRUECOLOR
+        @compression ||= ChunkyPNG::COMPRESSION_DEFAULT
+        @filtering   ||= ChunkyPNG::FILTERING_DEFAULT
+        @interlace   ||= ChunkyPNG::INTERLACING_NONE
       end
       
       def self.read(type, content)

data/lib/chunky_png/image.rb

@@ -1,23 +1,43 @@
 module ChunkyPNG
   class Image
     
-    attr_reader :pixels
+    attr_reader :pixel_matrix
     
     def initialize(width, height, background_color = ChunkyPNG::Pixel::TRANSPARENT)
-      @pixels = ChunkyPNG::PixelMatrix.new(width, height, background_color)
+      @pixel_matrix = ChunkyPNG::PixelMatrix.new(width, height, background_color)
+    end
+    
+    def self.from_pixel_matrix(matrix)
+      self.new(matrix.width, matrix.height, matrix.pixels)
     end
     
     def width
-      pixels.width
+      pixel_matrix.width
     end
     
     def height
-      pixels.height
+      pixel_matrix.height
+    end
+    
+    def [](x, y)
+      pixel_matrix[x,y]
+    end
+
+    def []=(x, y, pixel)
+      pixel_matrix[x,y] = pixel
+    end
+    
+    def pixels
+      pixel_matrix.pixels
     end
     
     def write(io, constraints = {})
-      datastream = pixels.to_datastream(constraints)
+      datastream = pixel_matrix.to_datastream(constraints)
       datastream.write(io)
     end
+    
+    def save(filename, constraints = {})
+      File.open(filename, 'w') { |io| write(io, constraints) }
+    end
   end
 end

data/lib/chunky_png/palette.rb

@@ -1,16 +1,36 @@
 module ChunkyPNG
-  
-  ###########################################
-  # PALETTE CLASS
-  ###########################################
-  
+
+  # A palette describes the set of colors that is being used for an image.
+  #
+  # A PNG image can contain an explicit palette which defines the colors of that image,
+  # but can also use an implicit palette, e.g. all truecolor colors or all grayscale colors.
+  #
+  # This palette supports decoding colors from a palette if an explicit palette is provided 
+  # in a PNG datastream, and it supports encoding colors to an explicit matrix.
+  #
+  # @see ChunkyPNG::Pixel
   class Palette < SortedSet
     
-    def initialize(enum)
+    # Builds a new palette given a set (Enumerable instance) of colors.
+    #
+    # @param [Enumerbale<ChunkyPNG::Pixel>] enum The set of colors to include in this palette.
+    #   This Enumerbale can contains duplicates.
+    # @param [Array] decoding_map An array of colors in the exact order at which 
+    #   they appeared in the palette chunk, so that this array can be used for decoding.
+    def initialize(enum, decoding_map = nil)
       super(enum)
-      @decoding_map = enum if enum.kind_of?(Array)
+      @decoding_map = decoding_map if decoding_map
     end
     
+    # Builds a palette instance from a PLTE chunk and optionally a tRNS chunk 
+    # from a PNG datastream.
+    #
+    # This method will cerate a palette that is suitable for decoding an image.
+    #
+    # @param [ChunkyPNG::Chunk::Palette] The palette chunk to load from
+    # @param [ChunkyPNG::Chunk::Transparency, nil] The optional transparency chunk.
+    # @return [ChunkyPNG::Palette] The loaded palette instance. 
+    # @see ChunkyPNG::Palette#can_decode?
     def self.from_chunks(palette_chunk, transparency_chunk = nil)
       return nil if palette_chunk.nil?
       
@@ -31,45 +51,99 @@ module ChunkyPNG
         index += 1
       end
       
-      self.new(decoding_map)
+      self.new(decoding_map, decoding_map)
     end
     
+    # Builds a palette instance from a given pixel matrix.
+    # @param [ChunkyPNG::PixelMatrix] pixel_matrix The pixel matrix to create a palette for.
+    # @return [ChunkyPNG::Palette] The palette instance.
     def self.from_pixel_matrix(pixel_matrix)
       self.new(pixel_matrix.pixels)
     end
     
+    # Builds a palette instance from a given set of pixels.
+    # @param [Enumerable<ChunkyPNG::Pixel>] pixels An enumeration of pixels to create a palette for
+    # @return [ChunkyPNG::Palette] The palette instance.
     def self.from_pixels(pixels)
       self.new(pixels)
     end
     
+    # Checks whether the size of this palette is suitable for indexed storage.
+    # @return [true, false] True if the number of colors in this palette is less than 256.
     def indexable?
       size < 256
     end
     
+    # Check whether this pelette only contains opaque colors.
+    # @return [true, false] True if all colors in this palette are opaque.
+    # @see ChunkyPNG::Pixel#opaque?
     def opaque?
       all? { |pixel| pixel.opaque? }
     end
+    
+    # Check whether this pelette only contains grayscale colors.
+    # @return [true, false] True if all colors in this palette are grayscale teints.
+    # @see ChunkyPNG::Pixel#grayscale??
+    def grayscale?
+      all? { |pixel| pixel.grayscale? }
+    end
 
+    # Checks whether this palette is suitable for decoding an image from a datastream.
+    #
+    # This requires that the positions of the colors in the original palette chunk is known,
+    # which is stored as an array in the +@decoding_map+ instance variable.
+    #
+    # @return [true, false] True if a decoding map was built when this palette was loaded.
     def can_decode?
       !@decoding_map.nil?
     end
     
+    # Checks whether this palette is suitable for encoding an image from to datastream.
+    #
+    # This requires that the position of the color in the future palette chunk is known,
+    # which is stored as a hash in the +@encoding_map+ instance variable.
+    #
+    # @return [true, false] True if a encoding map was built when this palette was loaded.
     def can_encode?
       !@encoding_map.nil?
     end
     
+    # Returns a color, given the position in the original palette chunk.
+    # @param [Fixnum] index The 0-based position of the color in the palette.
+    # @return [ChunkyPNG::Pixel] The color that is stored in the palette under the given index
+    # @see ChunkyPNG::Palette#can_decode?
     def [](index)
       @decoding_map[index]
     end
     
+    # Returns the position of a color in the palette
+    # @param [ChunkyPNG::Pixel] color The color for which to look up the index.
+    # @return [Fixnum] The 0-based position of the color in the palette.
+    # @see ChunkyPNG::Palette#can_encode?
     def index(color)
       @encoding_map[color]
     end
     
+    # Creates a tRNS chunk that corresponds with this palette to store the
+    # alpha channel of all colors.
+    #
+    # Note that this chunk can be left out of every color in the palette is 
+    # opaque, and the image is encoded using indexed colors.
+    #
+    # @return [ChunkyPNG::Chunk::Transparency] The tRNS chunk.
     def to_trns_chunk
       ChunkyPNG::Chunk::Transparency.new('tRNS', map(&:a).pack('C*'))
     end
     
+    # Creates a PLTE chunk that corresponds with this palette to store the
+    # r, g and b channels of all colors.
+    #
+    # Note that a PLTE chunk should only be included if the image is 
+    # encoded using index colors. After this chunk has been built, the
+    # palette becomes suitable for encoding an image.
+    #
+    # @return [ChunkyPNG::Chunk::Palette] The PLTE chunk.
+    # @see ChunkyPNG::Palette#can_encode?
     def to_plte_chunk
       @encoding_map = {}
       colors     = []
@@ -82,13 +156,22 @@ module ChunkyPNG
       ChunkyPNG::Chunk::Palette.new('PLTE', colors.pack('C*'))
     end
     
+    # Determines the most suitable colormode for this palette.
+    # @return [Fixnum] The colormode which would create the smalles possible
+    #    file for images that use this exact palette.
     def best_colormode
-      if indexable?
-        ChunkyPNG::Chunk::Header::COLOR_INDEXED
+      if grayscale?
+        if opaque?
+          ChunkyPNG::COLOR_GRAYSCALE
+        else
+          ChunkyPNG::COLOR_GRAYSCALE_ALPHA
+        end
+      elsif indexable?
+        ChunkyPNG::COLOR_INDEXED
       elsif opaque?
-        ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR
+        ChunkyPNG::COLOR_TRUECOLOR
       else
-        ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR_ALPHA
+        ChunkyPNG::COLOR_TRUECOLOR_ALPHA
       end
     end
   end

data/lib/chunky_png/pixel.rb

@@ -48,16 +48,28 @@ module ChunkyPNG
       a == 0x000000ff
     end
     
+    def grayscale?
+      r == g && r == b
+    end
+    
     def inspect
       '#%08x' % @value
     end
     
+    def hash
+      @value.hash
+    end
+    
     def eql?(other)
       other.kind_of?(self.class) && other.value == self.value
     end
     
     alias :== :eql?
     
+    def <=>(other)
+      other.value <=> self.value
+    end
+    
     def to_truecolor_alpha_bytes
       [r,g,b,a]
     end
@@ -89,11 +101,11 @@ module ChunkyPNG
     
     def self.bytesize(color_mode)
       case color_mode
-        when ChunkyPNG::Chunk::Header::COLOR_INDEXED         then 1
-        when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR       then 3
-        when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR_ALPHA then 4
-        when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE       then 1
-        when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE_ALPHA then 2
+        when ChunkyPNG::COLOR_INDEXED         then 1
+        when ChunkyPNG::COLOR_TRUECOLOR       then 3
+        when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then 4
+        when ChunkyPNG::COLOR_GRAYSCALE       then 1
+        when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then 2
         else raise "Don't know the bytesize of pixels in this colormode: #{color_mode}!"
       end
     end

data/lib/chunky_png/pixel_matrix.rb

@@ -1,19 +1,38 @@
 module ChunkyPNG
   
+  # The ChunkPNG::PixelMatrix class represents a matrix of pixels of which an i
+  # mage consists. This class supports loading a PixelMatrix from a PNG datastream,
+  # and creating a PNG datastream bse don this matrix.
+  #
+  # This class offers per-pixel access to the matrix by using x,y coordinates. It uses
+  # a palette (see {ChunkyPNG::Palette}) to keep track of the different colors used in
+  # this matrix.
+  #
+  # @see ChunkyPNG::Datastream
   class PixelMatrix
     
     include Encoding
     extend  Decoding
     
-    FILTER_NONE    = 0
-    FILTER_SUB     = 1
-    FILTER_UP      = 2
-    FILTER_AVERAGE = 3
-    FILTER_PAETH   = 4
-    
-    attr_reader :width, :height, :pixels
+    # @return [Integer] The number of columns in this pixel matrix
+    attr_reader :width
+
+    # @return [Integer] The number of rows in this pixel matrix
+    attr_reader :height
 
+    # @return [Array<ChunkyPNG::Pixel>] The list of pixels in this matrix.
+    #     This array always should have +width * height+ elements.
+    attr_reader :pixels
 
+    # Initializes a new PixelMatrix instance
+    # @param [Integer] width The width in pixels of this matrix
+    # @param [Integer] width The height in pixels of this matrix
+    # @param [ChunkyPNG::Pixel, Array<ChunkyPNG::Pixel>] initial The initial value of te pixels:
+    #
+    #    * If a color is passed to this parameter, this color will be used as background color. 
+    #
+    #    * If an array of pixels is provided, these pixels will be used as initial value. Note 
+    #      that the amount of pixels in this array should equal +width * height+.
     def initialize(width, height, initial = ChunkyPNG::Pixel::TRANSPARENT)
       
       @width, @height = width, height
@@ -27,14 +46,24 @@ module ChunkyPNG
       end
     end
     
+    # Replaces a single pixel in this matrix.
+    # @param [Integer] x The x-coordinate of the pixel (column)
+    # @param [Integer] y The y-coordinate of the pixel (row)
+    # @param [ChunkyPNG::Pixel] pixel The new pixel for the provided coordinates.
     def []=(x, y, pixel)
       @pixels[y * width + x] = pixel
     end
     
+    # Returns a single pixel from this matrix.
+    # @param [Integer] x The x-coordinate of the pixel (column)
+    # @param [Integer] y The y-coordinate of the pixel (row)
+    # @return [ChunkyPNG::Pixel] The current pixel at the provided coordinates.
     def [](x, y)
       @pixels[y * width + x]
     end
     
+    # Passes to this matrix of pixels line by line.
+    # @yield [Array<ChunkyPNG::Pixel>] An line of pixels
     def each_scanline(&block)
       height.times do |i|
         scanline = @pixels[width * i, width]
@@ -42,18 +71,15 @@ module ChunkyPNG
       end
     end
     
+    # Returns the palette used for this pixel matrix.
+    # @return [ChunkyPNG::Palette] A pallete which contains all the colors that are 
+    #    being used for this image.
     def palette
       ChunkyPNG::Palette.from_pixels(@pixels)
     end
     
-    def opaque?
-      pixels.all? { |pixel| pixel.opaque? }
-    end
-    
-    def indexable?
-      palette.indexable?
-    end
-    
+    # Converts this PixelMatrix to a datastream, so that it can be saved as a PNG image.
+    # @param [Hash] constraints The constraints to use when encoding the matrix.
     def to_datastream(constraints = {})
       data = encode(constraints)
       ds = Datastream.new
@@ -65,6 +91,10 @@ module ChunkyPNG
       return ds
     end
     
+    # Equality check to compare this pixel matrix with other matrices.
+    # @param other The object to compare this Matrix to.
+    # @return [true, false] True if the size and pixel values of the other matrix
+    #    are exactly the same as this matrix size and pixel values.
     def eql?(other)
       other.kind_of?(self.class) && other.pixels == self.pixels &&
             other.width == self.width && other.height == self.height

data/lib/chunky_png/pixel_matrix/decoding.rb

@@ -3,56 +3,116 @@ module ChunkyPNG
     module Decoding
       
       def decode(ds)
+        raise "Only 8-bit color depth is currently supported by ChunkyPNG!" unless ds.header_chunk.depth == 8
+        
         stream     = Zlib::Inflate.inflate(ds.data_chunks.map(&:content).join(''))
         width      = ds.header_chunk.width
         height     = ds.header_chunk.height
         color_mode = ds.header_chunk.color
+        interlace  = ds.header_chunk.interlace
         palette    = ChunkyPNG::Palette.from_chunks(ds.palette_chunk, ds.transparency_chunk)
-        decode_pixelstream(stream, width, height, color_mode, palette)
+        decode_pixelstream(stream, width, height, color_mode, palette, interlace)
       end
       
-      def decode_pixelstream(stream, width, height, color_mode = ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR, palette = nil)
-
-        pixel_size = Pixel.bytesize(color_mode)
-        raise "Invalid stream length!" unless stream.length == width * height * pixel_size + height
+      def decode_pixelstream(stream, width, height, color_mode = ChunkyPNG::COLOR_TRUECOLOR, palette = nil, interlace = ChunkyPNG::INTERLACING_NONE)
         raise "This palette is not suitable for decoding!" if palette && !palette.can_decode?
-
+        
+        pixel_size    = Pixel.bytesize(color_mode)
         pixel_decoder = case color_mode
-          when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR       then lambda { |bytes| ChunkyPNG::Pixel.rgb(*bytes) }
-          when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR_ALPHA then lambda { |bytes| ChunkyPNG::Pixel.rgba(*bytes) }
-          when ChunkyPNG::Chunk::Header::COLOR_INDEXED         then lambda { |bytes| palette[bytes.first] }
-          when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE       then lambda { |bytes| ChunkyPNG::Pixel.grayscale(*bytes) }
-          when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE_ALPHA then lambda { |bytes| ChunkyPNG::Pixel.grayscale(*bytes) }
+          when ChunkyPNG::COLOR_TRUECOLOR       then lambda { |bytes| ChunkyPNG::Pixel.rgb(*bytes) }
+          when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then lambda { |bytes| ChunkyPNG::Pixel.rgba(*bytes) }
+          when ChunkyPNG::COLOR_INDEXED         then lambda { |bytes| palette[bytes.first] }
+          when ChunkyPNG::COLOR_GRAYSCALE       then lambda { |bytes| ChunkyPNG::Pixel.grayscale(*bytes) }
+          when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then lambda { |bytes| ChunkyPNG::Pixel.grayscale(*bytes) }
           else raise "No suitable pixel decoder found for color mode #{color_mode}!"
         end
         
+        pixels = case interlace
+          when ChunkyPNG::INTERLACING_NONE  then decode_interlacing_none(stream, width, height, pixel_size, pixel_decoder)
+          when ChunkyPNG::INTERLACING_ADAM7 then decode_interlacing_adam7(stream, width, height, pixel_size, pixel_decoder)
+          else raise "Don't know how the handle interlacing method #{interlace}!"
+        end
+
+        return ChunkyPNG::PixelMatrix.new(width, height, pixels)
+      end
+      
+      protected
+      
+      def decode_image_pass(stream, width, height, pixel_size, pixel_decoder, start_pos = 0)
         pixels = []
         decoded_bytes = Array.new(width * pixel_size, 0)
         height.times do |line_no|
           
-          # get bytes of scanline
-          position       = line_no * (width * pixel_size + 1)
-          line_length    = width * pixel_size
-          bytes          = stream.unpack("@#{position}CC#{line_length}")
-          filter         = bytes.shift
-          decoded_bytes  = decode_scanline(filter, bytes, decoded_bytes, pixel_size)
-          
-          # decode bytes into colors
-          decoded_bytes.each_slice(pixel_size) { |bytes| pixels << pixel_decoder.call(bytes) }
-        end
+          if width > 0
+            
+            # get bytes of scanline
+            position       = start_pos + line_no * (width * pixel_size + 1)
+            line_length    = width * pixel_size
+            bytes          = stream.unpack("@#{position}CC#{line_length}")
+            filter         = bytes.shift
+            decoded_bytes  = decode_scanline(filter, bytes, decoded_bytes, pixel_size)
         
-        return ChunkyPNG::PixelMatrix.new(width, height, pixels)
+            # decode bytes into colors
+            decoded_bytes.each_slice(pixel_size) { |bytes| pixels << pixel_decoder.call(bytes) }
+          end
+        end
+        pixels
       end
       
-      protected
+      def decode_interlacing_none(stream, width, height, pixel_size, pixel_decoder)
+        raise "Invalid stream length!" unless stream.length == width * height * pixel_size + height
+        decode_image_pass(stream, width, height, pixel_size, pixel_decoder)
+      end
       
+      def decode_interlacing_adam7(stream, width, height, pixel_size, pixel_decoder)
+        start_pos = 0
+        sub_matrices = adam7_pass_sizes(width, height).map do |(pass_width, pass_height)|
+          pixels = decode_image_pass(stream, pass_width, pass_height, pixel_size, pixel_decoder, start_pos)
+          start_pos += (pass_width * pass_height * pixel_size) + pass_height
+          [pass_width, pass_height, pixels]
+        end
+
+        pixels = Array.new(width * height, ChunkyPNG::Pixel::TRANSPARENT)
+        0.upto(6) { |pass| adam7_merge_pass(pass, width, height, pixels, *sub_matrices[pass]) }
+        pixels
+      end
+
+      def adam7_multiplier_offset(pass)
+        {
+          :x_multiplier => 8 >> (pass >> 1),
+          :x_offset     => (pass & 1 == 0) ? 0 : 8 >> ((pass + 1) >> 1),
+          :y_multiplier => pass == 0 ? 8 : 8 >> ((pass - 1) >> 1),
+          :y_offset     => (pass == 0 || pass & 1 == 1) ? 0 : 8 >> (pass >> 1)
+        }
+      end
+      
+      def adam7_merge_pass(pass, width, height, pixels, sm_width, sm_height, sm_pixels)
+        m_o = adam7_multiplier_offset(pass)
+        0.upto(sm_height - 1) do |y|
+          0.upto(sm_width - 1) do |x|
+            new_x = x * m_o[:x_multiplier] + m_o[:x_offset]
+            new_y = y * m_o[:y_multiplier] + m_o[:y_offset]
+            pixels[width * new_y + new_x] = sm_pixels[sm_width * y + x]
+          end
+        end
+        pixels
+      end
+      
+      def adam7_pass_sizes(width, height)
+        (0...7).map do |pass|
+          m_o = adam7_multiplier_offset(pass)
+          [ ((width  - m_o[:x_offset] ) / m_o[:x_multiplier].to_f).ceil,
+            ((height - m_o[:y_offset] ) / m_o[:y_multiplier].to_f).ceil,]
+        end
+      end
+
       def decode_scanline(filter, bytes, previous_bytes, pixelsize = 3)
         case filter
-        when FILTER_NONE    then decode_scanline_none( bytes, previous_bytes, pixelsize)
-        when FILTER_SUB     then decode_scanline_sub(  bytes, previous_bytes, pixelsize)
-        when FILTER_UP      then decode_scanline_up(   bytes, previous_bytes, pixelsize)
-        when FILTER_AVERAGE then raise "Average filter are not yet supported!"
-        when FILTER_PAETH   then raise "Paeth filter are not yet supported!"
+        when ChunkyPNG::FILTER_NONE    then decode_scanline_none(    bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_SUB     then decode_scanline_sub(     bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_UP      then decode_scanline_up(      bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_AVERAGE then decode_scanline_average( bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_PAETH   then decode_scanline_paeth(   bytes, previous_bytes, pixelsize)
         else raise "Unknown filter type"
         end
       end
@@ -70,6 +130,30 @@ module ChunkyPNG
         bytes.each_with_index { |b, i| bytes[i] = (b + previous_bytes[i]) % 256 }
         bytes
       end
+
+      def decode_scanline_average(bytes, previous_bytes, pixelsize = 3)
+        bytes.each_with_index do |byte, i|
+          a = (i >= pixelsize) ? bytes[i - pixelsize] : 0
+          b = previous_bytes[i]
+          bytes[i] = (byte + (a + b / 2).floor) % 256
+        end
+        bytes
+      end
+
+      def decode_scanline_paeth(bytes, previous_bytes, pixelsize = 3)
+        bytes.each_with_index do |byte, i|
+          a = (i >= pixelsize) ? bytes[i - pixelsize] : 0
+          b = previous_bytes[i]
+          c = (i >= pixelsize) ? previous_bytes[i - pixelsize] : 0
+          p = a + b - c
+          pa = (p - a).abs
+          pb = (p - b).abs
+          pc = (p - c).abs
+          pr = (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c)
+          bytes[i] = (byte + pr) % 256
+        end
+        bytes
+      end
     end
   end
 end

data/lib/chunky_png/pixel_matrix/encoding.rb

@@ -7,7 +7,7 @@ module ChunkyPNG
         result = {}
         result[:header] = { :width => width, :height => height, :color => encoding[:color_mode] }
 
-        if encoding[:color_mode] == ChunkyPNG::Chunk::Header::COLOR_INDEXED
+        if encoding[:color_mode] == ChunkyPNG::COLOR_INDEXED
           result[:palette_chunk]      = encoding[:palette].to_plte_chunk
           result[:transparency_chunk] = encoding[:palette].to_trns_chunk unless encoding[:palette].opaque?
         end
@@ -25,58 +25,64 @@ module ChunkyPNG
         return encoding
       end
       
-      def encode_pixelstream(color_mode = ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR, palette = nil)
+      def encode_pixelstream(color_mode = ChunkyPNG::COLOR_TRUECOLOR, palette = nil)
 
         pixel_encoder = case color_mode
-          when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR       then lambda { |pixel| pixel.to_truecolor_bytes }
-          when ChunkyPNG::Chunk::Header::COLOR_TRUECOLOR_ALPHA then lambda { |pixel| pixel.to_truecolor_alpha_bytes }
-          when ChunkyPNG::Chunk::Header::COLOR_INDEXED         then lambda { |pixel| pixel.to_indexed_bytes(palette) }
-          when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE       then lambda { |pixel| pixel.to_grayscale_bytes }
-          when ChunkyPNG::Chunk::Header::COLOR_GRAYSCALE_ALPHA then lambda { |pixel| pixel.to_grayscale_alpha_bytes }
+          when ChunkyPNG::COLOR_TRUECOLOR       then lambda { |pixel| pixel.to_truecolor_bytes }
+          when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then lambda { |pixel| pixel.to_truecolor_alpha_bytes }
+          when ChunkyPNG::COLOR_INDEXED         then lambda { |pixel| pixel.to_indexed_bytes(palette) }
+          when ChunkyPNG::COLOR_GRAYSCALE       then lambda { |pixel| pixel.to_grayscale_bytes }
+          when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then lambda { |pixel| pixel.to_grayscale_alpha_bytes }
           else raise "Cannot encode pixels for this mode: #{color_mode}!"
         end
         
-        raise "This palette is not suitable for encoding!" if palette && !palette.can_encode?
+        if color_mode == ChunkyPNG::COLOR_INDEXED && !palette.can_encode?
+          raise "This palette is not suitable for encoding!"
+        end
 
-        pixelsize = Pixel.bytesize(color_mode)
+        pixel_size = Pixel.bytesize(color_mode)
 
         stream   = ""
-        previous = nil
+        previous_bytes = Array.new(pixel_size * width, 0)
         each_scanline do |line|
-          bytes  = line.map(&pixel_encoder).flatten
-          if previous
-            stream << encode_scanline_up(bytes, previous, pixelsize).pack('C*')
-          else
-            stream << encode_scanline_sub(bytes, previous, pixelsize).pack('C*')
-          end
-          previous = bytes
+          unencoded_bytes = line.map(&pixel_encoder).flatten
+          stream << encode_scanline_up(unencoded_bytes, previous_bytes, pixel_size).pack('C*')
+          previous_bytes  = unencoded_bytes
         end
         return stream
-      end      
+      end
 
       def encode_scanline(filter, bytes, previous_bytes = nil, pixelsize = 3)
         case filter
-        when FILTER_NONE    then encode_scanline_none( bytes, previous_bytes, pixelsize)
-        when FILTER_SUB     then encode_scanline_sub(  bytes, previous_bytes, pixelsize)
-        when FILTER_UP      then encode_scanline_up(   bytes, previous_bytes, pixelsize)
-        when FILTER_AVERAGE then raise "Average filter are not yet supported!"
-        when FILTER_PAETH   then raise "Paeth filter are not yet supported!"
+        when ChunkyPNG::FILTER_NONE    then encode_scanline_none( bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_SUB     then encode_scanline_sub(  bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_UP      then encode_scanline_up(   bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_AVERAGE then raise "Average filter are not yet supported!"
+        when ChunkyPNG::FILTER_PAETH   then raise "Paeth filter are not yet supported!"
         else raise "Unknown filter type"
         end
       end
 
-      def encode_scanline_none(bytes, previous_bytes = nil, pixelsize = 3)
-        [FILTER_NONE] + bytes
+      def encode_scanline_none(original_bytes, previous_bytes = nil, pixelsize = 3)
+        [ChunkyPNG::FILTER_NONE] + original_bytes
       end
 
-      def encode_scanline_sub(bytes, previous_bytes = nil, pixelsize = 3)
-        encoded = (pixelsize...bytes.length).map { |n| (bytes[n-pixelsize] - bytes[n]) % 256 }
-        [FILTER_SUB] + bytes[0...pixelsize] + encoded
+      def encode_scanline_sub(original_bytes, previous_bytes = nil, pixelsize = 3)
+        encoded_bytes = []
+        original_bytes.length.times do |index|
+          a = (index >= pixelsize) ? original_bytes[index - pixelsize] : 0
+          encoded_bytes[index] = (original_bytes[index] - a) % 256
+        end
+        [ChunkyPNG::FILTER_SUB] + encoded_bytes
       end
 
-      def encode_scanline_up(bytes, previous_bytes, pixelsize = 3)
-        encoded = (0...bytes.length).map { |n| previous_bytes[n] - bytes[n] % 256 }
-        [FILTER_UP] + encoded
+      def encode_scanline_up(original_bytes, previous_bytes, pixelsize = 3)
+        encoded_bytes = []
+        original_bytes.length.times do |index|
+          b = previous_bytes[index]
+          encoded_bytes[index] = (original_bytes[index] - b) % 256
+        end
+        [ChunkyPNG::FILTER_UP] + encoded_bytes
       end
     end
   end

data/spec/unit/decoding_spec.rb

@@ -7,23 +7,23 @@ describe ChunkyPNG::PixelMatrix::Decoding do
     
     it "should decode a line without filtering as is" do
       bytes = [255, 255, 255, 255, 255, 255, 255, 255, 255]
-      decode_scanline(ChunkyPNG::PixelMatrix::FILTER_NONE, bytes, nil).should == bytes
+      decode_scanline(ChunkyPNG::FILTER_NONE, bytes, nil).should == bytes
     end
     
     it "should decode a line with sub filtering correctly" do
       # all white pixels
       bytes = [255, 255, 255, 0, 0, 0, 0, 0, 0]
-      decoded_bytes = decode_scanline(ChunkyPNG::PixelMatrix::FILTER_SUB, bytes, nil)
+      decoded_bytes = decode_scanline(ChunkyPNG::FILTER_SUB, bytes, nil)
       decoded_bytes.should == [255, 255, 255, 255, 255, 255, 255, 255, 255]
       
       # all black pixels
       bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0]
-      decoded_bytes = decode_scanline(ChunkyPNG::PixelMatrix::FILTER_SUB, bytes, nil)
+      decoded_bytes = decode_scanline(ChunkyPNG::FILTER_SUB, bytes, nil)
       decoded_bytes.should == [0, 0, 0, 0, 0, 0, 0, 0, 0]
       
       # various colors
       bytes = [255, 0, 45, 0, 255, 0, 112, 200, 178]
-      decoded_bytes = decode_scanline(ChunkyPNG::PixelMatrix::FILTER_SUB, bytes, nil)
+      decoded_bytes = decode_scanline(ChunkyPNG::FILTER_SUB, bytes, nil)
       decoded_bytes.should == [255, 0, 45, 255, 255, 45, 111, 199, 223]
     end
     
@@ -31,14 +31,53 @@ describe ChunkyPNG::PixelMatrix::Decoding do
       # previous line is all black
       previous_bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0]
       bytes          = [255, 255, 255, 127, 127, 127, 0, 0, 0]
-      decoded_bytes  = decode_scanline(ChunkyPNG::PixelMatrix::FILTER_UP, bytes, previous_bytes)
+      decoded_bytes  = decode_scanline(ChunkyPNG::FILTER_UP, bytes, previous_bytes)
       decoded_bytes.should == [255, 255, 255, 127, 127, 127, 0, 0, 0]
       
       # previous line has various pixels
       previous_bytes = [255, 255, 255, 127, 127, 127, 0, 0, 0]
       bytes          = [0, 127, 255, 0, 127, 255, 0, 127, 255]
-      decoded_bytes  = decode_scanline(ChunkyPNG::PixelMatrix::FILTER_UP, bytes, previous_bytes)
+      decoded_bytes  = decode_scanline(ChunkyPNG::FILTER_UP, bytes, previous_bytes)
       decoded_bytes.should == [255, 126, 254, 127, 254, 126, 0, 127, 255]
     end
   end
+  
+  describe '#adam7_pass_sizes' do
+    it "should get the pass sizes for a 8x8 image correctly" do
+      adam7_pass_sizes(8, 8).should == [
+          [1, 1], [1, 1], [2, 1], [2, 2], [4, 2], [4, 4], [8, 4]
+        ]
+    end
+
+    it "should get the pass sizes for a 12x12 image correctly" do
+      adam7_pass_sizes(12, 12).should == [
+          [2, 2], [1, 2], [3, 1], [3, 3], [6, 3], [6, 6], [12, 6]
+        ]
+    end
+
+    it "should get the pass sizes for a 33x47 image correctly" do
+      adam7_pass_sizes(33, 47).should == [
+          [5, 6], [4, 6], [9, 6], [8, 12], [17, 12], [16, 24], [33, 23]
+        ]
+    end
+
+    it "should get the pass sizes for a 1x1 image correctly" do
+      adam7_pass_sizes(1, 1).should == [
+          [1, 1], [0, 1], [1, 0], [0, 1], [1, 0], [0, 1], [1, 0]
+        ]
+    end
+
+    it "should get the pass sizes for a 0x0 image correctly" do
+      adam7_pass_sizes(0, 0).should == [
+          [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0]
+        ]
+    end
+
+    it "should always maintain the same amount of pixels in total" do
+      [[8, 8], [12, 12], [33, 47], [1, 1], [0, 0]].each do |(width, height)|
+        pass_sizes = adam7_pass_sizes(width, height)
+        pass_sizes.inject(0) { |sum, (w, h)| sum + (w*h) }.should == width * height
+      end
+    end
+  end
 end

data/spec/unit/encoding_spec.rb

@@ -7,20 +7,20 @@ describe ChunkyPNG::PixelMatrix::Encoding do
     
     it "should encode a scanline without filtering correctly" do
       bytes = [0, 0, 0, 1, 1, 1, 2, 2, 2]
-      encoded_bytes = encode_scanline(ChunkyPNG::PixelMatrix::FILTER_NONE, bytes, nil)
+      encoded_bytes = encode_scanline(ChunkyPNG::FILTER_NONE, bytes, nil)
       encoded_bytes.should == [0, 0, 0, 0, 1, 1, 1, 2, 2, 2]
     end
     
     it "should encode a scanline with sub filtering correctly" do
       bytes = [255, 255, 255, 255, 255, 255, 255, 255, 255]
-      encoded_bytes = encode_scanline(ChunkyPNG::PixelMatrix::FILTER_SUB, bytes, nil)
+      encoded_bytes = encode_scanline(ChunkyPNG::FILTER_SUB, bytes, nil)
       encoded_bytes.should == [1, 255, 255, 255, 0, 0, 0, 0, 0, 0]
     end
     
     it "should encode a scanline with up filtering correctly" do
       bytes          = [255, 255, 255, 255, 255, 255, 255, 255, 255]
       previous_bytes = [255, 255, 255, 255, 255, 255, 255, 255, 255]
-      encoded_bytes  = encode_scanline(ChunkyPNG::PixelMatrix::FILTER_UP, bytes, previous_bytes)
+      encoded_bytes  = encode_scanline(ChunkyPNG::FILTER_UP, bytes, previous_bytes)
       encoded_bytes.should == [2, 0, 0, 0, 0, 0, 0, 0, 0, 0]
     end
   end

data/spec/unit/pixel_matrix_spec.rb

@@ -4,16 +4,25 @@ describe ChunkyPNG::PixelMatrix do
   
   describe '.decode' do
     
-    before(:each) do
-      @reference = ChunkyPNG::PixelMatrix.new(10, 10, ChunkyPNG::Pixel.rgb(100, 100, 100))
-    end
-    
     [:indexed, :grayscale, :grayscale_alpha, :truecolor, :truecolor_alpha].each do |color_mode|
       it "should decode an image with color mode #{color_mode} correctly" do
+        reference = ChunkyPNG::PixelMatrix.new(10, 10, ChunkyPNG::Pixel.rgb(100, 100, 100))
         ds = ChunkyPNG.load(resource_file("gray_10x10_#{color_mode}.png"))
-        ds.pixel_matrix.should == @reference
+        ds.pixel_matrix.should == reference
       end
     end
+    
+    it "should decode a transparent image correctly" do
+      reference = ChunkyPNG::PixelMatrix.new(10, 10, ChunkyPNG::Pixel.rgba(100, 100, 100, 128))
+      ds = ChunkyPNG.load(resource_file("transparent_gray_10x10.png"))
+        ds.pixel_matrix.should == reference
+    end
+    
+    it "should decode an interlaced image correctly" do
+      ds_i  = ChunkyPNG.load(resource_file("16x16_interlaced.png"))
+      ds_ni = ChunkyPNG.load(resource_file("16x16_non_interlaced.png"))
+      ds_i.pixel_matrix.should == ds_ni.pixel_matrix
+    end
   end
   
   describe '.encode' do

data/tasks/github-gem.rake

@@ -124,7 +124,7 @@ module GithubGem
         desc "Perform all checks that would occur before a release"
         task(:release_checks => checks)
 
-        release_tasks = [:release_checks, :set_version, :build, :github_release]
+        release_tasks = [:release_checks, :set_version, :build, :github_release, :gemcutter_release]
         release_tasks << [:rubyforge_release] if gemspec.rubyforge_project
 
         desc "Release a new verison of the gem"
@@ -132,6 +132,7 @@ module GithubGem
 
         task(:check_rubyforge)   { check_rubyforge_task }
         task(:rubyforge_release) { rubyforge_release_task }
+        task(:gemcutter_release) { gemcutter_release_task }
         task(:github_release => [:commit_modified_files, :tag_version]) { github_release_task }
         task(:tag_version) { tag_version_task }
         task(:commit_modified_files) { commit_modified_files_task }
@@ -228,6 +229,10 @@ module GithubGem
     def rubyforge_release_task
       sh 'rubyforge', 'add_release', gemspec.rubyforge_project, gemspec.name, gemspec.version.to_s, "pkg/#{gemspec.name}-#{gemspec.version}.gem"
     end
+    
+    def gemcutter_release_task
+      sh "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+    end
 
     # Gem release task.
     # All work is done by the task's dependencies, so just display a release completed message.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: chunky_png
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Willem van Bergen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-12 00:00:00 +01:00
+date: 2010-01-13 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,8 +44,10 @@ files:
 - lib/chunky_png/chunk.rb
 - spec/unit/encoding_spec.rb
 - Rakefile
+- spec/resources/transparent_gray_10x10.png
 - README.rdoc
 - spec/resources/gray_10x10_indexed.png
+- spec/resources/16x16_non_interlaced.png
 - spec/integration/image_spec.rb
 - lib/chunky_png/pixel.rb
 - lib/chunky_png/palette.rb
@@ -54,6 +56,8 @@ files:
 - tasks/github-gem.rake
 - spec/unit/decoding_spec.rb
 - spec/resources/gray_10x10_grayscale_alpha.png
+- spec/resources/16x16_interlaced.png
+- spec/resources/adam7.png
 - lib/chunky_png/pixel_matrix/encoding.rb
 - lib/chunky_png/image.rb
 - spec/unit/pixel_spec.rb