Class: ChunkyPNG::Canvas

Inherits:
Object
  • Object
show all
Extended by:
Adam7Interlacing, PNGDecoding, StreamImporting
Includes:
Drawing, Operations, PNGEncoding, StreamExporting
Defined in:
lib/chunky_png/canvas.rb,
lib/chunky_png/canvas/drawing.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/stream_exporting.rb,
lib/chunky_png/canvas/stream_importing.rb,
lib/chunky_png/canvas/adam7_interlacing.rb

Overview

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

This class supports loading a Canvas from a PNG datastream, and creating a 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 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 Color is provided to work more easily with these number as color values.

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

Direct Known Subclasses

Image

Defined Under Namespace

Modules: Adam7Interlacing, Drawing, Operations, PNGDecoding, PNGEncoding, StreamExporting, StreamImporting

Instance Attribute Summary collapse

Attributes included from PNGDecoding

#decoding_palette

Attributes included from PNGEncoding

#encoding_palette

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PNGDecoding

decode_png_pixelstream, from_blob, from_datastream, from_file, from_io

Methods included from Adam7Interlacing

adam7_extract_pass, adam7_merge_pass, adam7_multiplier_offset, adam7_pass_size, adam7_pass_sizes

Methods included from StreamImporting

from_abgr_stream, from_bgr_stream, from_rgb_stream, from_rgba_stream

Methods included from Drawing

#line_xiaolin_wu, #point

Methods included from Operations

#change_mask_color!, #change_theme_color!, #compose, #crop, #extract_mask, #replace

Methods included from StreamExporting

#to_abgr_stream, #to_rgb_stream, #to_rgba_stream

Methods included from PNGEncoding

#save, #to_blob, #to_datastream, #write

Constructor Details

#initialize(width, height, initial = ChunkyPNG::Color::TRANSPARENT) ⇒ Canvas

Initializes a new Canvas instance

Parameters:

  • width (Integer) —

    The width in pixels of this canvas

  • width (Integer) —

    The height in pixels of this canvas

  • initial (ChunkyPNG::Pixel, Array<ChunkyPNG::Color>) (defaults to: ChunkyPNG::Color::TRANSPARENT) —

    The initial value of te pixels:

    • If a color is passed to this parameter, this color will be used as background color.

    • If an array of pixels is provided, these pixels will be used as initial value. Note that the amount of pixels in this array should equal width * height.



58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/chunky_png/canvas.rb', line 58

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

  @width, @height = width, height

  if initial.kind_of?(Fixnum)
    @pixels = Array.new(width * height, initial)
  elsif initial.kind_of?(Array) && initial.size == width * height
    @pixels = initial
  else
    raise "Cannot use this value as initial canvas: #{initial.inspect}!"
  end
end

Instance Attribute Details

#height ⇒ Integer (readonly)

Returns The number of rows in this canvas.

Returns:

  • (Integer) —

    The number of rows in this canvas



38
39
40
 
# File 'lib/chunky_png/canvas.rb', line 38

def height
  @height
end

#pixels ⇒ Array<ChunkyPNG::Color> (readonly)

Returns The list of pixels in this canvas. This array always should have width * height elements.

Returns:

  • (Array<ChunkyPNG::Color>) —

    The list of pixels in this canvas. This array always should have width * height elements.



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

def pixels
  @pixels
end

#width ⇒ Integer (readonly)

Returns The number of columns in this canvas.

Returns:

  • (Integer) —

    The number of columns in this canvas



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

def width
  @width
end

Class Method Details

.from_canvas(canvas) ⇒ ChunkyPNG::Canvas

Creates a new canvas instance by duplicating another instance.

Parameters:

Returns:



81
82
83
 
# File 'lib/chunky_png/canvas.rb', line 81

def self.from_canvas(canvas)
  self.new(canvas.width, canvas.height, canvas.pixels.dup)
end

Instance Method Details

#[](x, y) ⇒ ChunkyPNG::Color

Returns a single pixel from this canvas.

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

Returns:



108
109
110
 
# File 'lib/chunky_png/canvas.rb', line 108

def [](x, y)
  @pixels[y * width + x]
end

#[]=(x, y, color) ⇒ Object

Replaces a single pixel in this canvas.

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

  • pixel (ChunkyPNG::Color) —

    The new pixel for the provided coordinates.



100
101
102
 
# File 'lib/chunky_png/canvas.rb', line 100

def []=(x, y, color)
  @pixels[y * width + x] = color
end

#eql?(other) ⇒ true, false Also known as: ==

Equality check to compare this canvas with other matrices.

Parameters:

  • other —

    The object to compare this Matrix to.

Returns:

  • (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.



132
133
134
135
 
# File 'lib/chunky_png/canvas.rb', line 132

def eql?(other)
  other.kind_of?(self.class) && other.pixels == self.pixels &&
        other.width == self.width && other.height == self.height
end

#include?(x, y) ⇒ true, false

Checks whether the given coordinates are in the range of the canvas

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

Returns:

  • (true, false) —

    True if the x and y coordinate are in the range of this canvas.



117
118
119
 
# File 'lib/chunky_png/canvas.rb', line 117

def include?(x, y)
  (0...width).include?(x) && (0...height).include?(y)
end

#initialize_copy(other) ⇒ Object

Initializes a new Canvas instances when being cloned.

Parameters:



73
74
75
76
 
# File 'lib/chunky_png/canvas.rb', line 73

def initialize_copy(other)
  @width, @height = other.width, other.height
  @pixels = other.pixels.dup
end

#palette ⇒ ChunkyPNG::Palette

Returns the palette used for this canvas.

Returns:

  • (ChunkyPNG::Palette) —

    A pallete which contains all the colors that are being used for this image.



124
125
126
 
# File 'lib/chunky_png/canvas.rb', line 124

def palette
  ChunkyPNG::Palette.from_canvas(self)
end

#size ⇒ Object

Returns the size ([width, height]) for this canvas.

Returns:

  • Array An array with the width and height of this canvas as elements.



92
93
94
 
# File 'lib/chunky_png/canvas.rb', line 92

def size
  [@width, @height]
end

#to_image ⇒ ChunkyPNG::Image

Creates an ChunkyPNG::Image object from this canvas.

Returns:



145
146
147
 
# File 'lib/chunky_png/canvas.rb', line 145

def to_image
  ChunkyPNG::Image.from_canvas(self)
end