chunky_png 0.0.5 → 0.5.0

data/lib/chunky_png/canvas/png_decoding.rb

@@ -0,0 +1,145 @@
+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.
+    module PNGDecoding
+
+      def from_blob(str)
+        from_datastream(ChunkyPNG::Datastream.from_blob(str))
+      end
+      
+      alias :from_string :from_blob
+
+      def from_file(filename)
+        from_datastream(ChunkyPNG::Datastream.from_file(filename))
+      end
+      
+      def from_io(io)
+        from_datastream(ChunkyPNG::Datastream.from_io(io))
+      end
+
+      def from_datastream(ds)
+        raise "Only 8-bit color depth is currently supported by ChunkyPNG!" unless ds.header_chunk.depth == 8
+
+        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)
+        stream     = ChunkyPNG::Chunk::ImageData.combine_chunks(ds.data_chunks)
+        decode_png_pixelstream(stream, width, height, color_mode, palette, interlace)
+      end
+
+      def decode_png_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    = Color.bytesize(color_mode)
+        pixel_decoder = case color_mode
+          when ChunkyPNG::COLOR_TRUECOLOR       then lambda { |bytes| ChunkyPNG::Color.rgb(*bytes) }
+          when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then lambda { |bytes| ChunkyPNG::Color.rgba(*bytes) }
+          when ChunkyPNG::COLOR_INDEXED         then lambda { |bytes| palette[bytes.first] }
+          when ChunkyPNG::COLOR_GRAYSCALE       then lambda { |bytes| ChunkyPNG::Color.grayscale(*bytes) }
+          when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then lambda { |bytes| ChunkyPNG::Color.grayscale(*bytes) }
+          else raise "No suitable pixel decoder found for color mode #{color_mode}!"
+        end
+
+        return case interlace
+          when ChunkyPNG::INTERLACING_NONE  then decode_png_without_interlacing(stream, width, height, pixel_size, pixel_decoder)
+          when ChunkyPNG::INTERLACING_ADAM7 then decode_png_with_adam7_interlacing(stream, width, height, pixel_size, pixel_decoder)
+          else raise "Don't know how the handle interlacing method #{interlace}!"
+        end
+      end
+
+      protected
+
+      def decode_png_image_pass(stream, width, height, pixel_size, pixel_decoder, start_pos = 0)
+        pixels = []
+
+        if width > 0
+          decoded_bytes = Array.new(width * pixel_size, 0)
+          height.times do |line_no|
+
+            # 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_png_scanline(filter, bytes, decoded_bytes, pixel_size)
+
+            # decode bytes into colors
+            decoded_bytes.each_slice(pixel_size) { |bytes| pixels << pixel_decoder.call(bytes) }
+          end
+        end
+        
+        new(width, height, pixels)
+      end
+
+      def decode_png_without_interlacing(stream, width, height, pixel_size, pixel_decoder)
+        raise "Invalid stream length!" unless stream.length == width * height * pixel_size + height
+        decode_png_image_pass(stream, width, height, pixel_size, pixel_decoder)
+      end
+
+      def decode_png_with_adam7_interlacing(stream, width, height, pixel_size, pixel_decoder)
+        start_pos = 0
+        canvas = ChunkyPNG::Canvas.new(width, height)
+        0.upto(6) do |pass|
+          sm_width, sm_height = adam7_pass_size(pass, width, height)
+          sm = decode_png_image_pass(stream, sm_width, sm_height, pixel_size, pixel_decoder, start_pos)
+          adam7_merge_pass(pass, canvas, sm)
+          start_pos += (sm_width * sm_height * pixel_size) + sm_height
+        end
+        canvas
+      end
+
+      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)
+        when ChunkyPNG::FILTER_SUB     then decode_png_scanline_sub(     bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_UP      then decode_png_scanline_up(      bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_AVERAGE then decode_png_scanline_average( bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_PAETH   then decode_png_scanline_paeth(   bytes, previous_bytes, pixelsize)
+        else raise "Unknown filter type"
+        end
+      end
+
+      def decode_png_scanline_none(bytes, previous_bytes, pixelsize = 3)
+        bytes
+      end
+
+      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
+
+      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
+
+      def decode_png_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_png_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/canvas/png_encoding.rb

@@ -0,0 +1,182 @@
+module ChunkyPNG
+  class Canvas
+    
+    # Methods for encoding a Canvas into a PNG datastream
+    #
+    module PNGEncoding
+
+      def write(io, constraints = {})
+        to_datastream(constraints).write(io)
+      end
+
+      def save(filename, constraints = {})
+        File.open(filename, 'wb') { |io| write(io, constraints) }
+      end
+      
+      def to_blob(constraints = {})
+        to_datastream(constraints).to_blob
+      end
+      
+      alias :to_string :to_blob
+      alias :to_s :to_blob
+
+      # 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.
+      def to_datastream(constraints = {})
+        data = encode_png(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
+        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[:palette], encoding[:interlace])
+        return result
+      end
+
+      def determine_png_encoding(constraints = {})
+        encoding = constraints
+        encoding[:palette]    ||= palette
+        encoding[:color_mode] ||= encoding[:palette].best_colormode
+        
+        encoding[:interlace] = case encoding[:interlace]
+          when nil, false, ChunkyPNG::INTERLACING_NONE then ChunkyPNG::INTERLACING_NONE
+          when true, ChunkyPNG::INTERLACING_ADAM7      then ChunkyPNG::INTERLACING_ADAM7
+          else encoding[:interlace]
+        end
+
+        return encoding
+      end
+      
+      def encode_png_pixelstream(color_mode = ChunkyPNG::COLOR_TRUECOLOR, palette = nil, interlace = ChunkyPNG::INTERLACING_NONE)
+
+        if color_mode == ChunkyPNG::COLOR_INDEXED && !palette.can_encode?
+          raise "This palette is not suitable for encoding!"
+        end
+
+        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| [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
+
+        case interlace
+          when ChunkyPNG::INTERLACING_NONE  then encode_png_image_without_interlacing(pixel_size, pixel_encoder)
+          when ChunkyPNG::INTERLACING_ADAM7 then encode_png_image_with_interlacing(pixel_size, pixel_encoder)
+          else raise "Unknown interlacing method!"
+        end
+      end
+
+      def encode_png_image_without_interlacing(pixel_size, pixel_encoder)
+        stream = ""
+        encode_png_image_pass_to_stream(stream, pixel_size, pixel_encoder)
+        stream
+      end
+      
+      def encode_png_image_with_interlacing(pixel_size, pixel_encoder)
+        stream = ""
+        0.upto(6) do |pass|
+          subcanvas = self.class.adam7_extract_pass(pass, self)
+          subcanvas.encode_png_image_pass_to_stream(stream, pixel_size, pixel_encoder)
+        end
+        stream
+      end
+      
+      def encode_png_image_pass_to_stream(stream, pixel_size, pixel_encoder)
+        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
+
+      # Passes to this canvas of pixel values line by line.
+      # @yield [Array<Fixnum>] An line of fixnums reprsenting pixels
+      def each_scanline(&block)
+        height.times do |i|
+          scanline = pixels[width * i, width]
+          yield(scanline)
+        end
+      end
+
+      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)
+        when ChunkyPNG::FILTER_SUB     then encode_png_scanline_sub(     bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_UP      then encode_png_scanline_up(      bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_AVERAGE then encode_png_scanline_average( bytes, previous_bytes, pixelsize)
+        when ChunkyPNG::FILTER_PAETH   then encode_png_scanline_paeth(   bytes, previous_bytes, pixelsize)
+        else raise "Unknown filter type"
+        end
+      end
+
+      def encode_png_scanline_none(original_bytes, previous_bytes = nil, pixelsize = 3)
+        [ChunkyPNG::FILTER_NONE] + original_bytes
+      end
+
+      def encode_png_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_png_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
+      
+      def encode_png_scanline_average(original_bytes, previous_bytes, pixelsize = 3)
+        encoded_bytes = []
+        original_bytes.length.times do |index|
+          a = (index >= pixelsize) ? original_bytes[index - pixelsize] : 0
+          b = previous_bytes[index]
+          encoded_bytes[index] = (original_bytes[index] - (a + b / 2).floor) % 256
+        end
+        [ChunkyPNG::FILTER_AVERAGE] + encoded_bytes
+      end
+      
+      def encode_png_scanline_paeth(original_bytes, previous_bytes, pixelsize = 3)
+        encoded_bytes = []
+        original_bytes.length.times do |i|
+          a = (i >= pixelsize) ? original_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)
+          encoded_bytes[i] = (original_bytes[i] - pr) % 256
+        end
+        [ChunkyPNG::FILTER_PAETH] + encoded_bytes
+      end
+    end
+  end
+end

data/lib/chunky_png/chunk.rb

@@ -1,52 +1,77 @@
 module ChunkyPNG
-  class Chunk
-    
+  
+  # A PNG datastream consists of multiple chunks. This module, and the classes
+  # contained within, help with handling these chunks. It supports both
+  # reading and writing chunks.
+  #
+  # All chunck types are instances of the {ChunkyPNG::Chunk::Base} class. For
+  # some chunk types a specialized class is available, e.g. the IHDR chunk is
+  # represented by the {ChunkyPNG::Chunk::Header} class. These specialized
+  # classes help accessing the content of the chunk. All other chunks are
+  # represented by the {ChunkyPNG::Chunk::Generic} class.
+  module Chunk
+
+    # Reads a chunk from an IO stream.
+    #
+    # @param [IO, #read] io The IO stream to read from.
+    # @return [ChunkyPNG::Chung::Base] The loaded chunk instance.
     def self.read(io)
 
       length, type = io.read(8).unpack('Na4')
       content      = io.read(length)
       crc          = io.read(4).unpack('N').first
-      
-      # verify_crc!(type, content, crc)
-      
+
+      verify_crc!(type, content, crc)
+
       CHUNK_TYPES.fetch(type, Generic).read(type, content)
     end
     
+    # Verifies the CRC of a chunk.
+    # @param [String] type The chunk's type.
+    # @param [String] content The chunk's content.
+    # @param [Fixnum] content The chunk's content.
+    # @raise [RuntimeError] An exception is raised if the found CRC value
+    #    is not equal to the expected CRC value.
+    def self.verify_crc!(type, content, found_crc)
+      expected_crc = Zlib.crc32(content, Zlib.crc32(type))
+      raise "Chuck CRC mismatch!" if found_crc != expected_crc
+    end
+
     class Base
       attr_accessor :type
-      
+
       def initialize(type, attributes = {})
         self.type = type
         attributes.each { |k, v| send("#{k}=", v) }
       end
-      
+
       def write_with_crc(io, content)
         io << [content.length].pack('N') << type << content
         io << [Zlib.crc32(content, Zlib.crc32(type))].pack('N')
       end
-      
+
       def write(io)
         write_with_crc(io, content || '')
       end
     end
-    
+
     class Generic < Base
-      
+
       attr_accessor :content
-      
+
       def initialize(type, content = '')
         super(type, :content => content)
       end
-      
+
       def self.read(type, content)
         self.new(type, content)
       end
     end
-    
+
     class Header < Base
-      
+
       attr_accessor :width, :height, :depth, :color, :compression, :filtering, :interlace
-      
+
       def initialize(attrs = {})
         super('IHDR', attrs)
         @depth       ||= 8
@@ -55,7 +80,7 @@ module ChunkyPNG
         @filtering   ||= ChunkyPNG::FILTERING_DEFAULT
         @interlace   ||= ChunkyPNG::INTERLACING_NONE
       end
-      
+
       def self.read(type, content)
         fields = content.unpack('NNC5')
         self.new(:width => fields[0],  :height => fields[1], :depth => fields[2], :color => fields[3],
@@ -66,17 +91,17 @@ module ChunkyPNG
         [width, height, depth, color, compression, filtering, interlace].pack('NNC5')
       end
     end
-    
+
     class End < Base
       def initialize
         super('IEND')
       end
-      
+
       def self.read(type, content)
         raise 'The IEND chunk should be empty!' if content != ''
         self.new
       end
-      
+
       def content
         ''
       end
@@ -84,18 +109,71 @@ module ChunkyPNG
 
     class Palette < Generic
     end
-    
+
     class Transparency < Generic
     end
 
     class ImageData < Generic
+      
+      def self.combine_chunks(data_chunks)
+        Zlib::Inflate.inflate(data_chunks.map(&:content).join(''))
+      end
+      
+      def self.split_in_chunks(data, chunk_size = 2147483647)
+        streamdata = Zlib::Deflate.deflate(data)
+        # TODO: Split long streamdata over multiple chunks
+        [ ChunkyPNG::Chunk::ImageData.new('IDAT', streamdata) ]
+      end
     end
-    
+
+    class Text < Base
+
+      attr_accessor :keyword, :value
+
+      def initialize(keyword, value)
+        super('tEXt')
+        @keyword, @value = keyword, value
+      end
+
+      def self.read(type, content)
+        keyword, value = content.unpack('Z*a*')
+        new(keyword, value)
+      end
+
+      def content
+        [keyword, value].pack('Z*a*')
+      end
+    end
+
+    class CompressedText < Base
+
+      attr_accessor :keyword, :value
+
+      def initialize(keyword, value)
+        super('tEXt')
+        @keyword, @value = keyword, value
+      end
+
+      def self.read(type, content)
+        keyword, compression, value = content.unpack('Z*Ca*')
+        raise "Compression method #{compression.inspect} not supported!" unless compression == ChunkyPNG::COMPRESSION_DEFAULT
+        new(keyword, Zlib::Inflate.inflate(value))
+      end
+
+      def content
+        [keyword, ChunkyPNG::COMPRESSION_DEFAULT, Zlib::Deflate.deflate(value)].pack('Z*Ca*')
+      end
+    end
+
+    class InternationalText < Generic
+      # TODO
+    end
+
     # Maps chunk types to classes.
     # If a chunk type is not given in this hash, a generic chunk type will be used.
     CHUNK_TYPES = {
-      'IHDR' => Header, 'IEND' => End, 'IDAT' => ImageData, 'PLTE' => Palette, 'tRNS' => Transparency
+      'IHDR' => Header, 'IEND' => End, 'IDAT' => ImageData, 'PLTE' => Palette, 'tRNS' => Transparency,
+      'tEXt' => Text, 'zTXt' => CompressedText, 'iTXt' => InternationalText
     }
-    
   end
 end