bench9000 0.1

data/vendor/chunky_png/lib/chunky_png/canvas/operations.rb

@@ -0,0 +1,395 @@
+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
+      # Converts the canvas to grayscale.
+      #
+      # This method will modify the canvas. The obtain a new canvas and leave
+      # the current instance intact, use {#grayscale} instead.
+      #
+      # @return [ChunkyPNG::Canvas] Returns itself, converted to grayscale.
+      # @see {#grayscale}
+      # @see {ChunkyPNG::Color#to_grayscale}
+      def grayscale!
+        pixels.map! { |pixel| ChunkyPNG::Color.to_grayscale(pixel) }
+        self
+      end
+
+      # Converts the canvas to grayscale, returning a new canvas.
+      #
+      # This method will not modify the canvas. To modift the current canvas,
+      # use {#grayscale!} instead.
+      #
+      # @return [ChunkyPNG::Canvas] A copy of the canvas, converted to
+      #   grayscale.
+      # @see {#grayscale!}
+      # @see {ChunkyPNG::Color#to_grayscale}
+      def grayscale
+        dup.grayscale!
+      end
+
+      # Composes another image onto this image using alpha blending. This will
+      # modify the current canvas.
+      #
+      # 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 foreground on.
+      # @param [Integer] offset_y The y-offset to apply the new foreground 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 canvas.
+      # @see #replace!
+      # @see #compose
+      def compose!(other, offset_x = 0, offset_y = 0)
+        check_size_constraints!(other, offset_x, offset_y)
+
+        for y in 0...other.height do
+          for x in 0...other.width do
+            set_pixel(x + offset_x,
+                      y + offset_y,
+                      ChunkyPNG::Color.compose(other.get_pixel(x, y),
+                                               get_pixel(x + offset_x,
+                                                         y + offset_y)))
+          end
+        end
+        self
+      end
+
+      # Composes another image onto this image using alpha blending. This will
+      # return a new canvas and leave the original intact.
+      #
+      # If you simply want to replace pixels or when the other image does not
+      # have transparency, it is faster to use {#replace}.
+      #
+      # @param (see #compose!)
+      # @return [ChunkyPNG::Canvas] Returns the new canvas, composed of the
+      #   other 2.
+      # @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
+      #   this one, given the offset and size of the other canvas.
+      #
+      # @note API changed since 1.0 - This method now no longer is in place,
+      #   but returns a new canvas and leaves the original intact. Use
+      #   {#compose!} if you want to compose on the canvas in place.
+      # @see #replace
+      def compose(other, offset_x = 0, offset_y = 0)
+        dup.compose!(other, offset_x, offset_y)
+      end
+
+      # Replaces pixels on this image by pixels from another pixels, on a given
+      # offset. This method will modify the current canvas.
+      #
+      # 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!}.
+      #
+      # @param [ChunkyPNG::Canvas] other The foreground canvas to get the
+      #   pixels from.
+      # @param [Integer] offset_x The x-offset to apply the new foreground on.
+      # @param [Integer] offset_y The y-offset to apply the new foreground on.
+      # @return [ChunkyPNG::Canvas] Returns itself, but with the other canvas
+      #   placed onto it.
+      # @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
+      #   this one, given the offset and size of the other canvas.
+      # @see #compose!
+      # @see #replace
+      def replace!(other, offset_x = 0, offset_y = 0)
+        check_size_constraints!(other, offset_x, offset_y)
+
+        for y in 0...other.height do
+          for d in 0...other.width
+            pixels[(y + offset_y) * width + offset_x + d] = other.pixels[y * other.width + d]
+          end
+        end
+        self
+      end
+
+      # Replaces pixels on this image by pixels from another pixels, on a given
+      # offset. This method will modify the current canvas.
+      #
+      # 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!}.
+      #
+      # @param (see #replace!)
+      # @return [ChunkyPNG::Canvas] Returns a new, combined canvas.
+      # @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
+      #   this one, given the offset and size of the other canvas.
+      #
+      # @note API changed since 1.0 - This method now no longer is in place,
+      #   but returns a new canvas and leaves the original intact. Use
+      #   {#replace!} if you want to replace pixels on the canvas in place.
+      # @see #compose
+      def replace(other, offset_x = 0, offset_y = 0)
+        dup.replace!(other, offset_x, offset_y)
+      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)
+        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.
+      #
+      # This will change the size and content of the current canvas. Use
+      # {#crop} if you want to have a new canvas returned instead, leaving the
+      # current canvas intact.
+      #
+      # @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 itself, but cropped.
+      # @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)
+        if crop_width + x > width
+          raise ChunkyPNG::OutOfBounds, 'Original image width is too small!'
+        end
+        if crop_height + y > height
+          raise ChunkyPNG::OutOfBounds, 'Original image height is too small!'
+        end
+
+        new_pixels = []
+        for cy in 0...crop_height do
+          new_pixels += pixels.slice((cy + y) * width + x, crop_width)
+        end
+        replace_canvas!(crop_width, crop_height, new_pixels)
+      end
+
+      # Flips the image horizontally, leaving the original intact.
+      #
+      # 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
+      # @see #flip_horizontally!
+      def flip_horizontally
+        dup.flip_horizontally!
+      end
+
+      # Flips the image horizontally in place.
+      #
+      # 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] Itself, but flipped
+      # @see #flip_horizontally
+      def flip_horizontally!
+        for y in 0..((height - 1) >> 1) do
+          other_y   = height - (y + 1)
+          other_row = row(other_y)
+          replace_row!(other_y, row(y))
+          replace_row!(y, other_row)
+        end
+        self
+      end
+
+      alias_method :flip!, :flip_horizontally!
+      alias_method :flip,  :flip_horizontally
+
+      # Flips the image vertically, leaving the original intact.
+      #
+      # 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
+      # @see #flip_vertically!
+      def flip_vertically
+        dup.flip_vertically!
+      end
+
+      # Flips the image vertically in place.
+      #
+      # 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] Itself, but flipped
+      # @see #flip_vertically
+      def flip_vertically!
+        for y in 0...height do
+          replace_row!(y, row(y).reverse)
+        end
+        self
+      end
+
+      alias_method :mirror!, :flip_vertically!
+      alias_method :mirror,  :flip_vertically
+
+      # Returns a new canvas instance that is rotated 90 degrees clockwise.
+      #
+      # This method will return a new canvas and leaves the original intact.
+      #
+      # @return [ChunkyPNG::Canvas] A clockwise-rotated copy.
+      # @see #rotate_right! for the in place version.
+      def rotate_right
+        dup.rotate_right!
+      end
+
+      # Rotates the image 90 degrees clockwise in place.
+      #
+      # This method will change the current canvas.
+      #
+      # @return [ChunkyPNG::Canvas] Itself, but rotated clockwise.
+      # @see #rotate_right for a version that leaves the current canvas intact
+      def rotate_right!
+        rotated = self.class.new(height, width)
+        new_pixels = []
+        0.upto(width - 1) { |i| new_pixels += column(i).reverse }
+        replace_canvas!(height, width, new_pixels)
+      end
+
+      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.
+      #
+      # @return [ChunkyPNG::Canvas] A rotated copy of itself.
+      # @see #rotate_left! for the in-place version.
+      def rotate_left
+        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 rotated 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.
+      #
+      # @return [ChunkyPNG::Canvas] The rotated image.
+      # @see #rotate_180!
+      def rotate_180
+        dup.rotate_180!
+      end
+
+      # Rotates the image 180 degrees in place.
+      #
+      # @return [ChunkyPNG::Canvas] Itself, but rotated 180 degrees.
+      # @see #rotate_180
+      def rotate_180!
+        pixels.reverse!
+        self
+      end
+
+      # Trims the border around the image, presumed to be the color of the
+      # first pixel.
+      #
+      # @param [Integer] border The color to attempt to trim.
+      # @return [ChunkyPNG::Canvas] The trimmed image.
+      # @see #trim!
+      def trim(border = pixels.first)
+        dup.trim!
+      end
+
+      # Trims the border around the image in place.
+      #
+      # @param [Integer] border The color to attempt to trim.
+      # @return [ChunkyPNG::Canvas] Returns itself, but with the border
+      #  trimmed.
+      # @see #trim
+      def trim!(border = pixels.first)
+        x1 = [*0...width].index   { |c| column(c).uniq != [border] }
+        x2 = [*0...width].rindex  { |c| column(c).uniq != [border] }
+        y1 = [*0...height].index  { |r|    row(r).uniq != [border] }
+        y2 = [*0...height].rindex { |r|    row(r).uniq != [border] }
+
+        crop! x1, y1, x2 - x1 + 1, y2 - y1 + 1
+      end
+
+      # Draws a border around the image.
+      #
+      # @param [Integer] size The size of the border.
+      # @param [Integer] color The color of the border.
+      # @return [ChunkyPNG::Canvas] Returns a bordered version of the image.
+      # @see #border!
+      def border(size, color = ChunkyPNG::Color::BLACK)
+        dup.border!(size, color)
+      end
+
+      # Draws a border around the image in place.
+      #
+      # @param [Integer] size The size of the border.
+      # @param [Integer] color The color of the border.
+      # @return [ChunkyPNG::Canvas] Returns itself with the border added.
+      # @see #border
+      def border!(size, color = ChunkyPNG::Color::BLACK)
+        new_width  = width  + size * 2
+        new_height = height + size * 2
+
+        bg = Canvas.new(new_width, new_height, color).replace(self, size, size)
+        replace_canvas!(new_width, new_height, bg.pixels)
+      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)
+        if width  < other.width  + offset_x
+          raise ChunkyPNG::OutOfBounds, 'Background image width is too small!'
+        end
+        if height < other.height + offset_y
+          raise ChunkyPNG::OutOfBounds, 'Background image height is too small!'
+        end
+      end
+    end
+  end
+end

data/vendor/chunky_png/lib/chunky_png/canvas/png_decoding.rb

@@ -0,0 +1,492 @@
+module ChunkyPNG
+  class Canvas
+
+    # The PNGDecoding contains methods for decoding PNG datastreams to create a 
+    # Canvas object. The datastream can be provided as filename, string or IO 
+    # stream.
+    #
+    # Overview of the decoding process:
+    #
+    # * The optional PLTE and tRNS chunk are decoded for the color palette of
+    #   the original image.
+    # * The contents of the IDAT chunks is combined, and uncompressed using
+    #   Inflate decompression to the image pixelstream.
+    # * Based on the color mode, width and height of the original image, which
+    #   is read from the PNG header (IHDR chunk), the amount of bytes
+    #   per line is determined.
+    # * For every line of pixels in the encoded image, the original byte values
+    #   are restored by unapplying the milter method for that line.
+    # * The read bytes are unfiltered given by the filter function specified by
+    #   the first byte of the line.
+    # * The unfiltered pixelstream are is into colored pixels, using the color mode.
+    # * All lines combined to form the original image.
+    #
+    # For interlaced images, the original image was split into 7 subimages.
+    # These images get decoded just like the process above (from step 3), and get 
+    # combined to form the original images.
+    #
+    # @see ChunkyPNG::Canvas::PNGEncoding
+    # @see http://www.w3.org/TR/PNG/ The W3C PNG format specification
+    module PNGDecoding
+
+      # The palette that is used to decode the image, loading from the PLTE and
+      # tRNS chunk from the PNG stream. For RGB(A) images, no palette is required.
+      # @return [ChunkyPNG::Palette]
+      attr_accessor :decoding_palette
+      
+      # The color to be replaced with fully transparent pixels.
+      attr_accessor :transparent_color
+
+      # Decodes a Canvas from a PNG encoded string.
+      # @param [String] str The string to read from.
+      # @return [ChunkyPNG::Canvas] The canvas decoded from the PNG encoded string.
+      def from_blob(str)
+        from_datastream(ChunkyPNG::Datastream.from_blob(str))
+      end
+
+      alias_method :from_string, :from_blob
+
+      # Decodes a Canvas from a PNG encoded file.
+      # @param [String] filename The file to read from.
+      # @return [ChunkyPNG::Canvas] The canvas decoded from the PNG file.
+      def from_file(filename)
+        from_datastream(ChunkyPNG::Datastream.from_file(filename))
+      end
+
+      # Decodes a Canvas from a PNG encoded stream.
+      # @param [IO, #read] io The stream to read from.
+      # @return [ChunkyPNG::Canvas] The canvas decoded from the PNG stream.
+      def from_io(io)
+        from_datastream(ChunkyPNG::Datastream.from_io(io))
+      end
+
+      alias_method :from_stream, :from_io
+
+      # Decodes the Canvas from a PNG datastream instance.
+      # @param [ChunkyPNG::Datastream] ds The datastream to decode.
+      # @return [ChunkyPNG::Canvas] The canvas decoded from the PNG datastream.
+      def from_datastream(ds)
+        width      = ds.header_chunk.width
+        height     = ds.header_chunk.height
+        color_mode = ds.header_chunk.color
+        interlace  = ds.header_chunk.interlace
+        depth      = ds.header_chunk.depth
+
+        if width == 0 || height == 0
+          raise ExpectationFailed, "Invalid image size, width: #{width}, height: #{height}"
+        end
+
+        case color_mode
+          when ChunkyPNG::COLOR_INDEXED
+            self.decoding_palette = ChunkyPNG::Palette.from_chunks(ds.palette_chunk, ds.transparency_chunk)
+          when ChunkyPNG::COLOR_TRUECOLOR
+            self.transparent_color = ds.transparency_chunk.truecolor_entry(depth) if ds.transparency_chunk
+          when ChunkyPNG::COLOR_GRAYSCALE
+            self.transparent_color = ds.transparency_chunk.grayscale_entry(depth) if ds.transparency_chunk
+        end
+            
+        decode_png_pixelstream(ds.imagedata, width, height, color_mode, depth, interlace)
+      end
+
+      # Decodes a canvas from a PNG encoded pixelstream, using a given width, height, 
+      # color mode and interlacing mode.
+      # @param [String] stream The pixelstream to read from.
+      # @param [Integer] width The width of the image.
+      # @param [Integer] width The height of the image.
+      # @param [Integer] color_mode The color mode of the encoded pixelstream.
+      # @param [Integer] depth The bit depth of the pixel samples.
+      # @param [Integer] interlace The interlace method of the encoded pixelstream.
+      # @return [ChunkyPNG::Canvas] The decoded Canvas instance.
+      def decode_png_pixelstream(stream, width, height, color_mode, depth, interlace)
+        raise ChunkyPNG::ExpectationFailed, "This palette is not suitable for decoding!" if decoding_palette && !decoding_palette.can_decode?
+
+        image = case interlace
+          when ChunkyPNG::INTERLACING_NONE;  decode_png_without_interlacing(stream, width, height, color_mode, depth)
+          when ChunkyPNG::INTERLACING_ADAM7; decode_png_with_adam7_interlacing(stream, width, height, color_mode, depth)
+          else raise ChunkyPNG::NotSupported, "Don't know how the handle interlacing method #{interlace}!"
+        end
+        
+        image.pixels.map! { |c| c == transparent_color ? ChunkyPNG::Color::TRANSPARENT : c } if transparent_color
+        return image
+      end
+
+      protected
+
+      # Decodes a canvas from a non-interlaced PNG encoded pixelstream, using a 
+      # given width, height and color mode.
+      # @param stream (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param width (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param height (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param color_mode (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param depth (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      def decode_png_without_interlacing(stream, width, height, color_mode, depth)
+        decode_png_image_pass(stream, width, height, color_mode, depth, 0)
+      end
+
+      # Decodes a canvas from a Adam 7 interlaced PNG encoded pixelstream, using a 
+      # given width, height and color mode.
+      # @param stream (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param width (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param height (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param color_mode (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param depth (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      def decode_png_with_adam7_interlacing(stream, width, height, color_mode, depth)
+        canvas = new(width, height)
+        start_pos = 0
+        for pass in 0...7
+          sm_width, sm_height = adam7_pass_size(pass, width, height)
+          sm = decode_png_image_pass(stream, sm_width, sm_height, color_mode, depth, start_pos)
+          adam7_merge_pass(pass, canvas, sm)
+          start_pos += ChunkyPNG::Color.pass_bytesize(color_mode, depth, sm_width, sm_height)
+        end
+        canvas
+      end
+      
+      # Extract 4 consecutive bits from a byte.
+      # @param [Integer] byte The byte (0..255) value to extract a 4 bit value from.
+      # @param [Integer] index The index within the byte. This should be either 0 or 2; 
+      #        the value will be modded by 2 to enforce this.
+      # @return [Integer] The extracted 4bit value (0..15)
+      def decode_png_extract_4bit_value(byte, index)
+        (index & 0x01 == 0) ? ((byte & 0xf0) >> 4) : (byte & 0x0f)
+      end
+      
+      # Extract 2 consecutive bits from a byte.
+      # @param [Integer] byte The byte (0..255) value to extract a 2 bit value from.
+      # @param [Integer] index The index within the byte. This should be either 0, 1, 2, or 3; 
+      #        the value will be modded by 4 to enforce this.
+      # @return [Integer] The extracted 2 bit value (0..3)
+      def decode_png_extract_2bit_value(byte, index)
+        bitshift = 6 - ((index & 0x03) << 1)
+        (byte & (0x03 << bitshift)) >> bitshift
+      end
+
+      # Extract a bit from a byte on a given index.
+      # @param [Integer] byte The byte (0..255) value to extract a bit from.
+      # @param [Integer] index The index within the byte. This should be 0..7; 
+      #        the value will be modded by 8 to enforce this.
+      # @return [Integer] Either 1 or 0.
+      def decode_png_extract_1bit_value(byte, index)
+        bitshift = 7 - (index & 0x07)
+        (byte & (0x01 << bitshift)) >> bitshift
+      end
+      
+      # Resamples a 16 bit value to an 8 bit value. This will discard some color information.
+      # @param [Integer] value The 16 bit value to resample.
+      # @return [Integer] The 8 bit resampled value
+      def decode_png_resample_16bit_value(value)
+        value >> 8
+      end
+      
+      # No-op - available for completeness sake only
+      # @param [Integer] value The 8 bit value to resample.
+      # @return [Integer] The 8 bit resampled value
+      def decode_png_resample_8bit_value(value)
+        value
+      end
+      
+      # Resamples a 4 bit value to an 8 bit value.
+      # @param [Integer] value The 4 bit value to resample.
+      # @return [Integer] The 8 bit resampled value.
+      def decode_png_resample_4bit_value(value)
+        value << 4 | value
+      end
+      
+      # Resamples a 2 bit value to an 8 bit value.
+      # @param [Integer] value The 2 bit value to resample.
+      # @return [Integer] The 8 bit resampled value.
+      def decode_png_resample_2bit_value(value)
+        value << 6 | value << 4 | value << 2 | value
+      end
+      
+      # Resamples a 1 bit value to an 8 bit value.
+      # @param [Integer] value The 1 bit value to resample.
+      # @return [Integer] The 8 bit resampled value
+      def decode_png_resample_1bit_value(value)
+        value == 0x01 ? 0xff : 0x00
+      end
+      
+
+      # Decodes a scanline of a 1-bit, indexed image into a row of pixels.
+      # @param [String] stream The stream to decode from.
+      # @param [Integer] pos The position in the stream on which the scanline starts (including the filter byte).
+      # @param [Integer] width The width in pixels of the scanline.
+      # @return [Array<Integer>] An array of decoded pixels.
+      def decode_png_pixels_from_scanline_indexed_1bit(stream, pos, width)
+        (0...width).map do |index|
+          palette_pos = decode_png_extract_1bit_value(stream.getbyte(pos + 1 + (index >> 3)), index) 
+          decoding_palette[palette_pos]
+        end
+      end
+
+      # Decodes a scanline of a 2-bit, indexed image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_indexed_2bit(stream, pos, width)
+        (0...width).map do |index|
+          palette_pos = decode_png_extract_2bit_value(stream.getbyte(pos + 1 + (index >> 2)), index)
+          decoding_palette[palette_pos]
+        end
+      end
+
+      # Decodes a scanline of a 4-bit, indexed image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_indexed_4bit(stream, pos, width)
+        (0...width).map do |index|
+          palette_pos = decode_png_extract_4bit_value(stream.getbyte(pos + 1 + (index >> 1)), index)
+          decoding_palette[palette_pos]
+        end
+      end
+
+      # Decodes a scanline of a 8-bit, indexed image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_indexed_8bit(stream, pos, width)
+        (1..width).map { |i| decoding_palette[stream.getbyte(pos + i)] }
+      end
+
+      # Decodes a scanline of an 8-bit, true color image with transparency into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_truecolor_alpha_8bit(stream, pos, width)
+        stream.unpack("@#{pos + 1}N#{width}")
+      end
+
+      # Decodes a scanline of a 16-bit, true color image with transparency into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_truecolor_alpha_16bit(stream, pos, width)
+        pixels = []
+        stream.unpack("@#{pos + 1}n#{width * 4}").each_slice(4) do |r, g, b, a|
+          pixels << ChunkyPNG::Color.rgba(decode_png_resample_16bit_value(r), decode_png_resample_16bit_value(g),
+                                          decode_png_resample_16bit_value(b), decode_png_resample_16bit_value(a))
+        end
+        return pixels
+      end
+      
+      # Decodes a scanline of an 8-bit, true color image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_truecolor_8bit(stream, pos, width)
+        stream.unpack("@#{pos + 1}" << ('NX' * width)).map { |c| c | 0x000000ff }
+      end
+      
+      # Decodes a scanline of a 16-bit, true color image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_truecolor_16bit(stream, pos, width)
+        pixels = []
+        stream.unpack("@#{pos + 1}n#{width * 3}").each_slice(3) do |r, g, b|
+          pixels << ChunkyPNG::Color.rgb(decode_png_resample_16bit_value(r), decode_png_resample_16bit_value(g), decode_png_resample_16bit_value(b))
+        end
+        return pixels
+      end
+
+      # Decodes a scanline of an 8-bit, grayscale image with transparency into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_alpha_8bit(stream, pos, width)
+        (0...width).map { |i| ChunkyPNG::Color.grayscale_alpha(stream.getbyte(pos + (i * 2) + 1), stream.getbyte(pos + (i * 2) + 2)) }
+      end
+      
+      # Decodes a scanline of a 16-bit, grayscale image with transparency into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_alpha_16bit(stream, pos, width)
+        pixels = []
+        stream.unpack("@#{pos + 1}n#{width * 2}").each_slice(2) do |g, a|
+          pixels << ChunkyPNG::Color.grayscale_alpha(decode_png_resample_16bit_value(g), decode_png_resample_16bit_value(a))
+        end
+        return pixels
+      end
+
+      # Decodes a scanline of a 1-bit, grayscale image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_1bit(stream, pos, width)
+        (0...width).map do |index|
+          value = decode_png_extract_1bit_value(stream.getbyte(pos + 1 + (index >> 3)), index)
+          value == 1 ? ChunkyPNG::Color::WHITE : ChunkyPNG::Color::BLACK
+        end
+      end
+
+      # Decodes a scanline of a 2-bit, grayscale image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_2bit(stream, pos, width)
+        (0...width).map do |index|
+          value = decode_png_extract_2bit_value(stream.getbyte(pos + 1 + (index >> 2)), index)
+          ChunkyPNG::Color.grayscale(decode_png_resample_2bit_value(value))
+        end
+      end
+
+      # Decodes a scanline of a 4-bit, grayscale image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_4bit(stream, pos, width)
+        (0...width).map do |index|
+          value = decode_png_extract_4bit_value(stream.getbyte(pos + 1 + (index >> 1)), index)
+          ChunkyPNG::Color.grayscale(decode_png_resample_4bit_value(value))
+        end
+      end
+      
+      # Decodes a scanline of an 8-bit, grayscale image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_8bit(stream, pos, width)
+        (1..width).map { |i| ChunkyPNG::Color.grayscale(stream.getbyte(pos + i)) }
+      end
+      
+      # Decodes a scanline of a 16-bit, grayscale image into a row of pixels.
+      # @params (see #decode_png_pixels_from_scanline_indexed_1bit)
+      # @return (see #decode_png_pixels_from_scanline_indexed_1bit)
+      def decode_png_pixels_from_scanline_grayscale_16bit(stream, pos, width)
+        values = stream.unpack("@#{pos + 1}n#{width}")
+        values.map { |value| ChunkyPNG::Color.grayscale(decode_png_resample_16bit_value(value)) }
+      end
+      
+      # Returns the method name to use to decode scanlines into pixels.
+      # @param [Integer] color_mode The color mode of the image.
+      # @param [Integer] depth The bit depth of the image.
+      # @return [Symbol] The method name to use for decoding, to be called on the canvas class.
+      # @raise [ChunkyPNG::NotSupported] when the color_mode and/or bit depth is not supported.
+      def decode_png_pixels_from_scanline_method(color_mode, depth)
+        decoder_method = case color_mode
+          when ChunkyPNG::COLOR_TRUECOLOR;       :"decode_png_pixels_from_scanline_truecolor_#{depth}bit"
+          when ChunkyPNG::COLOR_TRUECOLOR_ALPHA; :"decode_png_pixels_from_scanline_truecolor_alpha_#{depth}bit"
+          when ChunkyPNG::COLOR_INDEXED;         :"decode_png_pixels_from_scanline_indexed_#{depth}bit"
+          when ChunkyPNG::COLOR_GRAYSCALE;       :"decode_png_pixels_from_scanline_grayscale_#{depth}bit"
+          when ChunkyPNG::COLOR_GRAYSCALE_ALPHA; :"decode_png_pixels_from_scanline_grayscale_alpha_#{depth}bit"
+          else nil
+        end
+        
+        raise ChunkyPNG::NotSupported, "No decoder found for color mode #{color_mode} and #{depth}-bit depth!" unless respond_to?(decoder_method, true)
+        decoder_method
+      end
+
+      # Decodes a single PNG image pass width a given width, height and color 
+      # mode, to a Canvas, starting at the given position in the stream.
+      #
+      # A non-interlaced image only consists of one pass, while an Adam7
+      # image consists of 7 passes that must be combined after decoding.
+      #
+      # @param stream (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param width (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param height (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param color_mode (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      # @param [Integer] start_pos The position in the pixel stream to start reading.
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
+      def decode_png_image_pass(stream, width, height, color_mode, depth, start_pos)
+        
+        pixels = []
+        if width > 0 && height > 0
+          
+          stream << ChunkyPNG::EXTRA_BYTE if color_mode == ChunkyPNG::COLOR_TRUECOLOR
+          pixel_decoder = decode_png_pixels_from_scanline_method(color_mode, depth)
+          line_length   = ChunkyPNG::Color.scanline_bytesize(color_mode, depth, width)
+          pixel_size    = ChunkyPNG::Color.pixel_bytesize(color_mode, depth)
+          
+          raise ChunkyPNG::ExpectationFailed, "Invalid stream length!" unless stream.bytesize - start_pos >= ChunkyPNG::Color.pass_bytesize(color_mode, depth, width, height)
+
+          pos, prev_pos = start_pos, nil
+          for line_no in 0...height do
+            decode_png_str_scanline(stream, pos, prev_pos, line_length, pixel_size)
+            pixels += send(pixel_decoder, stream, pos, width)
+
+            prev_pos = pos
+            pos += line_length + 1
+          end
+        end
+
+        new(width, height, pixels)
+      end
+
+      # Decodes a scanline if it was encoded using filtering. 
+      #
+      # It will extract the filtering method from the first byte of the scanline, and uses the 
+      # method to change the subsequent bytes to unfiltered values. This will modify the pixelstream.
+      #
+      # The bytes of the scanline can then be used to construct pixels, based on the color mode..
+      #
+      # @param [String] stream The pixelstream to undo the filtering in.
+      # @param [Integer] pos The starting position of the scanline to decode.
+      # @param [Integer, nil] prev_pos The starting position of the previously decoded scanline, or <tt>nil</tt>
+      #     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 [void]
+      def decode_png_str_scanline(stream, pos, prev_pos, line_length, pixel_size)
+        case stream.getbyte(pos)
+          when ChunkyPNG::FILTER_NONE;    # noop
+          when ChunkyPNG::FILTER_SUB;     decode_png_str_scanline_sub(     stream, pos, prev_pos, line_length, pixel_size)
+          when ChunkyPNG::FILTER_UP;      decode_png_str_scanline_up(      stream, pos, prev_pos, line_length, pixel_size)
+          when ChunkyPNG::FILTER_AVERAGE; decode_png_str_scanline_average( stream, pos, prev_pos, line_length, pixel_size)
+          when ChunkyPNG::FILTER_PAETH;   decode_png_str_scanline_paeth(   stream, pos, prev_pos, line_length, pixel_size)
+          else raise ChunkyPNG::NotSupported, "Unknown filter type: #{stream.getbyte(pos)}!"
+        end
+      end
+
+      # Decodes a scanline that wasn't encoded using filtering. This is a no-op.
+      # @params (see #decode_png_str_scanline)
+      # @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
+
+      # Decodes a scanline in a pixelstream that was encoded using SUB filtering.
+      # This will change the pixelstream to have unfiltered values.
+      # @params (see #decode_png_str_scanline)
+      # @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)
+        end
+      end
+
+      # Decodes a scanline in a pixelstream that was encoded using UP filtering.
+      # This will change the pixelstream to have unfiltered values.
+      # @params (see #decode_png_str_scanline)
+      # @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
+          stream.setbyte(pos + i, (stream.getbyte(pos + i) + up) & 0xff)
+        end
+      end
+
+      # Decodes a scanline in a pixelstream that was encoded using AVERAGE filtering.
+      # This will change the pixelstream to have unfiltered values.
+      # @params (see #decode_png_str_scanline)
+      # @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
+          b = prev_pos ? stream.getbyte(prev_pos + i) : 0
+          stream.setbyte(pos + i, (stream.getbyte(pos + i) + ((a + b) >> 1)) & 0xff)
+        end
+      end
+
+      # Decodes a scanline in a pixelstream that was encoded using PAETH filtering.
+      # This will change the pixelstream to have unfiltered values.
+      # @params (see #decode_png_str_scanline)
+      # @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
+          a = (i > pixel_size) ? stream.getbyte(cur_pos - pixel_size) : 0
+          b = prev_pos ? stream.getbyte(prev_pos + i) : 0
+          c = (prev_pos && i > pixel_size) ? stream.getbyte(prev_pos + i - pixel_size) : 0
+          p = a + b - c
+          pa = (p - a).abs
+          pb = (p - b).abs
+          pc = (p - c).abs
+          pr = (pa <= pb) ? (pa <= pc ? a : c) : (pb <= pc ? b : c)
+          stream.setbyte(cur_pos, (stream.getbyte(cur_pos) + pr) & 0xff)
+        end
+      end
+    end
+  end
+end