chunky_png 0.0.5 → 0.5.0

data/lib/chunky_png/color.rb

@@ -0,0 +1,307 @@
+module ChunkyPNG
+
+  # The Color module defines methods for handling colors. Within the ChunkyPNG
+  # library, the concepts of pixels and colors are both used, and they are
+  # both represented by a Fixnum.
+  #
+  # Pixels/colors are represented in RGBA componetns. Each of the four
+  # components is stored with a depth of 8 bits (maximum value = 255 =
+  # {ChunkyPNG::Color::MAX}). Together, these components are stored in a 4-byte
+  # Fixnum.
+  #
+  # A color will always be represented using these 4 components in memory.
+  # When the image is encoded, a more suitable representation can be used
+  # (e.g. rgb, grayscale, palette-based), for which several conversion methods
+  # are provided in this module.
+  module Color
+    extend self
+
+    # The maximum value of each color component.
+    MAX = 0xff
+
+    ####################################################################
+    # CONSTRUCTING COLOR VALUES
+    ####################################################################
+
+    # Creates a new color using an r, g, b triple and an alpha value.
+    # @return [Fixnum] The newly constructed color value.
+    def rgba(r, g, b, a)
+      r << 24 | g << 16 | b << 8 | a
+    end
+
+    # Creates a new color using an r, g, b triple.
+    # @return [Fixnum] The newly constructed color value.
+    def rgb(r, g, b, a = MAX)
+      rgba(r, g, b, a)
+    end
+
+    # Creates a new color using a grayscale teint.
+    # @return [ChunkyPNG::Color] The newly constructed color value.
+    def grayscale(teint, a = MAX)
+      rgba(teint, teint, teint, a)
+    end
+
+    # Creates a new color using a grayscale teint and alpha value.
+    # @return [Fixnum] The newly constructed color value.
+    def grayscale_alpha(teint, a)
+      rgba(teint, teint, teint, a)
+    end
+    
+    ####################################################################
+    # COLOR IMPORTING
+    ####################################################################
+
+    # Creates a color by unpacking an rgb triple from a string.
+    #
+    # @param [String] stream The string to load the color from. It should be 
+    #     at least 3 + pos bytes long.
+    # @param [Fixnum] pos The position in the string to load the triple from.
+    # @return [Fixnum] The newly constructed color value.
+    def from_rgb_stream(stream, pos = 0)
+      rgb(*stream.unpack("@#{pos}C3"))
+    end
+
+    # Creates a color by unpacking an rgba triple from a string
+    #
+    # @param [String] stream The string to load the color from. It should be 
+    #      at least 4 + pos bytes long.
+    # @param [Fixnum] pos The position in the string to load the triple from.
+    # @return [Fixnum] The newly constructed color value.
+    def from_rgba_stream(stream, pos = 0)
+      rgba(*stream.unpack("@#{pos}C4"))
+    end
+    
+    # Creates a color by converting it from a string in hex notation. 
+    #
+    # It supports colors with (#rrggbbaa) or without (#rrggbb) alpha channel.
+    # Color strings may include the prefix "0x" or "#".
+    #
+    # @param [String] str The color in hex notation. @return [Fixnum] The
+    # converted color value.
+    def from_hex(str)
+      case str
+        when /^(?:#|0x)?([0-9a-f]{6})$/i then ($1.hex << 8) | 0xff
+        when /^(?:#|0x)?([0-9a-f]{8})$/i then $1.hex
+        else raise "Not a valid hex color notation: #{str.inspect}!"
+      end
+    end
+
+    ####################################################################
+    # PROPERTIES
+    ####################################################################
+
+    # Returns the red-component from the color value.
+    #
+    # @param [Fixnum] value The color value.
+    # @return [Fixnum] A value between 0 and MAX.
+    def r(value)
+      (value & 0xff000000) >> 24
+    end
+    
+    # Returns the green-component from the color value.
+    #
+    # @param [Fixnum] value The color value.
+    # @return [Fixnum] A value between 0 and MAX.
+    def g(value)
+      (value & 0x00ff0000) >> 16
+    end
+    
+    # Returns the blue-component from the color value.
+    #
+    # @param [Fixnum] value The color value.
+    # @return [Fixnum] A value between 0 and MAX.
+    def b(value)
+      (value & 0x0000ff00) >> 8
+    end
+    
+    # Returns the alpha channel value for the color value.
+    #
+    # @param [Fixnum] value The color value.
+    # @return [Fixnum] A value between 0 and MAX.
+    def a(value)
+      value & 0x000000ff
+    end
+    
+    # Returns true if this color is fully opaque.
+    #
+    # @param [Fixnum] value The color to test.
+    # @return [true, false] True if the alpha channel equals MAX.
+    def opaque?(value)
+      a(value) == 0x000000ff
+    end
+    
+    # Returns true if this color is fully transparent.
+    #
+    # @param [Fixnum] value The color to test.
+    # @return [true, false] True if the r, g and b component are equal.
+    def grayscale?(value)
+      r(value) == b(value) && b(value) == g(value)
+    end
+    
+    # Returns true if this color is fully transparent.
+    #
+    # @param [Fixnum] value The color to test.
+    # @return [true, false] True if the alpha channel equals 0.
+    def fully_transparent?(value)
+      a(value) == 0x00000000
+    end
+
+    ####################################################################
+    # ALPHA COMPOSITION
+    ####################################################################
+
+    # Multiplies two fractions using integer math, where the fractions are stored using an
+    # integer between 0 and 255. This method is used as a helper method for compositing
+    # colors using integer math.
+    #
+    # This is a quicker implementation of ((a * b) / 255.0).round.
+    #
+    # @param [Fixnum] a The first fraction.
+    # @param [Fixnum] b The second fraction.
+    # @return [Fixnum] The result of the multiplication.
+    def int8_mult(a, b)
+      t = a * b + 0x80
+      ((t >> 8) + t) >> 8
+    end
+
+    # Composes two colors with an alpha channel using integer math.
+    #
+    # This version is faster than the version based on floating point math, so this
+    # compositing function is used by default.
+    #
+    # @param [Fixnum] fg The foreground color.
+    # @param [Fixnum] bg The foreground color.
+    # @return [Fixnum] The composited color.
+    # @see ChunkyPNG::Color#compose_precise
+    def compose_quick(fg, bg)
+      return fg if opaque?(fg)
+      return bg if fully_transparent?(fg)
+      
+      a_com = int8_mult(0xff - a(fg), a(bg))
+      new_r = int8_mult(a(fg), r(fg)) + int8_mult(a_com, r(bg))
+      new_g = int8_mult(a(fg), g(fg)) + int8_mult(a_com, g(bg))
+      new_b = int8_mult(a(fg), b(fg)) + int8_mult(a_com, b(bg))
+      new_a = a(fg) + a_com
+      rgba(new_r, new_g, new_b, new_a)
+    end
+
+    # Composes two colors with an alpha channel using floating point math.
+    #
+    # This method uses more precise floating point math, but this precision is lost
+    # when the result is converted back to an integer. Because it is slower than
+    # the version based on integer math, that version is preferred.
+    #
+    # @param [Fixnum] fg The foreground color.
+    # @param [Fixnum] bg The foreground color.
+    # @return [Fixnum] The composited color.
+    # @see ChunkyPNG::Color#compose_quick
+    def compose_precise(fg, bg)
+      return fg if opaque?(fg)
+      return bg if fully_transparent?(fg)
+      
+      fg_a  = a(fg).to_f / MAX
+      bg_a  = a(bg).to_f / MAX
+      a_com = (1.0 - fg_a) * bg_a
+
+      new_r = (fg_a * r(fg) + a_com * r(bg)).round
+      new_g = (fg_a * g(fg) + a_com * g(bg)).round
+      new_b = (fg_a * b(fg) + a_com * b(bg)).round
+      new_a = ((fg_a + a_com) * MAX).round
+      rgba(new_r, new_g, new_b, new_a)
+    end
+
+    alias :compose :compose_quick
+    
+    # Blends the foreground and background color by taking the average of 
+    # the components.
+    #
+    # @param [Fixnum] fg The foreground color.
+    # @param [Fixnum] bg The foreground color.
+    # @return [Fixnum] The blended color.
+    def blend(fg, bg)
+      (fg + bg) >> 1
+    end
+
+    ####################################################################
+    # CONVERSIONS
+    ####################################################################
+
+    # Returns a string representing this color using hex notation (i.e. #rrggbbaa).
+    #
+    # @param [Fixnum] value The color to convert.
+    # @return [String] The color in hex notation, starting with a pound sign.
+    def to_hex(color, include_alpha = true)
+      include_alpha ? ('#%08x' % color) : ('#%06x' % [color >> 8])
+    end
+
+    # Returns an array with the separate RGBA values for this color.
+    #
+    # @param [Fixnum] color The color to convert.
+    # @return [Array<Fixnum>] An array with 4 Fixnum elements.
+    def to_truecolor_alpha_bytes(color)
+      [r(color), g(color), b(color), a(color)]
+    end
+
+    # Returns an array with the separate RGB values for this color.
+    # The alpha channel will be discarded.
+    #
+    # @param [Fixnum] color The color to convert.
+    # @return [Array<Fixnum>] An array with 3 Fixnum elements.
+    def to_truecolor_bytes(color)
+      [r(color), g(color), b(color)]
+    end
+
+    # Returns an array with the grayscale teint value for this color.
+    #
+    # This method expects the r,g and b value to be equal, and the alpha 
+    # channel will be discarded.
+    #
+    # @param [Fixnum] color The grayscale color to convert.
+    # @return [Array<Fixnum>] An array with 1 Fixnum element.
+    def to_grayscale_bytes(color)
+      [r(color)] # assumption r == g == b
+    end
+
+    # Returns an array with the grayscale teint and alpha channel values
+    # for this color.
+    #
+    # This method expects the r,g and b value to be equal.
+    #
+    # @param [Fixnum] color The grayscale color to convert.
+    # @return [Array<Fixnum>] An array with 2 Fixnum elements.
+    def to_grayscale_alpha_bytes(color)
+      [r(color), a(color)] # assumption r == g == b
+    end
+
+    ####################################################################
+    # COLOR CONSTANTS
+    ####################################################################
+
+    # Black pixel/color
+    BLACK = rgb(  0,   0,   0)
+
+    # White pixel/color
+    WHITE = rgb(255, 255, 255)
+
+    # Fully transparent pixel/color
+    TRANSPARENT = rgba(255, 255, 255, 0)
+
+    ####################################################################
+    # STATIC UTILITY METHODS
+    ####################################################################
+
+    # Returns the size in bytes of a pixel when it is stored using a given color mode.
+    # @param [Fixnum] color_mode The color mode in which the pixels are stored.
+    # @return [Fixnum] The number of bytes used per pixel in a datastream.
+    def bytesize(color_mode)
+      case color_mode
+        when ChunkyPNG::COLOR_INDEXED         then 1
+        when ChunkyPNG::COLOR_TRUECOLOR       then 3
+        when ChunkyPNG::COLOR_TRUECOLOR_ALPHA then 4
+        when ChunkyPNG::COLOR_GRAYSCALE       then 1
+        when ChunkyPNG::COLOR_GRAYSCALE_ALPHA then 2
+        else raise "Don't know the bytesize of pixels in this colormode: #{color_mode}!"
+      end
+    end
+  end
+end

data/lib/chunky_png/datastream.rb

@@ -1,71 +1,169 @@
 module ChunkyPNG
-  
+
+  # The Datastream class represents a PNG formatted datastream. It supports
+  # both reading from and writing to strings, stremas and files.
+  #
+  # A PNG datastream begins with the PNG signature, and than contains multiple
+  # chunks, starting with a header (IHDR) chunk and finishing with an end
+  # (IEND) chunk.
+  #
+  # @see ChunkyPNG::Chunk
   class Datastream
-    
+
+    # The signature that each PNG file or stream should begin with.
     SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10].pack('C8')
-    
+
+    # The header chunk of this datastream.
+    # @return [ChunkyPNG::Chunk::Header]
     attr_accessor :header_chunk
+
+    # All other chunks in this PNG file.
+    # @return [Array<ChunkyPNG::Chunk::Generic>]
     attr_accessor :other_chunks
+
+    # The chunk containing the image's palette.
+    # @return [ChunkyPNG::Chunk::Palette]
     attr_accessor :palette_chunk
+
+    # The chunk containing the transparency information of the palette.
+    # @return [ChunkyPNG::Chunk::Transparency]
     attr_accessor :transparency_chunk
+
+    # The chunks that together compose the images pixel data.
+    # @return [Array<ChunkyPNG::Chunk::ImageData>]
     attr_accessor :data_chunks
+
+    # The empty chunk that signals the end of this datastream
+    # @return [ChunkyPNG::Chunk::Header]
     attr_accessor :end_chunk
 
-    def self.read(io)
-      verify_signature!(io)
-
-      ds = self.new
-      until io.eof?
-        chunk = ChunkyPNG::Chunk.read(io)
-        case chunk
-          when ChunkyPNG::Chunk::Header       then ds.header_chunk        = chunk
-          when ChunkyPNG::Chunk::Palette      then ds.palette_chunk       = chunk
-          when ChunkyPNG::Chunk::Transparency then ds.transparency_chunk  = chunk
-          when ChunkyPNG::Chunk::ImageData    then ds.data_chunks        << chunk
-          when ChunkyPNG::Chunk::End          then ds.end_chunk           = chunk
-          else ds.other_chunks << chunk
+
+    # Initializes a new Datastream instance.
+    def initialize
+      @other_chunks = []
+      @data_chunks  = []
+    end
+
+    #############################################
+    # LOADING DATASTREAMS
+    #############################################
+
+    class << self
+
+      # Reads a PNG datastream from a string.
+      # @param [String] str The PNG encoded string to load from.
+      # @return [ChunkyPNG::Datastream] The loaded datastream instance.
+      def from_blob(str)
+        from_io(StringIO.new(str))
+      end
+
+      alias :from_string :from_blob
+
+      # Reads a PNG datastream from a file.
+      # @param [String] filename The path of the file to load from.
+      # @return [ChunkyPNG::Datastream] The loaded datastream instance.
+      def from_file(filename)
+        ds = nil
+        File.open(filename, 'rb') { |f| ds = from_io(f) }
+        ds
+      end
+
+      # Reads a PNG datastream from an input stream
+      # @param [IO] io The stream to read from.
+      # @return [ChunkyPNG::Datastream] The loaded datastream instance.
+      def from_io(io)
+        verify_signature!(io)
+
+        ds = self.new
+        until io.eof?
+          chunk = ChunkyPNG::Chunk.read(io)
+          case chunk
+            when ChunkyPNG::Chunk::Header       then ds.header_chunk        = chunk
+            when ChunkyPNG::Chunk::Palette      then ds.palette_chunk       = chunk
+            when ChunkyPNG::Chunk::Transparency then ds.transparency_chunk  = chunk
+            when ChunkyPNG::Chunk::ImageData    then ds.data_chunks        << chunk
+            when ChunkyPNG::Chunk::End          then ds.end_chunk           = chunk
+            else ds.other_chunks << chunk
+          end
         end
+        return ds
+      end
+
+      # Verifies that the current stream is a PNG datastream by checking its signature.
+      #
+      # This method reads the PNG signature from the stream, setting the current position
+      # of the stream directly after the signature, where the IHDR chunk should begin.
+      #
+      # @raise [RuntimeError] An exception is raised if the PNG signature is not found at
+      #    the beginning of the stream.
+      def verify_signature!(io)
+        signature = io.read(ChunkyPNG::Datastream::SIGNATURE.length)
+        raise "PNG signature not found!" unless signature == ChunkyPNG::Datastream::SIGNATURE
       end
-      return ds
     end
 
-    def self.verify_signature!(io)
-      signature = io.read(ChunkyPNG::Datastream::SIGNATURE.length)
-      raise "PNG signature not found!" unless signature == ChunkyPNG::Datastream::SIGNATURE
+    #############################################
+    # CHUNKS
+    #############################################
+
+    # Enumerates the chunks in this datastream.
+    #
+    # This will iterate over the chunks using the order in which the chunks
+    # should appear in the PNG file.
+    #
+    # @yield [ChunkyPNG::Chunk::Base] The chunks in this datastrean, one by one.
+    # @see ChunkyPNG::Datastream#chunks
+    def each_chunk
+      yield(header_chunk)
+      other_chunks.each { |chunk| yield(chunk) }
+      yield(palette_chunk)      if palette_chunk
+      yield(transparency_chunk) if transparency_chunk
+      data_chunks.each  { |chunk| yield(chunk) }
+      yield(end_chunk)
     end
-    
+
+    # Returns an enumerator instance for this datastream's chunks.
+    # @return [Enumerable::Enumerator] An enumerator for the :each_chunk method.
+    # @see ChunkyPNG::Datastream#each_chunk
     def chunks
-      cs = [header_chunk]
-      cs += other_chunks
-      cs << palette_chunk      if palette_chunk
-      cs << transparency_chunk if transparency_chunk
-      cs += data_chunks
-      cs << end_chunk
-      return cs
+      enum_for(:each_chunk)
     end
     
-    def initialize
-      @other_chunks = []
-      @data_chunks  = []
+    # Returns all the textual metadata key/value pairs as hash.
+    def metadata
+      metadata = {}
+      other_chunks.select do |chunk|
+        metadata[chunk.keyword] = chunk.value if chunk.respond_to?(:keyword)
+      end
+      metadata
     end
-    
+
+    #############################################
+    # WRITING DATASTREAMS
+    #############################################
+
+    # Writes the datastream to the given output stream.
+    # @param [IO] io The output stream to write to.
     def write(io)
       io << SIGNATURE
-      chunks.each { |c| c.write(io) }
-    end
-    
-    def idat_chunks(data)
-      streamdata = Zlib::Deflate.deflate(data)
-      # TODO: Split long streamdata over multiple chunks
-      return [ ChunkyPNG::Chunk::ImageData.new('IDAT', streamdata) ]
+      each_chunk { |c| c.write(io) }
     end
-    
-    def pixel_matrix=(pixel_matrix)
-      @pixel_matrix = pixel_matrix
+
+    # Saves this datastream as a PNG file.
+    # @param [String] filename The filename to use.
+    def save(filename)
+      File.open(filename, 'wb') { |f| write(f) }
     end
-    
-    def pixel_matrix
-      @pixel_matrix ||= ChunkyPNG::PixelMatrix.decode(self)
+
+    # Encodes this datastream into a string.
+    # @return [String] The encoded PNG datastream.
+    def to_blob
+      str = StringIO.new
+      write(str)
+      return str.string
     end
+
+    alias :to_string :to_blob
+    alias :to_s :to_blob
   end
 end