class ChunkyPNG::Datastream

The Datastream class represents a PNG formatted datastream. It supports both reading from and writing to strings, streams and files.

A PNG datastream begins with the PNG signature, and then contains multiple chunks, starting with a header (IHDR) chunk and finishing with an end (IEND) chunk.

@see ChunkyPNG::Chunk

Constants

SIGNATURE

The signature that each PNG file or stream should begin with.

Attributes

data_chunks[RW]

The chunks that together compose the images pixel data. @return [Array<ChunkyPNG::Chunk::ImageData>]

end_chunk[RW]

The empty chunk that signals the end of this datastream @return [ChunkyPNG::Chunk::Header]

header_chunk[RW]

The header chunk of this datastream. @return [ChunkyPNG::Chunk::Header]

other_chunks[RW]

All other chunks in this PNG file. @return [Array<ChunkyPNG::Chunk::Generic>]

palette_chunk[RW]

The chunk containing the image's palette. @return [ChunkyPNG::Chunk::Palette]

physical_chunk[RW]

The chunk containing the physical dimensions of the PNG's pixels. @return [ChunkyPNG::Chunk::Physical]

transparency_chunk[RW]

The chunk containing the transparency information of the palette. @return [ChunkyPNG::Chunk::Transparency]

Public Class Methods

empty_bytearray() click to toggle source

Returns an empty stream using binary encoding that can be used as stream to encode to. @return [String] An empty, binary string.

    # File lib/chunky_png/datastream.rb
161 def self.empty_bytearray
162   ChunkyPNG::EMPTY_BYTEARRAY.dup
163 end
from_blob(str) click to toggle source

Reads a PNG datastream from a string. @param [String] str The PNG encoded string to load from. @return [ChunkyPNG::Datastream] The loaded datastream instance.

   # File lib/chunky_png/datastream.rb
56 def from_blob(str)
57   from_io(StringIO.new(str, "rb"))
58 end
Also aliased as: from_string
from_file(filename) click to toggle source

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.

   # File lib/chunky_png/datastream.rb
65 def from_file(filename)
66   ds = nil
67   File.open(filename, "rb") { |f| ds = from_io(f) }
68   ds
69 end
from_io(io) click to toggle source

Reads a PNG datastream from an input stream @param [IO] io The stream to read from. @return [ChunkyPNG::Datastream] The loaded datastream instance.

   # File lib/chunky_png/datastream.rb
74 def from_io(io)
75   io.set_encoding(Encoding::BINARY)
76   verify_signature!(io)
77 
78   ds = new
79   while ds.end_chunk.nil?
80     chunk = ChunkyPNG::Chunk.read(io)
81     case chunk
82       when ChunkyPNG::Chunk::Header       then ds.header_chunk = chunk
83       when ChunkyPNG::Chunk::Palette      then ds.palette_chunk = chunk
84       when ChunkyPNG::Chunk::Transparency then ds.transparency_chunk = chunk
85       when ChunkyPNG::Chunk::ImageData    then ds.data_chunks << chunk
86       when ChunkyPNG::Chunk::Physical     then ds.physical_chunk = chunk
87       when ChunkyPNG::Chunk::End          then ds.end_chunk = chunk
88       else ds.other_chunks << chunk
89     end
90   end
91   ds
92 end
from_string(str)
Alias for: from_blob
new() click to toggle source

Initializes a new Datastream instance.

   # File lib/chunky_png/datastream.rb
43 def initialize
44   @other_chunks = []
45   @data_chunks  = []
46 end
verify_signature!(io) click to toggle source

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.

@param [IO] io The stream to read the PNG signature from. @raise [RuntimeError] An exception is raised if the PNG signature is not found at

the beginning of the stream.
    # File lib/chunky_png/datastream.rb
102 def verify_signature!(io)
103   signature = io.read(ChunkyPNG::Datastream::SIGNATURE.length)
104   unless signature == ChunkyPNG::Datastream::SIGNATURE
105     raise ChunkyPNG::SignatureMismatch, "PNG signature not found, found #{signature.inspect} instead of #{ChunkyPNG::Datastream::SIGNATURE.inspect}!"
106   end
107 end

Public Instance Methods

chunks() click to toggle source

Returns an enumerator instance for this datastream's chunks. @return [Enumerable::Enumerator] An enumerator for the :each_chunk method. @see ChunkyPNG::Datastream#each_chunk

    # File lib/chunky_png/datastream.rb
135 def chunks
136   enum_for(:each_chunk)
137 end
each_chunk() { |header_chunk| ... } click to toggle source

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 [chunk] Yields the chunks in this datastream, one by one in the correct order. @yieldparam [ChunkyPNG::Chunk::Base] chunk A chunk in this datastream. @see ChunkyPNG::Datastream#chunks

    # File lib/chunky_png/datastream.rb
122 def each_chunk
123   yield(header_chunk)
124   other_chunks.each { |chunk| yield(chunk) }
125   yield(palette_chunk)      if palette_chunk
126   yield(transparency_chunk) if transparency_chunk
127   yield(physical_chunk)     if physical_chunk
128   data_chunks.each { |chunk| yield(chunk) }
129   yield(end_chunk)
130 end
imagedata() click to toggle source

Returns the uncompressed image data, combined from all the IDAT chunks @return [String] The uncompressed image data for this datastream

    # File lib/chunky_png/datastream.rb
151 def imagedata
152   ChunkyPNG::Chunk::ImageData.combine_chunks(data_chunks)
153 end
metadata() click to toggle source

Returns all the textual metadata key/value pairs as hash. @return [Hash] A hash containing metadata fields and their values.

    # File lib/chunky_png/datastream.rb
141 def metadata
142   metadata = {}
143   other_chunks.each do |chunk|
144     metadata[chunk.keyword] = chunk.value if chunk.respond_to?(:keyword) && chunk.respond_to?(:value)
145   end
146   metadata
147 end
save(filename) click to toggle source

Saves this datastream as a PNG file. @param [String] filename The filename to use.

    # File lib/chunky_png/datastream.rb
174 def save(filename)
175   File.open(filename, "wb") { |f| write(f) }
176 end
to_blob() click to toggle source

Encodes this datastream into a string. @return [String] The encoded PNG datastream.

    # File lib/chunky_png/datastream.rb
180 def to_blob
181   str = StringIO.new
182   str.set_encoding("ASCII-8BIT")
183   write(str)
184   str.string
185 end
Also aliased as: to_string, to_s
to_s()
Alias for: to_blob
to_string()
Alias for: to_blob
write(io) click to toggle source

Writes the datastream to the given output stream. @param [IO] io The output stream to write to.

    # File lib/chunky_png/datastream.rb
167 def write(io)
168   io << SIGNATURE
169   each_chunk { |c| c.write(io) }
170 end