Module: ChunkyPNG::Canvas::PNGEncoding

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

Overview

Methods for encoding a Canvas instance into a PNG datastream.

Overview of the encoding process:

  • The image is split up in scanlines (i.e. rows of pixels);

  • All pixels are encoded as a pixelstream, based on the color mode.

  • All the pixel bytes in the pixelstream are adjusted using a filtering method if one is specified.

  • Compress the resulting string using deflate compression.

  • Split compressed data over one or more PNG chunks.

  • These chunks should be embedded in a datastream with at least a IHDR and IEND chunk and possibly a PLTE chunk.

For interlaced images, the initial image is first split into 7 subimages. These images get encoded exactly as above, and the result gets combined before the compression step.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#encoding_paletteChunkyPNG::Palette

The palette used for encoding the image.This is only in used for images that get encoded using indexed colors.

Returns:



28
29
30
# File 'lib/chunky_png/canvas/png_encoding.rb', line 28

def encoding_palette
  @encoding_palette
end

Instance Method Details

#save(filename, constraints = {})

This method returns an undefined value.

Writes the canvas to a file, encoded as a PNG image.

Parameters:

  • filename (String)

    The file to save the PNG image to.

  • constraints (Hash, Symbol) (defaults to: {})

    The constraints to use when encoding the canvas. This can either be a hash with different constraints, or a symbol which acts as a preset for some constraints. If no constraints are given, ChunkyPNG will decide

    for itself how to best create the PNG datastream. Supported presets are :fast_rgba for quickly saving images with transparency, :fast_rgb for quickly saving opaque images, and :best_compression to obtain the smallest possible filesize.



42
43
44
# File 'lib/chunky_png/canvas/png_encoding.rb', line 42

def save(filename, constraints = {})
  File.open(filename, 'wb') { |io| write(io, constraints) }
end

#to_blob(constraints = {}) ⇒ String Also known as: to_string, to_s

Encoded the canvas to a PNG formatted string.

Parameters:

  • constraints (Hash, Symbol) (defaults to: {})

    The constraints to use when encoding the canvas. This can either be a hash with different constraints, or a symbol which acts as a preset for some constraints. If no constraints are given, ChunkyPNG will decide

    for itself how to best create the PNG datastream. Supported presets are :fast_rgba for quickly saving images with transparency, :fast_rgb for quickly saving opaque images, and :best_compression to obtain the smallest possible filesize.

Returns:

  • (String)

    The PNG encoded canvas as string.



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

def to_blob(constraints = {})
  to_datastream(constraints).to_blob
end

#to_datastream(constraints = {}) ⇒ ChunkyPNG::Datastream

Converts this Canvas to a datastream, so that it can be saved as a PNG image.

Parameters:

  • constraints (Hash, Symbol) (defaults to: {})

    The constraints to use when encoding the canvas. This can either be a hash with different constraints, or a symbol which acts as a preset for some constraints. If no constraints are given, ChunkyPNG will decide

    for itself how to best create the PNG datastream. Supported presets are :fast_rgba for quickly saving images with transparency, :fast_rgb for quickly saving opaque images, and :best_compression to obtain the smallest possible filesize.

Options Hash (constraints):

  • :color_mode (Fixnum)

    The color mode to use. Use one of the ChunkyPNG::COLOR_* constants.

  • :interlace (true, false)

    Whether to use interlacing.

  • :compression (Fixnum)

    The compression level for Zlib. This can be a value between 0 and 9, or a Zlib constant like Zlib::BEST_COMPRESSION.

  • :bit_depth (Fixnum)

    The bit depth to use. This option is only used for indexed images, in which case it overrides the determined minimal bit depth. For all the other color modes, a bit depth of 8 is used.

Returns:

See Also:

  • #determine_png_encoding


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# File 'lib/chunky_png/canvas/png_encoding.rb', line 74

def to_datastream(constraints = {})
  encoding = determine_png_encoding(constraints)

  ds = Datastream.new
  ds.header_chunk = Chunk::Header.new(:width => width, :height => height,
      :color => encoding[:color_mode], :depth => encoding[:bit_depth], :interlace => encoding[:interlace])

  if encoding[:color_mode] == ChunkyPNG::COLOR_INDEXED
    ds.palette_chunk      = encoding_palette.to_plte_chunk
    ds.transparency_chunk = encoding_palette.to_trns_chunk unless encoding_palette.opaque?
  end
  data           = encode_png_pixelstream(encoding[:color_mode], encoding[:bit_depth], encoding[:interlace], encoding[:filtering])
  ds.data_chunks = Chunk::ImageData.split_in_chunks(data, encoding[:compression])
  ds.end_chunk   = Chunk::End.new
  return ds
end

#write(io, constraints = {})

This method returns an undefined value.

Writes the canvas to an IO stream, encoded as a PNG image.

Parameters:

  • io (IO)

    The output stream to write to.

  • constraints (Hash, Symbol) (defaults to: {})

    The constraints to use when encoding the canvas. This can either be a hash with different constraints, or a symbol which acts as a preset for some constraints. If no constraints are given, ChunkyPNG will decide

    for itself how to best create the PNG datastream. Supported presets are :fast_rgba for quickly saving images with transparency, :fast_rgb for quickly saving opaque images, and :best_compression to obtain the smallest possible filesize.



34
35
36
# File 'lib/chunky_png/canvas/png_encoding.rb', line 34

def write(io, constraints = {})
  to_datastream(constraints).write(io)
end