chunky_png 0.0.5 → 0.5.0

data/README.rdoc

@@ -11,8 +11,8 @@ 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  
+* 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
@@ -26,21 +26,30 @@ 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.
+<tt>ChunkyPNG::Canvas</tt> :: represents an image canvas as a matrix of pixels.
+<tt>ChunkyPNG::Color</tt> :: represents a, RGBA color
 
 == Usage
 
   require 'chunky_png'
-  
+
   # 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 = ChunkyPNG::Image.new(16, 16, ChunkyPNG::Color::TRANSPARENT)
+  png[1,1] = ChunkyPNG::Color.rgba(10, 20, 30, 128)
+  png[2,1] = ChunkyPNG::Color.rgba(0, 0, 0, 128)
   png.save('filename.png')
 
-  # Modify an image - TODO
+  # Compose images using alpha blending
+  avatar = ChunkyPNG::Image.from_file('avatar.png')
+  badge  = ChunkyPNG::Image.from_file('no_ie_badge.png')
+  avatar.compose(badge, 10, 10)
+  avatar.save('composited.png', :color_mode => ChunkyPNG::COLOR_GRAYSCALE, :interlace => true)
+  
   # Inspecting metadata - TODO
+  
+  # Low level access to PNG chunks
+  png_stream = ChunkyPNG::Datastream.from_file('filename.png')
+  png_stream.each_chunk { |chunk| p chunk.type }
 
 (Note: this is subject to change while work is in progress)
 
@@ -50,4 +59,5 @@ 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! :-)
 
-P.S.: _why is why this library is so chunky.
+P.S.: The name of this library is intentionally similar to Chunky Bacon and 
+Chunky GIF. Use Google if you want to know _why.

data/chunky_png.gemspec

@@ -1,13 +1,25 @@
 Gem::Specification.new do |s|
   s.name    = 'chunky_png'
-  
+
   # Do not change the version and date fields by hand. This will be done
   # automatically by the gem release script.
-  s.version = "0.0.5"
-  s.date    = "2010-01-13"
+  s.version = "0.5.0"
+  s.date    = "2010-01-16"
 
   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"
+  s.description = <<-EOT
+    This pure Ruby library can read and write PNG images without depending on an external 
+    image library, like RMagick. It tries to be memory efficient and reasonably fast.
+    
+    It supports reading and writing all PNG variants that are defined in the specification, 
+    with one limitation: only 8-bit color depth is supported. It supports all transparency, 
+    interlacing and filtering options the PNG specifications allows. It can also read and 
+    write textual metadata from PNG files. Low-level read/write access to PNG chunks is
+    also possible.
+    
+    This library supports simple drawing on the image canvas and simple operations like alpha composition
+    and cropping. Finally, it can import from and export to RMagick for interoperability. 
+  EOT
 
   s.authors  = ['Willem van Bergen']
   s.email    = ['willem@railsdoctors.com']
@@ -20,6 +32,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/pixelstream.rgb 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 spec/resources/operations.png 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_matrix/operations.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/pixelstream_reference.png 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)
+  s.files      = %w(spec/spec_helper.rb spec/resources/ztxt_chunk.png spec/resources/text_chunk.png spec/resources/replaced.png spec/resources/pixelstream.rgb spec/resources/gray_10x10_grayscale.png spec/resources/damaged_signature.png spec/resources/damaged_chunk.png spec/chunky_png/canvas/png_encoding_spec.rb spec/resources/gray_10x10.png lib/chunky_png/color.rb lib/chunky_png/canvas/operations.rb .gitignore spec/resources/gray_10x10_truecolor_alpha.png spec/chunky_png/canvas_spec.rb LICENSE spec/resources/gray_10x10_truecolor.png spec/resources/composited.png spec/chunky_png/color_spec.rb spec/chunky_png/canvas/adam7_interlacing_spec.rb lib/chunky_png/chunk.rb lib/chunky_png/canvas/png_encoding.rb lib/chunky_png/canvas/adam7_interlacing.rb spec/resources/operations.png spec/chunky_png/canvas/png_decoding_spec.rb lib/chunky_png/canvas.rb Rakefile spec/resources/transparent_gray_10x10.png spec/resources/pixelstream.rgba spec/resources/cropped.png README.rdoc spec/resources/gray_10x10_indexed.png spec/resources/16x16_non_interlaced.png spec/chunky_png_spec.rb lib/chunky_png/palette.rb lib/chunky_png/datastream.rb chunky_png.gemspec tasks/github-gem.rake spec/resources/pixelstream_reference.png spec/resources/gray_10x10_grayscale_alpha.png spec/resources/16x16_interlaced.png spec/chunky_png/image_spec.rb lib/chunky_png/canvas/drawing.rb spec/resources/adam7.png lib/chunky_png/rmagick.rb lib/chunky_png/image.rb spec/chunky_png/rmagick_spec.rb spec/chunky_png/datastream_spec.rb lib/chunky_png/canvas/png_decoding.rb lib/chunky_png.rb)
+  s.test_files = %w(spec/chunky_png/canvas/png_encoding_spec.rb spec/chunky_png/canvas_spec.rb spec/chunky_png/color_spec.rb spec/chunky_png/canvas/adam7_interlacing_spec.rb spec/chunky_png/canvas/png_decoding_spec.rb spec/chunky_png_spec.rb spec/chunky_png/image_spec.rb spec/chunky_png/rmagick_spec.rb spec/chunky_png/datastream_spec.rb)
 end

data/lib/chunky_png.rb

@@ -4,11 +4,13 @@ require 'zlib'
 require 'chunky_png/datastream'
 require 'chunky_png/chunk'
 require 'chunky_png/palette'
-require 'chunky_png/pixel'
-require 'chunky_png/pixel_matrix/encoding'
-require 'chunky_png/pixel_matrix/decoding'
-require 'chunky_png/pixel_matrix/operations'
-require 'chunky_png/pixel_matrix'
+require 'chunky_png/color'
+require 'chunky_png/canvas/png_encoding'
+require 'chunky_png/canvas/png_decoding'
+require 'chunky_png/canvas/adam7_interlacing'
+require 'chunky_png/canvas/operations'
+require 'chunky_png/canvas/drawing'
+require 'chunky_png/canvas'
 require 'chunky_png/image'
 
 # ChunkyPNG
@@ -16,7 +18,10 @@ require 'chunky_png/image'
 # The ChunkyPNG module defines some constants that are used in the
 # PNG specification.
 module ChunkyPNG
-  extend self
+
+  # The current version of ChunkyPNG. This value will be updated automatically
+  # by them gem:release rake task.
+  VERSION = "0.5.0"
 
   ###################################################
   # PNG international standard defined constants
@@ -40,26 +45,4 @@ module ChunkyPNG
   FILTER_UP             = 2
   FILTER_AVERAGE        = 3
   FILTER_PAETH          = 4
-
-  def load_from_io(io)
-    ChunkyPNG::Datastream.read(io)
-  end
-
-  def load_from_file(file)
-    File.open(file, 'rb') { |f| load_from_io(f) }
-  end
-
-  def load_from_memory(string)
-    load_from_io(StringIO.new(string))
-  end
-
-  def load(arg)
-    if arg.respond_to?(:read)
-      load_from_io(arg)
-    elsif File.exists?(arg)
-      load_from_file(arg)
-    else
-      load_from_memory(arg)
-    end
-  end
 end

data/lib/chunky_png/canvas.rb

@@ -0,0 +1,186 @@
+module ChunkyPNG
+
+  # The ChunkPNG::Canvas class represents a raster image as a matrix of
+  # pixels. 
+  #
+  # This class supports loading a Canvas from a PNG datastream, and creating a
+  # {ChunkyPNG::Datastream PNG datastream} based on this matrix. ChunkyPNG
+  # only supports 8-bit color depth, otherwise all of the PNG format's
+  # variations are supported for both reading and writing.
+  #
+  # 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.
+  #
+  # The pixels in the canvas are stored as 4-byte fixnum, representing 32-bit
+  # RGBA colors (8 bit per channel). The module {ChunkyPNG::Color} is provided
+  # to work more easily with these number as color values.
+  #
+  # The module {ChunkyPNG::Canvas::Operations} is imported for operations on
+  # the whole canvas, like cropping and alpha compositing. Simple drawing
+  # functions are imported from the {ChunkyPNG::Canvas::Drawing} module.
+  class Canvas
+
+    include PNGEncoding
+    extend  PNGDecoding
+    extend  Adam7Interlacing
+
+    include Operations
+    include Drawing
+
+    # @return [Integer] The number of columns in this canvas
+    attr_reader :width
+
+    # @return [Integer] The number of rows in this canvas
+    attr_reader :height
+
+    # @return [Array<ChunkyPNG::Color>] The list of pixels in this canvas.
+    #     This array always should have +width * height+ elements.
+    attr_reader :pixels
+
+    # Initializes a new Canvas instance
+    # @param [Integer] width The width in pixels of this canvas
+    # @param [Integer] width The height in pixels of this canvas
+    # @param [ChunkyPNG::Pixel, Array<ChunkyPNG::Color>] 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::Color::TRANSPARENT)
+
+      @width, @height = width, height
+
+      if initial.kind_of?(Fixnum)
+        @pixels = Array.new(width * height, initial)
+      elsif initial.kind_of?(Array) && initial.size == width * height
+        @pixels = initial.map(&:to_i)
+      else
+        raise "Cannot use this value as initial canvas: #{initial.inspect}!"
+      end
+    end
+    
+    def initialize_copy(other)
+      @width, @height = other.width, other.height
+      @pixels = other.pixels.dup
+    end
+
+    # Returns the size ([width, height]) for this canvas.
+    # @return Array An array with the width and height of this canvas as elements.
+    def size
+      [@width, @height]
+    end
+
+    # Replaces a single pixel in this canvas.
+    # @param [Integer] x The x-coordinate of the pixel (column)
+    # @param [Integer] y The y-coordinate of the pixel (row)
+    # @param [ChunkyPNG::Color] pixel The new pixel for the provided coordinates.
+    def []=(x, y, color)
+      @pixels[y * width + x] = color
+    end
+
+    # Returns a single pixel from this canvas.
+    # @param [Integer] x The x-coordinate of the pixel (column)
+    # @param [Integer] y The y-coordinate of the pixel (row)
+    # @return [ChunkyPNG::Color] The current pixel at the provided coordinates.
+    def [](x, y)
+      @pixels[y * width + x]
+    end
+
+    # Returns the palette used for this canvas.
+    # @return [ChunkyPNG::Palette] A pallete which contains all the colors that are
+    #    being used for this image.
+    def palette
+      ChunkyPNG::Palette.from_canvas(self)
+    end
+
+    # Equality check to compare this canvas 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 canvas
+    #    are exactly the same as this canvas's size and pixel values.
+    def eql?(other)
+      other.kind_of?(self.class) && other.pixels == self.pixels &&
+            other.width == self.width && other.height == self.height
+    end
+
+    alias :== :eql?
+
+    # Creates an ChunkyPNG::Image object from this canvas
+    def to_image
+      ChunkyPNG::Image.from_canvas(self)
+    end
+
+    #################################################################
+    # CONSTRUCTORS
+    #################################################################
+
+    # Creates a new canvas instance by duplicating another instance.
+    # @param [ChunkyPNG::Canvas] canvas The canvas to duplicate
+    # @return [ChunkyPNG::Canvas] The newly constructed canvas instance.
+    def self.from_canvas(canvas)
+      self.new(canvas.width, canvas.height, canvas.pixels.dup)
+    end
+
+    # Creates a canvas by reading pixels from an RGB formatted stream with a
+    # provided with and height. 
+    #
+    # Every pixel should be represented by 3 bytes in the stream, in the correct
+    # RGB order. This format closely resembles the internal representation of a
+    # canvas object, so this kind of stream can be read extremely quickly.
+    #
+    # @param [Integer] width The width of the new canvas.
+    # @param [Integer] height The height of the new canvas.
+    # @param [#read, String] stream The stream to read the pixel data from.
+    # @return [ChunkyPNG::Canvas] The newly constructed canvas instance.
+    def self.from_rgb_stream(width, height, stream)
+      string = stream.respond_to?(:read) ? stream.read(3 * width * height) : stream.to_s[0, 3 * width * height]
+      string << "\255" # Add a fourth byte to the last RGB triple.
+      unpacker = 'NX' * (width * height)
+      pixels = string.unpack(unpacker).map { |color| color | 0x000000ff }
+      self.new(width, height, pixels)
+    end
+
+    # Creates a canvas by reading pixels from an RGBA formatted stream with a
+    # provided with and height. 
+    #
+    # Every pixel should be represented by 4 bytes in the stream, in the correct
+    # RGBA order. This format is exactly like the internal representation of a
+    # canvas object, so this kind of stream can be read extremely quickly.
+    #
+    # @param [Integer] width The width of the new canvas. 
+    # @param [Integer] height The height of the new canvas. 
+    # @param [#read, String] stream The stream to read the pixel data from. 
+    # @return [ChunkyPNG::Canvas] The newly constructed canvas instance.
+    def self.from_rgba_stream(width, height, stream)
+      string = stream.respond_to?(:read) ? stream.read(4 * width * height) : stream.to_s[0, 4 * width * height]
+      self.new(width, height, string.unpack("N*"))
+    end
+    
+    #################################################################
+    # EXPORTING
+    #################################################################
+    
+    # Creates an RGB-formatted pixelstream with the pixel data from this canvas.
+    #
+    # Note that this format is fast but bloated, because no compression is used
+    # and the internal representation is left intact. However, to reconstruct the
+    # canvas, the width and height should be known.
+    #
+    # @return [String] The RGBA-formatted pixel data.
+    def to_rgba_stream
+      pixels.pack('N*')
+    end
+
+    # Creates an RGB-formatted pixelstream with the pixel data from this canvas.
+    #
+    # Note that this format is fast but bloated, because no compression is used
+    # and the internal representation is almost left intact. However, to reconstruct 
+    # the canvas, the width and height should be known.
+    #
+    # @return [String] The RGB-formatted pixel data.
+    def to_rgb_stream
+      packer = 'NX' * (width * height)
+      pixels.pack(packer)
+    end
+  end
+end

data/lib/chunky_png/canvas/adam7_interlacing.rb

@@ -0,0 +1,53 @@
+module ChunkyPNG
+  class Canvas
+    
+    # Methods for decoding and encoding adam7 interlacing
+    #
+    module Adam7Interlacing
+      
+      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_pass_size(pass, original_width, original_height)
+        m_o = adam7_multiplier_offset(pass)
+        [ ((original_width  - m_o[:x_offset] ) / m_o[:x_multiplier].to_f).ceil,
+          ((original_height - m_o[:y_offset] ) / m_o[:y_multiplier].to_f).ceil]
+      end
+
+      def adam7_pass_sizes(original_width, original_height)
+        (0...7).map { |pass| adam7_pass_size(pass, original_width, original_height) }
+      end
+
+      def adam7_merge_pass(pass, canvas, subcanvas)
+        m_o = adam7_multiplier_offset(pass)
+        0.upto(subcanvas.height - 1) do |y|
+          0.upto(subcanvas.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]
+            canvas[new_x, new_y] = subcanvas[x, y]
+          end
+        end
+        canvas
+      end
+      
+      def adam7_extract_pass(pass, canvas)
+        m_o = adam7_multiplier_offset(pass)
+        sm_pixels = []
+        m_o[:y_offset].step(canvas.height - 1, m_o[:y_multiplier]) do |y|
+          m_o[:x_offset].step(canvas.width - 1, m_o[:x_multiplier]) do |x|
+            sm_pixels << canvas[x, y]
+          end
+        end
+        
+        new_canvas_args = adam7_pass_size(pass, canvas.width, canvas.height) + [sm_pixels]
+        ChunkyPNG::Canvas.new(*new_canvas_args)
+      end
+    end
+  end
+end

data/lib/chunky_png/canvas/drawing.rb

@@ -0,0 +1,8 @@
+module ChunkyPNG
+  class Canvas
+    
+    module Drawing
+      
+    end
+  end
+end

data/lib/chunky_png/{pixel_matrix → canvas}/operations.rb

@@ -1,34 +1,34 @@
 module ChunkyPNG
-  class PixelMatrix
+  class Canvas
     module Operations
-      def compose(other, dx = 0, dy = 0)
-        check_size_constraints!(other, dx, dy)
-        
-        other.height.times do |y|
-          other.width.times do |x|
-            self[x+dx, y+dy] = self[x+dx, y+dy] & other[x, y]
+      def compose(new_foreground, dx = 0, dy = 0)
+        check_size_constraints!(new_foreground, dx, dy)
+
+        new_foreground.height.times do |y|
+          new_foreground.width.times do |x|
+            self[x+dx, y+dy] = ChunkyPNG::Color.compose(new_foreground[x, y], self[x+dx, y+dy])
           end
         end
         self
       end
-      
+
       def replace(other, offset_x = 0, offset_y = 0)
         check_size_constraints!(other, offset_x, offset_y)
-        
+
         other.height.times do |y|
           pixels[(y + offset_y) * width + offset_x, other.width] = other.pixels[y * other.width, other.width]
         end
         self
       end
-      
+
       def crop(x, y, crop_width, crop_height)
         new_pixels = []
         crop_height.times do |cy|
           new_pixels += pixels.slice((cy + y) * width + x, crop_width)
         end
-        ChunkyPNG::PixelMatrix.new(crop_width, crop_height, new_pixels)
+        ChunkyPNG::Canvas.new(crop_width, crop_height, new_pixels)
       end
-      
+
       protected
 
       def check_size_constraints!(other, offset_x, offset_y)