Class ChunkyPNG::Datastream
In: lib/chunky_png/datastream.rb
Parent: Object

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 than contains multiple chunks, starting with a header (IHDR) chunk and finishing with an end (IEND) chunk.

@see ChunkyPNG::Chunk

Methods

Constants

SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10].pack('C8')   The signature that each PNG file or stream should begin with.

External Aliases

from_blob -> from_string

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]
transparency_chunk  [RW]  The chunk containing the transparency information of the palette. @return [ChunkyPNG::Chunk::Transparency]

Public Class methods

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

[Source]

     # File lib/chunky_png/datastream.rb, line 157
157:     def self.empty_bytearray
158:       ChunkyPNG::EMPTY_BYTEARRAY.dup
159:     end

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

[Source]

    # File lib/chunky_png/datastream.rb, line 55
55:       def from_blob(str)
56:         from_io(StringIO.new(str))
57:       end

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.

[Source]

    # File lib/chunky_png/datastream.rb, line 64
64:       def from_file(filename)
65:         ds = nil
66:         File.open(filename, 'rb') { |f| ds = from_io(f) }
67:         ds
68:       end

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

[Source]

    # File lib/chunky_png/datastream.rb, line 73
73:       def from_io(io)
74:         verify_signature!(io)
75: 
76:         ds = self.new
77:         until io.eof?
78:           chunk = ChunkyPNG::Chunk.read(io)
79:           case chunk
80:             when ChunkyPNG::Chunk::Header;       ds.header_chunk = chunk
81:             when ChunkyPNG::Chunk::Palette;      ds.palette_chunk = chunk
82:             when ChunkyPNG::Chunk::Transparency; ds.transparency_chunk = chunk
83:             when ChunkyPNG::Chunk::ImageData;    ds.data_chunks << chunk
84:             when ChunkyPNG::Chunk::End;          ds.end_chunk = chunk
85:             else ds.other_chunks << chunk
86:           end
87:         end
88:         return ds
89:       end

Initializes a new Datastream instance.

[Source]

    # File lib/chunky_png/datastream.rb, line 41
41:     def initialize
42:       @other_chunks = []
43:       @data_chunks  = []
44:     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.

@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.

[Source]

     # File lib/chunky_png/datastream.rb, line 99
 99:       def verify_signature!(io)
100:         signature = io.read(ChunkyPNG::Datastream::SIGNATURE.length)
101:         unless signature == ChunkyPNG::Datastream::SIGNATURE
102:           raise ChunkyPNG::SignatureMismatch, "PNG signature not found!"
103:         end
104:       end

Public Instance methods

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

[Source]

     # File lib/chunky_png/datastream.rb, line 131
131:     def chunks
132:       enum_for(:each_chunk)
133:     end

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

[Source]

     # File lib/chunky_png/datastream.rb, line 119
119:     def each_chunk
120:       yield(header_chunk)
121:       other_chunks.each { |chunk| yield(chunk) }
122:       yield(palette_chunk)      if palette_chunk
123:       yield(transparency_chunk) if transparency_chunk
124:       data_chunks.each  { |chunk| yield(chunk) }
125:       yield(end_chunk)
126:     end

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

[Source]

     # File lib/chunky_png/datastream.rb, line 147
147:     def imagedata
148:       ChunkyPNG::Chunk::ImageData.combine_chunks(data_chunks)
149:     end

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

[Source]

     # File lib/chunky_png/datastream.rb, line 137
137:     def metadata
138:       metadata = {}
139:       other_chunks.select do |chunk|
140:         metadata[chunk.keyword] = chunk.value if chunk.respond_to?(:keyword)
141:       end
142:       metadata
143:     end

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

[Source]

     # File lib/chunky_png/datastream.rb, line 170
170:     def save(filename)
171:       File.open(filename, 'wb') { |f| write(f) }
172:     end

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

[Source]

     # File lib/chunky_png/datastream.rb, line 176
176:     def to_blob
177:       str = StringIO.new
178:       write(str)
179:       return str.string
180:     end
to_s()

Alias for to_blob

to_string()

Alias for to_blob

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

[Source]

     # File lib/chunky_png/datastream.rb, line 163
163:     def write(io)
164:       io << SIGNATURE
165:       each_chunk { |c| c.write(io) }
166:     end

[Validate]