Module: ChunkyPNG::Canvas::PNGDecoding

Included in:
ChunkyPNG::Canvas
Defined in:
lib/chunky_png/canvas/png_decoding.rb

Overview

The PNGDecoding contains methods for decoding PNG datastreams to create a Canvas object. The datastream can be provided as filename, string or IO stream.

Overview of the decoding process:

  • The optional PLTE and tRNS chunk are decoded for the color palette of the original image.

  • The contents of the IDAT chunks is combined, and uncompressed using Inflate decompression to the image pixelstream.

  • Based on the color mode, width and height of the original image, which is read from the PNG header (IHDR chunk), the amount of bytes per line is determined.

  • For every line of pixels in the original image, the determined amount of bytes is read from the pixel stream.

  • The read bytes are unfiltered given by the filter function specified by the first byte of the line.

  • The unfiltered bytes are converted into colored pixels, using the color mode.

  • All lines combined form the original image.

For interlaced images, the original image was split into 7 subimages. These images get decoded just like the process above (from step 3), and get combined to form the original images.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#decoding_palette ⇒ ChunkyPNG::Palette

The palette that is used to decode the image, loading from the PLTE and tRNS chunk from the PNG stream. For RGB(A) images, no palette is required.

Returns:



35
36
37
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 35

def decoding_palette
  @decoding_palette
end

Instance Method Details

#decode_png_pixelstream(stream, width, height, color_mode = ChunkyPNG::COLOR_TRUECOLOR, interlace = ChunkyPNG::INTERLACING_NONE) ⇒ ChunkyPNG::Canvas

Decodes a canvas from a PNG encoded pixelstream, using a given width, height, color mode and interlacing mode.

Parameters:

  • stream (String) —

    The pixelstream to read from.

  • width (Integer) —

    The width of the image.

  • width (Integer) —

    The height of the image.

  • color_mode (Integer) (defaults to: ChunkyPNG::COLOR_TRUECOLOR) —

    The color mode of the encoded pixelstream.

  • interlace (Integer) (defaults to: ChunkyPNG::INTERLACING_NONE) —

    The interlace method of the encoded pixelstream.

Returns:



85
86
87
88
89
90
91
92
93
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 85

def decode_png_pixelstream(stream, width, height, color_mode = ChunkyPNG::COLOR_TRUECOLOR, interlace = ChunkyPNG::INTERLACING_NONE)
  raise "This palette is not suitable for decoding!" if decoding_palette && !decoding_palette.can_decode?

  return case interlace
    when ChunkyPNG::INTERLACING_NONE  then decode_png_without_interlacing(stream, width, height, color_mode)
    when ChunkyPNG::INTERLACING_ADAM7 then decode_png_with_adam7_interlacing(stream, width, height, color_mode)
    else raise "Don't know how the handle interlacing method #{interlace}!"
  end
end

#from_blob(str) ⇒ ChunkyPNG::Canvas Also known as: from_string

Decodes a Canvas from a PNG encoded string.

Parameters:

  • str (String) —

    The string to read from.

Returns:



40
41
42
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 40

def from_blob(str)
  from_datastream(ChunkyPNG::Datastream.from_blob(str))
end

#from_datastream(ds) ⇒ ChunkyPNG::Canvas

Decodes the Canvas from a PNG datastream instance.

Parameters:

Returns:



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 63

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

  self.decoding_palette = ChunkyPNG::Palette.from_chunks(ds.palette_chunk, ds.transparency_chunk)
  pixelstream           = ChunkyPNG::Chunk::ImageData.combine_chunks(ds.data_chunks)

  decode_png_pixelstream(pixelstream, width, height, color_mode, interlace)
end

#from_file(filename) ⇒ ChunkyPNG::Canvas

Decodes a Canvas from a PNG encoded file.

Parameters:

  • filename (String) —

    The file to read from.

Returns:



49
50
51
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 49

def from_file(filename)
  from_datastream(ChunkyPNG::Datastream.from_file(filename))
end

#from_io(io) ⇒ ChunkyPNG::Canvas

Decodes a Canvas from a PNG encoded stream.

Parameters:

  • io (IO, #read) —

    The stream to read from.

Returns:



56
57
58
 
# File 'lib/chunky_png/canvas/png_decoding.rb', line 56

def from_io(io)
  from_datastream(ChunkyPNG::Datastream.from_io(io))
end