Class: ChunkyPNG::Canvas

### Home Classes Methods

### In Files

- lib/chunky_png/canvas.rb
- lib/chunky_png/canvas/adam7_interlacing.rb
- lib/chunky_png/canvas/data_url_exporting.rb
- lib/chunky_png/canvas/data_url_importing.rb
- lib/chunky_png/canvas/drawing.rb
- lib/chunky_png/canvas/masking.rb
- lib/chunky_png/canvas/operations.rb
- lib/chunky_png/canvas/png_decoding.rb
- lib/chunky_png/canvas/png_encoding.rb
- lib/chunky_png/canvas/resampling.rb
- lib/chunky_png/canvas/stream_exporting.rb
- lib/chunky_png/canvas/stream_importing.rb

### Parent

Object

### Namespace

- MODULE ChunkyPNG::Canvas::Adam7Interlacing
- MODULE ChunkyPNG::Canvas::DataUrlExporting
- MODULE ChunkyPNG::Canvas::DataUrlImporting
- MODULE ChunkyPNG::Canvas::Drawing
- MODULE ChunkyPNG::Canvas::Masking
- MODULE ChunkyPNG::Canvas::Operations
- MODULE ChunkyPNG::Canvas::PNGDecoding
- MODULE ChunkyPNG::Canvas::PNGEncoding
- MODULE ChunkyPNG::Canvas::Resampling
- MODULE ChunkyPNG::Canvas::StreamExporting
- MODULE ChunkyPNG::Canvas::StreamImporting

### Methods

- ::from_canvas
- ::new
- #==
- #[]
- #[]=
- #area
- #assert_height!
- #assert_size!
- #assert_width!
- #assert_x!
- #assert_xy!
- #assert_y!
- #column
- #dimension
- #eql?
- #get_pixel
- #include?
- #include_point?
- #include_x?
- #include_xy?
- #include_y?
- #initialize_copy
- #inspect
- #palette
- #replace_canvas!
- #replace_column!
- #replace_row!
- #row
- #set_pixel
- #set_pixel_if_within_bounds
- #to_image

### Included Modules

- ChunkyPNG::Canvas::PNGEncoding
- ChunkyPNG::Canvas::StreamExporting
- ChunkyPNG::Canvas::DataUrlExporting
- ChunkyPNG::Canvas::Operations
- ChunkyPNG::Canvas::Drawing
- ChunkyPNG::Canvas::Resampling
- ChunkyPNG::Canvas::Masking

### Files

- BENCHMARKING.rdoc
- CHANGELOG.rdoc
- CONTRIBUTING.rdoc
- README.rdoc

### Class/Module Index

Quicksearch

- ChunkyPNG
- ChunkyPNG::CRCMismatch
- ChunkyPNG::Canvas
- ChunkyPNG::Canvas::Adam7Interlacing
- ChunkyPNG::Canvas::DataUrlExporting
- ChunkyPNG::Canvas::DataUrlImporting
- ChunkyPNG::Canvas::Drawing
- ChunkyPNG::Canvas::Masking
- ChunkyPNG::Canvas::Operations
- ChunkyPNG::Canvas::PNGDecoding
- ChunkyPNG::Canvas::PNGEncoding
- ChunkyPNG::Canvas::Resampling
- ChunkyPNG::Canvas::StreamExporting
- ChunkyPNG::Canvas::StreamImporting
- ChunkyPNG::Chunk
- ChunkyPNG::Chunk::Base
- ChunkyPNG::Chunk::CompressedText
- ChunkyPNG::Chunk::End
- ChunkyPNG::Chunk::Generic
- ChunkyPNG::Chunk::Header
- ChunkyPNG::Chunk::ImageData
- ChunkyPNG::Chunk::InternationalText
- ChunkyPNG::Chunk::Palette
- ChunkyPNG::Chunk::Text
- ChunkyPNG::Chunk::Transparency
- ChunkyPNG::Color
- ChunkyPNG::Datastream
- ChunkyPNG::Dimension
- ChunkyPNG::Exception
- ChunkyPNG::ExpectationFailed
- ChunkyPNG::Image
- ChunkyPNG::NotSupported
- ChunkyPNG::OutOfBounds
- ChunkyPNG::Palette
- ChunkyPNG::Point
- ChunkyPNG::RMagick
- ChunkyPNG::SignatureMismatch
- ChunkyPNG::Vector
- Enumerable
- String

No matching classes.

# ChunkyPNG::Canvas

The ChunkyPNG::Canvas class represents a raster image as a matrix of pixels.

This class supports loading a Canvas from a PNG datastream, and creating a {ChunkyPNG::Datastream PNG datastream} based on this matrix. ChunkyPNG only supports 8-bit color depth, otherwise all of the PNG format's variations are supported for both reading and writing.

This class offers per-pixel access to the matrix by using x,y coordinates. It uses a palette (see {ChunkyPNG::Palette}) to keep track of the different colors used in this matrix.

The pixels in the canvas are stored as 4-byte fixnum, representing 32-bit RGBA colors (8 bit per channel). The module {ChunkyPNG::Color} is provided to work more easily with these number as color values.

The module {ChunkyPNG::Canvas::Operations} is imported for operations on the whole canvas, like cropping and alpha compositing. Simple drawing functions are imported from the {ChunkyPNG::Canvas::Drawing} module.

### Attributes

height[R]

@return [Integer] The number of rows in this canvas

pixels[R]

@return [Array<ChunkyPNG::Color>] The list of pixels in this canvas.

    This array always should have +width * height+ elements.

width[R]

@return [Integer] The number of columns in this canvas

### Public Class Methods

from_canvas(canvas) click to toggle source

Creates a new canvas instance by duplicating another instance. @param [ChunkyPNG::Canvas] canvas The canvas to duplicate @return [ChunkyPNG::Canvas] The newly constructed canvas instance.

    # File lib/chunky_png/canvas.rb, line 103
    def self.from_canvas(canvas)
      new(canvas.width, canvas.height, canvas.pixels.dup)
    end

new(width, height, initial = ChunkyPNG::Color::TRANSPARENT) click to toggle source

Initializes a new Canvas instance.

@overload initialize(width, height, background_color)

    @param [Integer] width The width in pixels of this canvas
    @param [Integer] height The height in pixels of this canvas
    @param [Integer, ...] background_color The initial background color of
      this canvas. This can be a color value or any value that
      {ChunkyPNG::Color.parse} can handle.

@overload initialize(width, height, initial)

    @param [Integer] width The width in pixels of this canvas
    @param [Integer] height The height in pixels of this canvas
    @param [Array<Integer>] initial The initial pizel values. Must be an
      array with <tt>width * height</tt> elements.

    # File lib/chunky_png/canvas.rb, line 78
    def initialize(width, height, initial = ChunkyPNG::Color::TRANSPARENT)
      @width, @height = width, height

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

### Public Instance Methods

==(other) click to toggle source
Alias for: eql?
[](x, y) click to toggle source

Returns a single pixel's color value from this canvas. @param [Integer] x The x-coordinate of the pixel (column) @param [Integer] y The y-coordinate of the pixel (row) @return [Integer] The current color value at the provided coordinates. @raise [ChunkyPNG::OutOfBounds] when the coordinates are outside of the

    image's dimensions.

@see get_pixel

    # File lib/chunky_png/canvas.rb, line 173
    def [](x, y)
      assert_xy!(x, y)
      @pixels[y * width + x]
    end

[]=(x, y, color) click to toggle source

Replaces a single pixel in this canvas. @param [Integer] x The x-coordinate of the pixel (column) @param [Integer] y The y-coordinate of the pixel (row) @param [Integer] color The new color for the provided coordinates. @return [Integer] The new color value for this pixel, i.e.

    <tt>color</tt>.

@raise [ChunkyPNG::OutOfBounds] when the coordinates are outside of the

    image's dimensions.

@see set_pixel

    # File lib/chunky_png/canvas.rb, line 134
    def []=(x, y, color)
      assert_xy!(x, y)
      @pixels[y * width + x] = ChunkyPNG::Color.parse(color)
    end

area() click to toggle source

Returns the area of this canvas in number of pixels. @return [Integer] The number of pixels in this canvas

    # File lib/chunky_png/canvas.rb, line 121
    def area
      pixels.length
    end

column(x) click to toggle source

Returns an extracted column as vector of pixels. @param [Integer] x The 0-based column index. @return [Array<Integer>] The vector of pixels in the requested column.

    # File lib/chunky_png/canvas.rb, line 199
    def column(x)
      assert_x!(x)
      (0...height).inject([]) { |pixels, y| pixels << get_pixel(x, y) }
    end

dimension() click to toggle source

Returns the dimension (width x height) for this canvas. @return [ChunkyPNG::Dimension] A dimension instance with the width and

    height set for this canvas.

    # File lib/chunky_png/canvas.rb, line 115
    def dimension
      ChunkyPNG::Dimension.new(width, height)
    end

eql?(other) click to toggle source

Equality check to compare this canvas with other matrices. @param other The object to compare this Matrix to. @return [true, false] True if the size and pixel values of the other

    canvas are exactly the same as this canvas's size and pixel values.

    # File lib/chunky_png/canvas.rb, line 276
    def eql?(other)
      other.kind_of?(self.class) && other.pixels == self.pixels &&
            other.width == self.width && other.height == self.height
    end

Also aliased as: ==
get_pixel(x, y) click to toggle source

Returns a single pixel from this canvas, without checking bounds. The return value for this method is undefined if the coordinates are out of bounds.

@param (see #[]) @return [Integer] The current pixel at the provided coordinates.

    # File lib/chunky_png/canvas.rb, line 184
    def get_pixel(x, y)
      @pixels[y * width + x]
    end

include?(*point_like) click to toggle source
Alias for: include_point?
include_point?(*point_like) click to toggle source

Checks whether the given coordinates are in the range of the canvas @param [ChunkyPNG::Point, Array, Hash, String] point_like The point to

    check.

@return [true, false] True if the x and y coordinates of the point are

    within the limits of this canvas.

@see ChunkyPNG.Point

    # File lib/chunky_png/canvas.rb, line 232
    def include_point?(*point_like)
      dimension.include?(ChunkyPNG::Point(*point_like))
    end

Also aliased as: include?
include_x?(x) click to toggle source

Checks whether the given x-coordinate is in the range of the canvas @param [Integer] x The y-coordinate of the pixel (column) @return [true, false] True if the x-coordinate is in the range of this

    canvas.

    # File lib/chunky_png/canvas.rb, line 261
    def include_x?(x)
      x >= 0 && x < width
    end

include_xy?(x, y) click to toggle source

Checks whether the given x- and y-coordinate are in the range of the canvas

@param [Integer] x The x-coordinate of the pixel (column) @param [Integer] y The y-coordinate of the pixel (row) @return [true, false] True if the x- and y-coordinate is in the range of

    this canvas.

    # File lib/chunky_png/canvas.rb, line 245
    def include_xy?(x, y)
      y >= 0 && y < height && x >= 0 && x < width
    end

include_y?(y) click to toggle source

Checks whether the given y-coordinate is in the range of the canvas @param [Integer] y The y-coordinate of the pixel (row) @return [true, false] True if the y-coordinate is in the range of this

    canvas.

    # File lib/chunky_png/canvas.rb, line 253
    def include_y?(y)
      y >= 0 && y < height
    end

initialize_copy(other) click to toggle source

Initializes a new Canvas instances when being cloned. @param [ChunkyPNG::Canvas] other The canvas to duplicate @return [void] @private

    # File lib/chunky_png/canvas.rb, line 95
    def initialize_copy(other)
      @width, @height = other.width, other.height
      @pixels = other.pixels.dup
    end

inspect() click to toggle source

Alternative implementation of the inspect method. @return [String] A nicely formatted string representation of this canvas. @private

    # File lib/chunky_png/canvas.rb, line 296
    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

palette() click to toggle source

Returns the palette used for this canvas. @return [ChunkyPNG::Palette] A palette which contains all the colors that

    are being used for this image.

    # File lib/chunky_png/canvas.rb, line 268
    def palette
      ChunkyPNG::Palette.from_canvas(self)
    end

replace_column!(x, vector) click to toggle source

Replaces a column of pixels on this canvas. @param [Integer] x The 0-based column index. @param [Array<Integer>] vector The vector of pixels to replace the column

    with.

@return [void]

    # File lib/chunky_png/canvas.rb, line 219
    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

replace_row!(y, vector) click to toggle source

Replaces a row of pixels on this canvas. @param [Integer] y The 0-based row index. @param [Array<Integer>] vector The vector of pixels to replace the row

    with.

@return [void]

    # File lib/chunky_png/canvas.rb, line 209
    def replace_row!(y, vector)
      assert_y!(y) && assert_width!(vector.length)
      pixels[y * width, width] = vector
    end

row(y) click to toggle source

Returns an extracted row as vector of pixels @param [Integer] y The 0-based row index @return [Array<Integer>] The vector of pixels in the requested row

    # File lib/chunky_png/canvas.rb, line 191
    def row(y)
      assert_y!(y)
      pixels.slice(y * width, width)
    end

set_pixel(x, y, color) click to toggle source

Replaces a single pixel in this canvas, without bounds checking.

This method return value and effects are undefined for coordinates out of bounds of the canvas.

@param [Integer] x The x-coordinate of the pixel (column) @param [Integer] y The y-coordinate of the pixel (row) @param [Integer] pixel The new color for the provided coordinates. @return [Integer] The new color value for this pixel, i.e.

    <tt>color</tt>.

    # File lib/chunky_png/canvas.rb, line 149
    def set_pixel(x, y, color)
      @pixels[y * width + x] = color
    end

set_pixel_if_within_bounds(x, y, color) click to toggle source

Replaces a single pixel in this canvas, with bounds checking. It will do noting if the provided coordinates are out of bounds.

@param [Integer] x The x-coordinate of the pixel (column) @param [Integer] y The y-coordinate of the pixel (row) @param [Integer] pixel The new color value for the provided coordinates. @return [Integer] The new color value for this pixel, i.e.

    <tt>color</tt>, or <tt>nil</tt> if the coordinates are out of bounds.

    # File lib/chunky_png/canvas.rb, line 161
    def set_pixel_if_within_bounds(x, y, color)
      return unless include_xy?(x, y)
      @pixels[y * width + x] = color
    end

to_image() click to toggle source

Creates an ChunkyPNG::Image object from this canvas. @return [ChunkyPNG::Image] This canvas wrapped in an Image instance.

    # File lib/chunky_png/canvas.rb, line 289
    def to_image
      ChunkyPNG::Image.from_canvas(self)
    end

### Protected Instance Methods

assert_height!(vector_length) click to toggle source

Throws an exception if the vector_length does not match this canvas' height.

    # File lib/chunky_png/canvas.rb, line 341
    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

assert_size!(matrix_width, matrix_height) click to toggle source

Throws an exception if the matrix width and height does not match this canvas' dimensions.

    # File lib/chunky_png/canvas.rb, line 360
    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

assert_width!(vector_length) click to toggle source

Throws an exception if the vector_length does not match this canvas' width.

    # File lib/chunky_png/canvas.rb, line 351
    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

assert_x!(x) click to toggle source

Throws an exception if the x-coordinate is out of bounds.

    # File lib/chunky_png/canvas.rb, line 316
    def assert_x!(x)
      unless include_x?(x)
        raise ChunkyPNG::OutOfBounds, "Column index #{x} out of bounds!"
      end
      true
    end

assert_xy!(x, y) click to toggle source

Throws an exception if the x- or y-coordinate is out of bounds.

    # File lib/chunky_png/canvas.rb, line 332
    def assert_xy!(x, y)
      unless include_xy?(x, y)
        raise ChunkyPNG::OutOfBounds, "Coordinates (#{x},#{y}) out of bounds!"
      end
      true
    end

assert_y!(y) click to toggle source

Throws an exception if the y-coordinate is out of bounds.

    # File lib/chunky_png/canvas.rb, line 324
    def assert_y!(y)
      unless include_y?(y)
        raise ChunkyPNG::OutOfBounds, "Row index #{y} out of bounds!"
      end
      true
    end

replace_canvas!(new_width, new_height, new_pixels) click to toggle source

Replaces the image, given a new width, new height, and a new pixel array.

    # File lib/chunky_png/canvas.rb, line 307
    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

[Validate]

Generated with the Darkfish Rdoc Generator 2.