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
The chunks that together compose the images pixel data. @return [Array<ChunkyPNG::Chunk::ImageData>]
The empty chunk that signals the end of this datastream @return [ChunkyPNG::Chunk::Header]
The header chunk of this datastream. @return [ChunkyPNG::Chunk::Header]
All other chunks in this PNG file. @return [Array<ChunkyPNG::Chunk::Generic>]
The chunk containing the image's palette. @return [ChunkyPNG::Chunk::Palette]
The chunk containing the physical dimensions of the PNG's pixels. @return [ChunkyPNG::Chunk::Physical]
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.
# File lib/chunky_png/datastream.rb 161 def self.empty_bytearray 162 ChunkyPNG::EMPTY_BYTEARRAY.dup 163 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.
# File lib/chunky_png/datastream.rb 56 def from_blob(str) 57 from_io(StringIO.new(str, "rb")) 58 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.
# 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
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
Initializes a new Datastream
instance.
# File lib/chunky_png/datastream.rb 43 def initialize 44 @other_chunks = [] 45 @data_chunks = [] 46 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.
# 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
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
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
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
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
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
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
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