chunky_png 0.5.4 → 0.5.5

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.5.4"
-  s.date    = "2010-01-18"
+  s.version = "0.5.5"
+  s.date    = "2010-02-16"
 
   s.summary     = "Pure ruby library for read/write, chunk-level access to PNG files"
   s.description = <<-EOT

data/lib/chunky_png.rb

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

data/lib/chunky_png/canvas/png_decoding.rb

@@ -1,26 +1,65 @@
 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 object.
+
+    # 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 original image, the determined amount
+    #   of bytes is read from the pixel stream.
+    # * The read bytes are unfiltered given by the filter function specified by
+    #   the first byte of the line.
+    # * The unfiltered bytes are converted into colored pixels, using the color mode.
+    # * All lines combined 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
 
+      # 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 :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
 
+      # 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)
         raise "Only 8-bit color depth is currently supported by ChunkyPNG!" unless ds.header_chunk.depth == 8
 
@@ -28,13 +67,21 @@ module ChunkyPNG
         height     = ds.header_chunk.height
         color_mode = ds.header_chunk.color
         interlace  = ds.header_chunk.interlace
-        
+
         self.decoding_palette = ChunkyPNG::Palette.from_chunks(ds.palette_chunk, ds.transparency_chunk)
         pixelstream           = ChunkyPNG::Chunk::ImageData.combine_chunks(ds.data_chunks)
-        
+
         decode_png_pixelstream(pixelstream, width, height, color_mode, 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] interlace The interlace method of the encoded pixelstream.
+      # @return [ChunkyPNG::Canvas] The decoded Canvas instance.
       def decode_png_pixelstream(stream, width, height, color_mode = ChunkyPNG::COLOR_TRUECOLOR, interlace = ChunkyPNG::INTERLACING_NONE)
         raise "This palette is not suitable for decoding!" if decoding_palette && !decoding_palette.can_decode?
 
@@ -47,10 +94,24 @@ module ChunkyPNG
 
       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)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
       def decode_png_without_interlacing(stream, width, height, color_mode)
         decode_png_image_pass(stream, width, height, color_mode)
       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)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_pixelstream)
       def decode_png_with_adam7_interlacing(stream, width, height, color_mode)
         canvas     = ChunkyPNG::Canvas.new(width, height)
         pixel_size = Color.bytesize(color_mode)
@@ -64,6 +125,18 @@ module ChunkyPNG
         canvas
       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, start_pos = 0)
         
         pixel_size    = Color.bytesize(color_mode)
@@ -99,8 +172,20 @@ module ChunkyPNG
         new(width, height, pixels)
       end
 
-
-
+      # Decodes filtered bytes from a scanline from a PNG pixelstream,
+      # to return the original bytes of the image.
+      #
+      # The decoded bytes should be used to get the original pixels of the 
+      # scanline, combining them using a color mode dependent color decoder.
+      #
+      # @param [Integer] filter The filter used to encode the bytes.
+      # @param [Array<Fixnum>] bytes The filtered bytes to decode.
+      # @param [Array<Fixnum>] previous_bytes The decoded bytes of the 
+      #      previous scanline.
+      # @param [Integer] pixelsize The amount of bytes used for every pixel.
+      #      This depends on the used color mode and color depth.
+      # @return [Array<Fixnum>] The array of original bytes for the scanline,
+      #      before they were encoded.
       def decode_png_scanline(filter, bytes, previous_bytes, pixelsize = 3)
         case filter
         when ChunkyPNG::FILTER_NONE    then decode_png_scanline_none(    bytes, previous_bytes, pixelsize)
@@ -112,20 +197,44 @@ module ChunkyPNG
         end
       end
 
+      # Decoded filtered scanline bytes that were not filtered.
+      # @param bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param previous_bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param pixelsize (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline
       def decode_png_scanline_none(bytes, previous_bytes, pixelsize = 3)
         bytes
       end
 
+      # Decoded filtered scanline bytes that were filtered using SUB filtering.
+      # @param bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param previous_bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param pixelsize (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline
       def decode_png_scanline_sub(bytes, previous_bytes, pixelsize = 3)
         bytes.each_with_index { |b, i| bytes[i] = (b + (i >= pixelsize ? bytes[i-pixelsize] : 0)) % 256 }
         bytes
       end
 
+      # Decoded filtered scanline bytes that were filtered using UP filtering.
+      # @param bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param previous_bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param pixelsize (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline
       def decode_png_scanline_up(bytes, previous_bytes, pixelsize = 3)
         bytes.each_with_index { |b, i| bytes[i] = (b + previous_bytes[i]) % 256 }
         bytes
       end
 
+      # Decoded filtered scanline bytes that were filtered using AVERAGE filtering.
+      # @param bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param previous_bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param pixelsize (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline
       def decode_png_scanline_average(bytes, previous_bytes, pixelsize = 3)
         bytes.each_with_index do |byte, i|
           a = (i >= pixelsize) ? bytes[i - pixelsize] : 0
@@ -135,6 +244,12 @@ module ChunkyPNG
         bytes
       end
 
+      # Decoded filtered scanline bytes that were filtered using PAETH filtering.
+      # @param bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param previous_bytes (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @param pixelsize (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @return (see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline)
+      # @see ChunkyPNG::Canvas::PNGDecoding#decode_png_scanline
       def decode_png_scanline_paeth(bytes, previous_bytes, pixelsize = 3)
         bytes.each_with_index do |byte, i|
           a = (i >= pixelsize) ? bytes[i - pixelsize] : 0

data/lib/chunky_png/canvas/png_encoding.rb

@@ -1,20 +1,49 @@
 module ChunkyPNG
   class Canvas
     
-    # Methods for encoding a Canvas into a PNG datastream
+    # Methods for encoding a Canvas instance into a PNG datastream.
     #
+    # Overview of the encoding process:
+    #
+    # * The image is split up in scanlines (i.e. rows of pixels);
+    # * Every pixel in this row is converted into bytes, based on the color mode;
+    # * Filter every byte in the row according to the filter method.
+    # * Concatenate all the filtered bytes of every line to a single stream
+    # * Compress the resulting string using deflate compression.
+    # * Split compressed data over one or more PNG chunks.
+    # * These chunks should be embedded in a datastream with at least a IHDR and 
+    #   IEND chunk and possibly a PLTE chunk.
+    #
+    # For interlaced images, the initial image is first split into 7 subimages.
+    # These images get encoded exectly as above, and the result gets combined 
+    # before the compression step.
+    #
+    # @see ChunkyPNG::Canvas::PNGDecoding
+    # @see http://www.w3.org/TR/PNG/ The W3C PNG format specification
     module PNGEncoding
 
+      # The palette used for encoding the image.This is only in used for images
+      # that get encoded using indexed colors.
+      # @return [ChunkyPNG::Palette]
       attr_accessor :encoding_palette
 
+      # 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)
       def write(io, constraints = {})
         to_datastream(constraints).write(io)
       end
 
+      # 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)
       def save(filename, constraints = {})
         File.open(filename, 'wb') { |io| write(io, constraints) }
       end
       
+      # Encoded the canvas to a PNG formatted string.
+      # @param constraints (see ChunkyPNG::Canvas::PNGEncoding#to_datastream)
+      # @return [String] The PNG encoded canvas as string.
       def to_blob(constraints = {})
         to_datastream(constraints).to_blob
       end
@@ -24,33 +53,36 @@ module ChunkyPNG
 
       # Converts this Canvas to a datastream, so that it can be saved as a PNG image.
       # @param [Hash] constraints The constraints to use when encoding the canvas.
+      # @return [ChunkyPNG::Datastream] The PNG datastream containing the encoded canvas.
+      # @see ChunkyPNG::Canvas::PNGEncoding#determine_png_encoding
       def to_datastream(constraints = {})
-        data = encode_png(constraints)
+        encoding = determine_png_encoding(constraints)
+        
         ds = Datastream.new
-        ds.header_chunk       = Chunk::Header.new(data[:header])
-        ds.palette_chunk      = data[:palette_chunk]      if data[:palette_chunk]
-        ds.transparency_chunk = data[:transparency_chunk] if data[:transparency_chunk]
-        ds.data_chunks        = Chunk::ImageData.split_in_chunks(data[:pixelstream])
-        ds.end_chunk          = Chunk::End.new
+        ds.header_chunk = Chunk::Header.new(:width => width, :height => height, 
+            :color => encoding[:color_mode], :interlace => encoding[:interlace])
+        
+        if encoding[:color_mode] == ChunkyPNG::COLOR_INDEXED
+          ds.palette_chunk      = encoding_palette.to_plte_chunk
+          ds.transparency_chunk = encoding_palette.to_trns_chunk unless encoding_palette.opaque?
+        end
+        
+        data           = encode_png_pixelstream(encoding[:color_mode], encoding[:interlace])
+        ds.data_chunks = Chunk::ImageData.split_in_chunks(data)
+        ds.end_chunk   = Chunk::End.new
         return ds
       end
 
       protected
-      
-      def encode_png(constraints = {})
-        encoding = determine_png_encoding(constraints)
-        result = {}
-        result[:header] = { :width => width, :height => height, :color => encoding[:color_mode], :interlace => encoding[:interlace] }
-
-        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
-
-        result[:pixelstream] = encode_png_pixelstream(encoding[:color_mode], encoding[:interlace])
-        return result
-      end
 
+      # Determines the best possible PNG encoding variables for this image, by analyzing 
+      # the colors used for the image.
+      #
+      # You can provide constraints for the encoding variables by passing a hash with 
+      # encoding variables to this method.
+      #
+      # @param [Hash] constraints The constraints for the encoding.
+      # @return [Hash] A hash with encoding options for {ChunkyPNG::Canvas::PNGEncoding#to_datastream}
       def determine_png_encoding(constraints = {})
         
         if constraints == :fast_rgb
@@ -80,6 +112,11 @@ module ChunkyPNG
         return encoding
       end
       
+      # Encodes the canvas according to the PNG format specification with a given color 
+      # mode, possibly with interlacing.
+      # @param [Integer] color_mode The color mode to use for encoding.
+      # @param [Integer] interlace The interlacing method to use.
+      # @param [String] The PNG encoded canvas as string.
       def encode_png_pixelstream(color_mode = ChunkyPNG::COLOR_TRUECOLOR, interlace = ChunkyPNG::INTERLACING_NONE)
 
         if color_mode == ChunkyPNG::COLOR_INDEXED && (encoding_palette.nil? || !encoding_palette.can_encode?)
@@ -93,12 +130,23 @@ module ChunkyPNG
         end
       end
 
+      # Encodes the canvas according to the PNG format specification with a given color mode.
+      # @param [Integer] color_mode The color mode to use for encoding.
+      # @param [String] Th PNG encoded canvas as string.
       def encode_png_image_without_interlacing(color_mode)
         stream = ""
         encode_png_image_pass_to_stream(stream, color_mode)
         stream
       end
       
+      # Encodes the canvas according to the PNG format specification with a given color 
+      # mode and Adam7 interlacing.
+      #
+      # This method will split the original canva in 7 smaller canvases and encode them 
+      # one by one, concatenating the resulting strings.
+      #
+      # @param [Integer] color_mode The color mode to use for encoding.
+      # @param [String] Th PNG encoded canvas as string.
       def encode_png_image_with_interlacing(color_mode)
         stream = ""
         0.upto(6) do |pass|
@@ -109,35 +157,37 @@ module ChunkyPNG
         stream
       end
       
+      # Encodes the canvas to a stream, in a given color mode.
+      # @param [String, IO, :<<] stream The stream to write to.
+      # @param [Integer] color_mode The color mode to use for encoding.
       def encode_png_image_pass_to_stream(stream, color_mode)
 
         case color_mode
-          when ChunkyPNG::COLOR_TRUECOLOR_ALPHA
-            stream << pixels.pack("xN#{width}" * height)
-            
-          when ChunkyPNG::COLOR_TRUECOLOR 
-            line_packer = 'x' + ('NX' * width)
-            stream << pixels.pack(line_packer * height)
-            
-          else
-            
-            pixel_size = Color.bytesize(color_mode)
-            pixel_encoder = case color_mode
-              when ChunkyPNG::COLOR_TRUECOLOR       then lambda { |color| Color.to_truecolor_bytes(color) }
-              when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then lambda { |color| Color.to_truecolor_alpha_bytes(color) }
-              when ChunkyPNG::COLOR_INDEXED         then lambda { |color| [encoding_palette.index(color)] }
-              when ChunkyPNG::COLOR_GRAYSCALE       then lambda { |color| Color.to_grayscale_bytes(color) }
-              when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then lambda { |color| Color.to_grayscale_alpha_bytes(color) }
-              else raise "Cannot encode pixels for this mode: #{color_mode}!"
-            end
-
-            previous_bytes = Array.new(pixel_size * width, 0)
-            each_scanline do |line|
-              unencoded_bytes = line.map(&pixel_encoder).flatten
-              stream << encode_png_scanline_up(unencoded_bytes, previous_bytes, pixel_size).pack('C*')
-              previous_bytes = unencoded_bytes
-            end
+        when ChunkyPNG::COLOR_TRUECOLOR_ALPHA
+          stream << pixels.pack("xN#{width}" * height)
+          
+        when ChunkyPNG::COLOR_TRUECOLOR 
+          line_packer = 'x' + ('NX' * width)
+          stream << pixels.pack(line_packer * height)
+          
+        else
+          pixel_size = Color.bytesize(color_mode)
+          pixel_encoder = case color_mode
+            when ChunkyPNG::COLOR_TRUECOLOR       then lambda { |color| Color.to_truecolor_bytes(color) }
+            when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then lambda { |color| Color.to_truecolor_alpha_bytes(color) }
+            when ChunkyPNG::COLOR_INDEXED         then lambda { |color| [encoding_palette.index(color)] }
+            when ChunkyPNG::COLOR_GRAYSCALE       then lambda { |color| Color.to_grayscale_bytes(color) }
+            when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then lambda { |color| Color.to_grayscale_alpha_bytes(color) }
+            else raise "Cannot encode pixels for this mode: #{color_mode}!"
+          end
+
+          previous_bytes = Array.new(pixel_size * width, 0)
+          each_scanline do |line|
+            unencoded_bytes = line.map(&pixel_encoder).flatten
+            stream << encode_png_scanline_up(unencoded_bytes, previous_bytes, pixel_size).pack('C*')
+            previous_bytes = unencoded_bytes
           end
+        end
       end
 
       # Passes to this canvas of pixel values line by line.
@@ -150,6 +200,12 @@ module ChunkyPNG
         end
       end
 
+      # Encodes the bytes of a scanline with a given filter.
+      # @param [Integer] filter The filter method to use.
+      # @param [Array<Fixnum>]  bytes The scanline bytes to encode.
+      # @param [Array<Fixnum>]  previous_bytes The original bytes of the previous scanline.
+      # @param [Integer] pixelsize The number of bytes per pixel.
+      # @return [Array<Fixnum>] The filtered array of bytes.
       def encode_png_scanline(filter, bytes, previous_bytes = nil, pixelsize = 3)
         case filter
         when ChunkyPNG::FILTER_NONE    then encode_png_scanline_none(    bytes, previous_bytes, pixelsize)
@@ -161,10 +217,17 @@ module ChunkyPNG
         end
       end
 
+      # Encodes the bytes of a scanline without filtering.
+      # @param [Array<Fixnum>]  bytes The scanline bytes to encode.
+      # @param [Array<Fixnum>]  previous_bytes The original bytes of the previous scanline.
+      # @param [Integer] pixelsize The number of bytes per pixel.
+      # @return [Array<Fixnum>] The filtered array of bytes.
       def encode_png_scanline_none(original_bytes, previous_bytes = nil, pixelsize = 3)
         [ChunkyPNG::FILTER_NONE] + original_bytes
       end
 
+      # Encodes the bytes of a scanline with SUB filtering.
+      # @param (see ChunkyPNG::Canvas::PNGEncoding#encode_png_scanline_none)
       def encode_png_scanline_sub(original_bytes, previous_bytes = nil, pixelsize = 3)
         encoded_bytes = []
         for index in 0...original_bytes.length do
@@ -174,6 +237,8 @@ module ChunkyPNG
         [ChunkyPNG::FILTER_SUB] + encoded_bytes
       end
 
+      # Encodes the bytes of a scanline with UP filtering.
+      # @param (see ChunkyPNG::Canvas::PNGEncoding#encode_png_scanline_none)
       def encode_png_scanline_up(original_bytes, previous_bytes, pixelsize = 3)
         encoded_bytes = []
         for index in 0...original_bytes.length do
@@ -182,7 +247,9 @@ module ChunkyPNG
         end
         [ChunkyPNG::FILTER_UP] + encoded_bytes
       end
-      
+
+      # Encodes the bytes of a scanline with AVERAGE filtering.
+      # @param (see ChunkyPNG::Canvas::PNGEncoding#encode_png_scanline_none)
       def encode_png_scanline_average(original_bytes, previous_bytes, pixelsize = 3)
         encoded_bytes = []
         for index in 0...original_bytes.length do
@@ -192,7 +259,9 @@ module ChunkyPNG
         end
         [ChunkyPNG::FILTER_AVERAGE] + encoded_bytes
       end
-      
+
+      # Encodes the bytes of a scanline with PAETH filtering.
+      # @param (see ChunkyPNG::Canvas::PNGEncoding#encode_png_scanline_none)
       def encode_png_scanline_paeth(original_bytes, previous_bytes, pixelsize = 3)
         encoded_bytes = []
         for i in 0...original_bytes.length do

data/lib/chunky_png/color.rb

@@ -130,6 +130,13 @@ module ChunkyPNG
       a(value) == 0x000000ff
     end
     
+    # Returns the opaque value of this color by removing the alpha channel.
+    # @param [Fixnum] value The color to transform.
+    # @return [Fixnum] The opauq color
+    def opaque!(value)
+      value | 0x000000ff
+    end
+    
     # Returns true if this color is fully transparent.
     #
     # @param [Fixnum] value The color to test.
@@ -230,6 +237,25 @@ module ChunkyPNG
       new_alpha = int8_mult(a(color), factor)
       (color & 0xffffff00) | new_alpha
     end
+    
+    def alpha_decomposable?(color, mask, bg, tolerance = 1)
+      components = decompose_alpha_components(color, mask, bg)
+      sum = components.inject(0) { |a,b| a + b } 
+      max = components.max * 3
+      return (sum + tolerance * 3) >= max
+    end
+    
+    def decompose_alpha(color, mask, bg)
+      components = decompose_alpha_components(color, mask, bg)
+      (components.inject(0) { |a,b| a + b } / 3.0).round
+    end
+    
+    def decompose_alpha_components(color, mask, bg)
+      a_r = ((r(bg) - r(color)).to_f / (r(bg) - r(mask)).to_f * MAX).round
+      a_g = ((g(bg) - g(color)).to_f / (g(bg) - g(mask)).to_f * MAX).round
+      a_b = ((b(bg) - b(color)).to_f / (b(bg) - b(mask)).to_f * MAX).round
+      [a_r, a_g, a_b]
+    end
 
     ####################################################################
     # CONVERSIONS

data/spec/chunky_png/color_spec.rb

@@ -91,6 +91,12 @@ describe ChunkyPNG::Color do
     end
   end
   
+  describe '#decompose_alpha' do
+    it "should decompose the alpha channel correctly" do
+      decompose_alpha(0x9fc2d6ff, @opaque, @white).should == 0x00000064
+    end
+  end
+  
   describe '#blend' do
     it "should blend colors correctly" do
       blend(@opaque, @black).should == 0x05324bff

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: chunky_png
 version: !ruby/object:Gem::Version 
-  version: 0.5.4
+  version: 0.5.5
 platform: ruby
 authors: 
 - Willem van Bergen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-18 00:00:00 +01:00
+date: 2010-02-16 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency