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.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#encoding_palette ⇒ ChunkyPNG::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
90
91
92
93
94
 
# 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
  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