module ChunkyPNG

ChunkyPNG - the pure ruby library to access PNG files.

The ChunkyPNG module defines some constants that are used in the PNG specification, specifies some exception classes, and serves as a namespace for all the other modules and classes in this library.

{ChunkyPNG::Image}

class to represent PNG images, including metadata.

{ChunkyPNG::Canvas}

class to represent the image’s canvas.

{ChunkyPNG::Color}

module to work with color values.

{ChunkyPNG::Palette}

represents the palette of colors used on a {ChunkyPNG::Canvas}.

{ChunkyPNG::Datastream}

represents the internal structure of a PNG {ChunkyPNG::Image}.

{ChunkyPNG::Color}

represents one chunk of data within a {ChunkyPNG::Datastream}.

{ChunkyPNG::Point}

geometry helper class representing a 2-dimensional point.

{ChunkyPNG::Dimension}

geometry helper class representing a dimension (i.e. width x height).

{ChunkyPNG::Vector}

geometry helper class representing a series of points.

@author Willem van Bergen

Constants

COLOR_GRAYSCALE

Indicates that the PNG image uses grayscale colors, i.e. only a single teint channel. @private

COLOR_GRAYSCALE_ALPHA

Indicates that the PNG image uses grayscale colors with opacity, i.e. a teint channel with an alpha channel. @private

COLOR_INDEXED

Indicates that the PNG image uses indexed colors, where the values point to colors defined on a palette. @private

COLOR_TRUECOLOR

Indicates that the PNG image uses true color, composed of a red green and blue channel. @private

COLOR_TRUECOLOR_ALPHA

Indicates that the PNG image uses true color with opacity, composed of a red, green and blue channel, and an alpha value. @private

COMPRESSED_CONTENT

Indicates that the PNG chunk content is compressed flag used in iTXt chunk @private

COMPRESSION_DEFAULT

Indicates that the PNG specification’s default compression method is used (Zlib/Deflate) @private

EXTRA_BYTE

Null-byte, with the encoding set correctly to ASCII-8BIT (binary) in Ruby 1.9. @return [String] A binary string, consisting of one NULL-byte. @private

FILTERING_DEFAULT

Indicates that the PNG specification’s default filtering are being used in the image. @private

FILTER_AVERAGE

Indicates that AVERAGE filtering is used for the scanline. @private

FILTER_NONE

Indicates that no filtering is used for the scanline. @private

FILTER_PAETH

Indicates that PAETH filtering is used for the scanline. @private

FILTER_SUB

Indicates that SUB filtering is used for the scanline. @private

FILTER_UP

Indicates that UP filtering is used for the scanline. @private

INTERLACING_ADAM7

Indicates that the image uses Adam7 interlacing. @private

INTERLACING_NONE

Indicates that the image does not use interlacing. @private

UNCOMPRESSED_CONTENT

Indicates that the PNG chunk content is not compressed flag used in iTXt chunk @private

VERSION

The current version of ChunkyPNG. Set it and commit the change this before running rake release.

Public Class Methods

Color(*args) click to toggle source

Factory method to return a color value, based on the arguments given.

@overload Color(r, g, b, a)

@param (see ChunkyPNG::Color.rgba)
@return [Integer] The rgba color value.

@overload Color(r, g, b)

@param (see ChunkyPNG::Color.rgb)
@return [Integer] The rgb color value.

@overload Color(hex_value, opacity = nil)

@param (see ChunkyPNG::Color.from_hex)
@return [Integer] The hex color value, with the opacity applied if one
  was given.

@overload Color(color_name, opacity = nil)

@param (see ChunkyPNG::Color.html_color)
@return [Integer] The hex color value, with the opacity applied if one
  was given.

@overload Color(color_value, opacity = nil)

@param [Integer, :to_i] The color value.
@return [Integer] The color value, with the opacity applied if one was
  given.

@return [Integer] The determined color value as RGBA integer. @raise [ArgumentError] if the arguments weren’t understood as a color. @see ChunkyPNG::Color @see ChunkyPNG::Color.parse

   # File lib/chunky_png/color.rb
33 def self.Color(*args) # rubocop:disable Naming/MethodName # API backwards compatibility
34   case args.length
35     when 1 then ChunkyPNG::Color.parse(args.first)
36     when 2 then (ChunkyPNG::Color.parse(args.first) & 0xffffff00) | args[1].to_i
37     when 3 then ChunkyPNG::Color.rgb(*args)
38     when 4 then ChunkyPNG::Color.rgba(*args)
39     else raise ArgumentError, "Don't know how to create a color from #{args.inspect}!"
40   end
41 end
Dimension(*args) click to toggle source

Creates a {ChunkyPNG::Dimension} instance using arguments that can be interpreted as width and height.

@overload Dimension(width, height)

@param [Integer] width The width-component of the dimension.
@param [Integer] height The height-component of the dimension.
@return [ChunkyPNG::Dimension] The instantiated dimension.

@overload Dimension(string)

@param [String] string A string from which a width and height value can be parsed, e.g.
   <tt>'10x20'</tt> or <tt>'[10, 20]'</tt>.
@return [ChunkyPNG::Dimension] The instantiated dimension.

@overload Dimension(ary)

@param [Array] ary An array with the desired width as first element and the
   desired height as second element, e.g. <tt>[10, 20]</tt>.
@return [ChunkyPNG::Dimension] The instantiated dimension.

@overload Dimension(hash)

@param [Hash] hash An hash with a <tt>'height'</tt> or <tt>:height</tt> key for the
   desired height and with a <tt>'width'</tt> or <tt>:width</tt> key for the desired
   width.
@return [ChunkyPNG::Dimension] The instantiated dimension.

@return [ChunkyPNG::Dimension] The dimension created by this factory method. @raise [ArgumentError] If the argument(s) given where not understood as a dimension. @see ChunkyPNG::Dimension

   # File lib/chunky_png/dimension.rb
31 def self.Dimension(*args)
32   case args.length
33   when 2 then ChunkyPNG::Dimension.new(*args)
34   when 1 then build_dimension_from_object(args.first)
35   else raise ArgumentError,
36     "Don't know how to construct a dimension from #{args.inspect}"
37   end
38 end
Point(*args) click to toggle source

Factory method to create {ChunkyPNG::Point} instances.

This method tries to be as flexible as possible with regards to the given input: besides explicit coordinates, this method also accepts arrays, hashes, strings, {ChunkyPNG::Dimension} instances and anything that responds to :x and :y.

@overload Point(x, y)

@param [Integer, :to_i] x The x-coordinate
@param [Integer, :to_i] y The y-coordinate
@return [ChunkyPNG::Point] The instantiated point.

@overload Point(array)

@param [Array<Integer>] array A two element array which represent the x- and y-coordinate.
@return [ChunkyPNG::Point] The instantiated point.

@overload Point(hash)

@param [Hash] array A hash with the <tt>:x</tt> or <tt>'x'</tt> and <tt>:y</tt> or
  <tt>'y'</tt> keys set, which will be used as coordinates.
@return [ChunkyPNG::Point] The instantiated point.

@overload Point(string)

@param [String] string A string that contains the coordinates, e.g. <tt>'0, 4'</tt>,
  <tt>'(0 4)'</tt>, <tt>[0,4}'</tt>, etc.
@return [ChunkyPNG::Point] The instantiated point.

@return [ChunkyPNG::Point] @raise [ArgumentError] if the arguments weren’t understood. @see ChunkyPNG::Point

   # File lib/chunky_png/point.rb
32 def self.Point(*args)
33   case args.length
34   when 2 then ChunkyPNG::Point.new(*args)
35   when 1 then build_point_from_object(args.first)
36   else raise ArgumentError,
37     "Don't know how to construct a point from #{args.inspect}!"
38   end
39 end
Vector(*args) click to toggle source

Factory method for {ChunkyPNG::Vector} instances.

@overload Vector(x0, y0, x1, y1, x2, y2, …)

Creates a vector by parsing two subsequent values in the argument list
as x- and y-coordinate of a point.
@return [ChunkyPNG::Vector] The instantiated vector.

@overload Vector(string)

Creates a vector by parsing coordinates from the input string.
@return [ChunkyPNG::Vector] The instantiated vector.

@overload Vector(pointlike, pointlike, pointlike, …)

Creates a vector by converting every argument to a point using {ChunkyPNG.Point}.
@return [ChunkyPNG::Vector] The instantiated vector.

@return [ChunkyPNG::Vector] The vector created by this factory method. @raise [ArgumentError] If the given arguments could not be understood as a vector. @see ChunkyPNG::Vector

   # File lib/chunky_png/vector.rb
20 def self.Vector(*args)
21   return args.first if args.length == 1 && args.first.is_a?(ChunkyPNG::Vector)
22 
23   if args.length == 1 && args.first.respond_to?(:scan)
24     ChunkyPNG::Vector.new(ChunkyPNG::Vector.multiple_from_string(args.first)) # e.g. ['1,1 2,2 3,3']
25   else
26     ChunkyPNG::Vector.new(ChunkyPNG::Vector.multiple_from_array(args)) # e.g. [[1,1], [2,2], [3,3]] or [1,1,2,2,3,3]
27   end
28 end

Private Class Methods

build_dimension_from_object(source) click to toggle source
   # File lib/chunky_png/dimension.rb
40 def self.build_dimension_from_object(source)
41   case source
42   when ChunkyPNG::Dimension
43     source
44   when ChunkyPNG::Point
45     ChunkyPNG::Dimension.new(source.x, source.y)
46   when Array
47     ChunkyPNG::Dimension.new(source[0], source[1])
48   when Hash
49     width = source[:width] || source["width"]
50     height = source[:height] || source["height"]
51     ChunkyPNG::Dimension.new(width, height)
52   when ChunkyPNG::Dimension::DIMENSION_REGEXP
53     ChunkyPNG::Dimension.new($1, $2)
54   else
55     if source.respond_to?(:width) && source.respond_to?(:height)
56       ChunkyPNG::Dimension.new(source.width, source.height)
57     else
58       raise ArgumentError, "Don't know how to construct a dimension from #{source.inspect}!"
59     end
60   end
61 end
build_point_from_object(source) click to toggle source
   # File lib/chunky_png/point.rb
41 def self.build_point_from_object(source)
42   case source
43   when ChunkyPNG::Point
44     source
45   when ChunkyPNG::Dimension
46     ChunkyPNG::Point.new(source.width, source.height)
47   when Array
48     ChunkyPNG::Point.new(source[0], source[1])
49   when Hash
50     x = source[:x] || source["x"]
51     y = source[:y] || source["y"]
52     ChunkyPNG::Point.new(x, y)
53   when ChunkyPNG::Point::POINT_REGEXP
54     ChunkyPNG::Point.new($1.to_i, $2.to_i)
55   else
56     if source.respond_to?(:x) && source.respond_to?(:y)
57       ChunkyPNG::Point.new(source.x, source.y)
58     else
59       raise ArgumentError,
60         "Don't know how to construct a point from #{source.inspect}!"
61     end
62   end
63 end