class ChunkyPNG::Canvas

functions are imported from the {ChunkyPNG::Canvas::Drawing} module.
the whole canvas, like cropping and alpha compositing. Simple drawing
The module {ChunkyPNG::Canvas::Operations} is imported for operations on
to work more easily with these number as color values.
RGBA colors (8 bit per channel). The module {ChunkyPNG::Color} is provided
The pixels in the canvas are stored as 4-byte fixnum, representing 32-bit
different colors used in this matrix.
It uses a palette (see {ChunkyPNG::Palette}) to keep track of the
This class offers per-pixel access to the matrix by using x,y coordinates.
variations are supported for both reading and writing.
only supports 8-bit color depth, otherwise all of the PNG format’s
{ChunkyPNG::Datastream PNG datastream} based on this matrix. ChunkyPNG
This class supports loading a Canvas from a PNG datastream, and creating a
pixels.
The ChunkyPNG::Canvas class represents a raster image as a matrix of

def self.from_canvas(canvas)

Returns:
  • (ChunkyPNG::Canvas) - The newly constructed canvas instance.

Parameters:
  • canvas (ChunkyPNG::Canvas) -- The canvas to duplicate
def self.from_canvas(canvas)
  new(canvas.width, canvas.height, canvas.pixels.dup)
end

def [](x, y)

Other tags:
    See: #get_pixel -

Raises:
  • (ChunkyPNG::OutOfBounds) - when the coordinates are outside of the

Returns:
  • (Integer) - The current color value at the provided coordinates.

Parameters:
  • y (Integer) -- The y-coordinate of the pixel (row)
  • x (Integer) -- The x-coordinate of the pixel (column)
def [](x, y)
  assert_xy!(x, y)
  @pixels[y * width + x]
end

def []=(x, y, color)

Other tags:
    See: #set_pixel -

Raises:
  • (ChunkyPNG::OutOfBounds) - when the coordinates are outside of the

Returns:
  • (Integer) - The new color value for this pixel, i.e.

Parameters:
  • color (Integer) -- The new color for the provided coordinates.
  • y (Integer) -- The y-coordinate of the pixel (row)
  • x (Integer) -- The x-coordinate of the pixel (column)
def []=(x, y, color)
  assert_xy!(x, y)
  @pixels[y * width + x] = ChunkyPNG::Color.parse(color)
end

def area

Returns:
  • (Integer) - The number of pixels in this canvas
def area
  pixels.length
end

def assert_height!(vector_length)

height.
Throws an exception if the vector_length does not match this canvas'
def assert_height!(vector_length)
  if height != vector_length
    raise ChunkyPNG::ExpectationFailed,
      "The length of the vector (#{vector_length}) does not match the canvas height (#{height})!"
  end
  true
end

def assert_size!(matrix_width, matrix_height)

Throws an exception if the matrix width and height does not match this canvas' dimensions.
def assert_size!(matrix_width, matrix_height)
  if width != matrix_width
    raise ChunkyPNG::ExpectationFailed,
      "The width of the matrix does not match the canvas width!"
  end
  if height != matrix_height
    raise ChunkyPNG::ExpectationFailed,
      "The height of the matrix does not match the canvas height!"
  end
  true
end

def assert_width!(vector_length)

width.
Throws an exception if the vector_length does not match this canvas'
def assert_width!(vector_length)
  if width != vector_length
    raise ChunkyPNG::ExpectationFailed,
      "The length of the vector (#{vector_length}) does not match the canvas width (#{width})!"
  end
  true
end

def assert_x!(x)

Throws an exception if the x-coordinate is out of bounds.
def assert_x!(x)
  unless include_x?(x)
    raise ChunkyPNG::OutOfBounds, "Column index #{x} out of bounds!"
  end
  true
end

def assert_xy!(x, y)

Throws an exception if the x- or y-coordinate is out of bounds.
def assert_xy!(x, y)
  unless include_xy?(x, y)
    raise ChunkyPNG::OutOfBounds, "Coordinates (#{x},#{y}) out of bounds!"
  end
  true
end

def assert_y!(y)

Throws an exception if the y-coordinate is out of bounds.
def assert_y!(y)
  unless include_y?(y)
    raise ChunkyPNG::OutOfBounds, "Row index #{y} out of bounds!"
  end
  true
end

def column(x)

Returns:
  • (Array) - The vector of pixels in the requested column.

Parameters:
  • x (Integer) -- The 0-based column index.
def column(x)
  assert_x!(x)
  (0...height).inject([]) { |pixels, y| pixels << get_pixel(x, y) }
end

def dimension

Returns:
  • (ChunkyPNG::Dimension) - A dimension instance with the width and
def dimension
  ChunkyPNG::Dimension.new(width, height)
end

def eql?(other)

Returns:
  • (true, false) - True if the size and pixel values of the other

Parameters:
  • other () -- The object to compare this Matrix to.
def eql?(other)
  other.is_a?(self.class) &&
    other.pixels == pixels &&
    other.width == width &&
    other.height == height
end

def get_pixel(x, y)

Returns:
  • (Integer) - The current pixel at the provided coordinates.

Parameters:
  • () --
def get_pixel(x, y)
  @pixels[y * width + x]
end

def include_point?(*point_like)

Other tags:
    See: ChunkyPNG.Point -

Returns:
  • (true, false) - True if the x and y coordinates of the point are

Parameters:
  • point_like (ChunkyPNG::Point, Array, Hash, String) -- The point to
def include_point?(*point_like)
  dimension.include?(ChunkyPNG::Point(*point_like))
end

def include_x?(x)

Returns:
  • (true, false) - True if the x-coordinate is in the range of this

Parameters:
  • x (Integer) -- The y-coordinate of the pixel (column)
def include_x?(x)
  x >= 0 && x < width
end

def include_xy?(x, y)

Returns:
  • (true, false) - True if the x- and y-coordinate is in the range of

Parameters:
  • y (Integer) -- The y-coordinate of the pixel (row)
  • x (Integer) -- The x-coordinate of the pixel (column)
def include_xy?(x, y)
  y >= 0 && y < height && x >= 0 && x < width
end

def include_y?(y)

Returns:
  • (true, false) - True if the y-coordinate is in the range of this

Parameters:
  • y (Integer) -- The y-coordinate of the pixel (row)
def include_y?(y)
  y >= 0 && y < height
end

def initialize(width, height, initial = ChunkyPNG::Color::TRANSPARENT)

Parameters:
  • initial (Array) -- The initial pizel values. Must be an
  • height (Integer) -- The height in pixels of this canvas
  • width (Integer) -- The width in pixels of this canvas
  • background_color (Integer, ...) -- The initial background color of
  • height (Integer) -- The height in pixels of this canvas
  • width (Integer) -- The width in pixels of this canvas

Overloads:
  • initialize(width, height, initial)
  • initialize(width, height, background_color)
def initialize(width, height, initial = ChunkyPNG::Color::TRANSPARENT)
  @width, @height = width, height
  if initial.is_a?(Array)
    pixel_count = width * height
    unless initial.length == pixel_count
      raise ArgumentError, "The initial array should have #{width}x#{height} = #{pixel_count} elements!"
    end
    @pixels = initial
  else
    @pixels = Array.new(width * height, ChunkyPNG::Color.parse(initial))
  end
end

def initialize_copy(other)

Other tags:
    Private: -

Returns:
  • (void) -

Parameters:
  • other (ChunkyPNG::Canvas) -- The canvas to duplicate
def initialize_copy(other)
  @width, @height = other.width, other.height
  @pixels = other.pixels.dup
end

def inspect

Other tags:
    Private: -

Returns:
  • (String) - A nicely formatted string representation of this canvas.
def inspect
  inspected = +"<#{self.class.name} #{width}x#{height} ["
  for y in 0...height
    inspected << "\n\t[" << row(y).map { |p| ChunkyPNG::Color.to_hex(p) }.join(" ") << "]"
  end
  inspected << "\n]>"
end

def palette

Returns:
  • (ChunkyPNG::Palette) - A palette which contains all the colors that
def palette
  ChunkyPNG::Palette.from_canvas(self)
end

def replace_canvas!(new_width, new_height, new_pixels)

Replaces the image, given a new width, new height, and a new pixel array.
def replace_canvas!(new_width, new_height, new_pixels)
  unless new_pixels.length == new_width * new_height
    raise ArgumentError, "The provided pixel array should have #{new_width * new_height} items"
  end
  @width, @height, @pixels = new_width, new_height, new_pixels
  self
end

def replace_column!(x, vector)

Returns:
  • (void) -

Parameters:
  • vector (Array) -- The vector of pixels to replace the column
  • x (Integer) -- The 0-based column index.
def replace_column!(x, vector)
  assert_x!(x) && assert_height!(vector.length)
  for y in 0...height do
    set_pixel(x, y, vector[y])
  end
end

def replace_row!(y, vector)

Returns:
  • (void) -

Parameters:
  • vector (Array) -- The vector of pixels to replace the row
  • y (Integer) -- The 0-based row index.
def replace_row!(y, vector)
  assert_y!(y) && assert_width!(vector.length)
  pixels[y * width, width] = vector
end

def row(y)

Returns:
  • (Array) - The vector of pixels in the requested row

Parameters:
  • y (Integer) -- The 0-based row index
def row(y)
  assert_y!(y)
  pixels.slice(y * width, width)
end

def set_pixel(x, y, color)

Returns:
  • (Integer) - The new color value for this pixel, i.e.

Parameters:
  • color (Integer) -- The new color for the provided coordinates.
  • y (Integer) -- The y-coordinate of the pixel (row)
  • x (Integer) -- The x-coordinate of the pixel (column)
def set_pixel(x, y, color)
  @pixels[y * width + x] = color
end

def set_pixel_if_within_bounds(x, y, color)

Returns:
  • (Integer) - The new color value for this pixel, i.e.

Parameters:
  • color (Integer) -- The new color value for the provided coordinates.
  • y (Integer) -- The y-coordinate of the pixel (row)
  • x (Integer) -- The x-coordinate of the pixel (column)
def set_pixel_if_within_bounds(x, y, color)
  return unless include_xy?(x, y)
  @pixels[y * width + x] = color
end

def to_image

Returns:
  • (ChunkyPNG::Image) - This canvas wrapped in an Image instance.
def to_image
  ChunkyPNG::Image.from_canvas(self)
end