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 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

#border, #border!, #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!, #trim, #trim!

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.



78
79
80
81
82
83
84
85
86
87
88
89
 
# 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

Instance Attribute Details

#height ⇒ Integer (readonly)

Returns The number of rows in this canvas.

Returns:

  • (Integer) —

    The number of rows in this canvas



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

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.



57
58
59
 
# File 'lib/chunky_png/canvas.rb', line 57

def pixels
  @pixels
end

#width ⇒ Integer (readonly)

Returns The number of columns in this canvas.

Returns:

  • (Integer) —

    The number of columns in this canvas



50
51
52
 
# File 'lib/chunky_png/canvas.rb', line 50

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)
  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:



173
174
175
176
 
# File 'lib/chunky_png/canvas.rb', line 173

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:



134
135
136
137
 
# 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 ⇒ Integer

Returns the area of this canvas in number of pixels.

Returns:

  • (Integer) —

    The number of pixels in this canvas



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

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.



199
200
201
202
 
# 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 ⇒ ChunkyPNG::Dimension

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

Returns:



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

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.



276
277
278
279
 
# 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

#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.



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

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:



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

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.



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

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.



245
246
247
 
# 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) ⇒ 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.



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

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.



268
269
270
 
# File 'lib/chunky_png/canvas.rb', line 268

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.



219
220
221
222
223
224
 
# 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)

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.



209
210
211
212
 
# 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) ⇒ 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



191
192
193
194
 
# 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) ⇒ 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.



149
150
151
 
# 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) ⇒ 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.



161
162
163
164
 
# 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 ⇒ ChunkyPNG::Image

Creates an ChunkyPNG::Image object from this canvas.

Returns:



289
290
291
 
# File 'lib/chunky_png/canvas.rb', line 289

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