Class: ChunkyPNG::Canvas

Inherits:
Object
  • Object
show all
Extended by:
Adam7Interlacing, DataUrlImporting, PNGDecoding, StreamImporting
Includes:
DataUrlExporting, Drawing, Masking, Operations, PNGEncoding, Resampling, StreamExporting
Defined in:
lib/chunky_png/canvas.rb,
lib/chunky_png/canvas/drawing.rb,
lib/chunky_png/canvas/masking.rb,
lib/chunky_png/canvas/operations.rb,
lib/chunky_png/canvas/resampling.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,
lib/chunky_png/canvas/data_url_exporting.rb,
lib/chunky_png/canvas/data_url_importing.rb

Overview

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 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, DataUrlExporting, DataUrlImporting, Drawing, Masking, Operations, PNGDecoding, PNGEncoding, Resampling, StreamExporting, StreamImporting

Instance Attribute Summary collapse

Attributes included from PNGDecoding

#decoding_palette, #transparent_color

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 DataUrlImporting

from_data_url

Methods included from Masking

#change_mask_color!, #change_theme_color!, #extract_mask

Methods included from Resampling

#resample_bilinear, #resample_bilinear!, #resample_nearest_neighbor, #resample_nearest_neighbor!, #steps, #steps_residues

Methods included from Drawing

#bezier_curve, #circle, #compose_pixel, #compose_pixel_unsafe, #line_xiaolin_wu, #polygon, #rect

Methods included from Operations

#compose, #compose!, #crop, #crop!, #flip_horizontally, #flip_horizontally!, #flip_vertically, #flip_vertically!, #grayscale, #grayscale!, #replace, #replace!, #rotate_180, #rotate_180!, #rotate_left, #rotate_left!, #rotate_right, #rotate_right!

Methods included from DataUrlExporting

#to_data_url

Methods included from StreamExporting

#to_abgr_stream, #to_alpha_channel_stream, #to_grayscale_stream, #to_rgb_stream, #to_rgba_stream

Methods included from PNGEncoding

#save, #to_blob, #to_datastream, #write

Constructor Details

#initialize(width, height, background_color) ⇒ Canvas #initialize(width, height, initial) ⇒ Canvas

Initializes a new Canvas instance.

Overloads:

  • #initialize(width, height, background_color) ⇒ Canvas

    Parameters:

    • width (Integer) —

      The width in pixels of this canvas

    • height (Integer) —

      The height in pixels of this canvas

    • background_color (Integer, ...) —

      The initial background color of this canvas. This can be a color value or any value that ChunkyPNG::Color.parse can handle.

  • #initialize(width, height, initial) ⇒ Canvas

    Parameters:

    • width (Integer) —

      The width in pixels of this canvas

    • height (Integer) —

      The height in pixels of this canvas

    • initial (Array<Integer>) —

      The initial pizel values. Must be an array with width * height elements.



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/chunky_png/canvas.rb', line 79

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

  @width, @height = width, height

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



55
56
57
 
# File 'lib/chunky_png/canvas.rb', line 55

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.



59
60
61
 
# File 'lib/chunky_png/canvas.rb', line 59

def pixels
  @pixels
end

#width ⇒ Integer (readonly)

Returns The number of columns in this canvas.

Returns:

  • (Integer) —

    The number of columns in this canvas



52
53
54
 
# File 'lib/chunky_png/canvas.rb', line 52

def width
  @width
end

Class Method Details

.from_canvas(canvas) ⇒ ChunkyPNG::Canvas

Creates a new canvas instance by duplicating another instance.

Parameters:

Returns:



103
104
105
 
# File 'lib/chunky_png/canvas.rb', line 103

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

Instance Method Details

#[](x, y) ⇒ Integer

Returns a single pixel’s color value from this canvas.

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

Returns:

  • (Integer) —

    The current color value at the provided coordinates.

Raises:

See Also:



168
169
170
171
 
# File 'lib/chunky_png/canvas.rb', line 168

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

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

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)

  • color (Integer) —

    The new color for the provided coordinates.

Returns:

  • (Integer) —

    The new color value for this pixel, i.e. color.

Raises:

See Also:



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

def []=(x, y, color)
  assert_xy!(x, y)
  @pixels[y * width + x] = ChunkyPNG::Color.parse(color)
end

#area ⇒ Integer

Returns the area of this canvas in number of pixels.

Returns:

  • (Integer) —

    The number of pixels in this canvas



120
121
122
 
# File 'lib/chunky_png/canvas.rb', line 120

def area
  pixels.length
end

#column(x) ⇒ Array<Integer>

Returns an extracted column as vector of pixels.

Parameters:

  • x (Integer) —

    The 0-based column index.

Returns:

  • (Array<Integer>) —

    The vector of pixels in the requested column.



192
193
194
195
 
# File 'lib/chunky_png/canvas.rb', line 192

def column(x)
  assert_x!(x)
  (0...height).inject([]) { |pixels, y| pixels << get_pixel(x, y) }
end

#dimension ⇒ ChunkyPNG::Dimension

Returns the dimension (width x height) for this canvas.

Returns:



114
115
116
 
# File 'lib/chunky_png/canvas.rb', line 114

def dimension
  ChunkyPNG::Dimension.new(width, height)
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.



261
262
263
264
 
# File 'lib/chunky_png/canvas.rb', line 261

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

#get_pixel(x, y) ⇒ Integer

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.

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

Returns:

  • (Integer) —

    The current pixel at the provided coordinates.



177
178
179
 
# File 'lib/chunky_png/canvas.rb', line 177

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

#include_point?(*point_like) ⇒ true, false Also known as: include?

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

Parameters:

Returns:

  • (true, false) —

    True if the x and y coordinates of the point are

    within the limits of this canvas.

See Also:



222
223
224
 
# File 'lib/chunky_png/canvas.rb', line 222

def include_point?(*point_like)
  dimension.include?(ChunkyPNG::Point(*point_like))
end

#include_x?(x) ⇒ true, false

Checks whether the given x-coordinate is in the range of the canvas

Parameters:

  • x (Integer) —

    The y-coordinate of the pixel (column)

Returns:

  • (true, false) —

    True if the x-coordinate is in the range of this canvas.



246
247
248
 
# File 'lib/chunky_png/canvas.rb', line 246

def include_x?(x)
  x >= 0 && x < width
end

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

Checks whether the given x- and y-coordinate 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 is in the range of this canvas.



232
233
234
 
# File 'lib/chunky_png/canvas.rb', line 232

def include_xy?(x, y)
  y >= 0 && y < height && x >= 0 && x < width
end

#include_y?(y) ⇒ true, false

Checks whether the given y-coordinate is in the range of the canvas

Parameters:

  • y (Integer) —

    The y-coordinate of the pixel (row)

Returns:

  • (true, false) —

    True if the y-coordinate is in the range of this canvas.



239
240
241
 
# File 'lib/chunky_png/canvas.rb', line 239

def include_y?(y)
  y >= 0 && y < height
end

#palette ⇒ ChunkyPNG::Palette

Returns the palette used for this canvas.

Returns:

  • (ChunkyPNG::Palette) —

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



253
254
255
 
# File 'lib/chunky_png/canvas.rb', line 253

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

#replace_column!(x, vector)

This method returns an undefined value.

Replaces a column of pixels on this canvas.

Parameters:

  • x (Integer) —

    The 0-based column index.

  • vector (Array<Integer>) —

    The vector of pixels to replace the column with.



210
211
212
213
214
215
 
# File 'lib/chunky_png/canvas.rb', line 210

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)

This method returns an undefined value.

Replaces a row of pixels on this canvas.

Parameters:

  • y (Integer) —

    The 0-based row index.

  • vector (Array<Integer>) —

    The vector of pixels to replace the row with.



201
202
203
204
 
# File 'lib/chunky_png/canvas.rb', line 201

def replace_row!(y, vector)
  assert_y!(y) && assert_width!(vector.length)
  pixels[y * width, width] = vector
end

#row(y) ⇒ Array<Integer>

Returns an extracted row as vector of pixels

Parameters:

  • y (Integer) —

    The 0-based row index

Returns:

  • (Array<Integer>) —

    The vector of pixels in the requested row



184
185
186
187
 
# File 'lib/chunky_png/canvas.rb', line 184

def row(y)
  assert_y!(y)
  pixels.slice(y * width, width)
end

#set_pixel(x, y, color) ⇒ Integer

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.

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

  • pixel (Integer) —

    The new color for the provided coordinates.

Returns:

  • (Integer) —

    The new color value for this pixel, i.e. color.



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

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

#set_pixel_if_within_bounds(x, y, color) ⇒ Integer

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

Parameters:

  • x (Integer) —

    The x-coordinate of the pixel (column)

  • y (Integer) —

    The y-coordinate of the pixel (row)

  • pixel (Integer) —

    The new color value for the provided coordinates.

Returns:

  • (Integer) —

    The new color value for this pixel, i.e. color, or nil if the coordinates are out of bounds.



157
158
159
160
 
# File 'lib/chunky_png/canvas.rb', line 157

def set_pixel_if_within_bounds(x, y, color)
  return unless include_xy?(x, y)
  @pixels[y * width + x] = color
end

#to_image ⇒ ChunkyPNG::Image

Creates an ChunkyPNG::Image object from this canvas.

Returns:



274
275
276
 
# File 'lib/chunky_png/canvas.rb', line 274

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