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 DataUrlImporting

from_data_url

Methods included from StreamImporting

from_abgr_stream, from_bgr_stream, from_rgb_stream, from_rgba_stream

Methods included from Adam7Interlacing

adam7_extract_pass, adam7_merge_pass, adam7_multiplier_offset, adam7_pass_size, adam7_pass_sizes

Methods included from PNGDecoding

decode_png_pixelstream, from_blob, from_datastream, from_file, from_io

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.


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

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

Instance Attribute Details

#heightInteger (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

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

#widthInteger (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:


105
106
107
# File 'lib/chunky_png/canvas.rb', line 105

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:


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

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:


135
136
137
138
# File 'lib/chunky_png/canvas.rb', line 135

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

#areaInteger

Returns the area of this canvas in number of pixels.

Returns:

  • (Integer)

    The number of pixels in this canvas


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

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.


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

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

#dimensionChunkyPNG::Dimension

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

Returns:


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

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.


277
278
279
280
281
282
# File 'lib/chunky_png/canvas.rb', line 277

def eql?(other)
  other.is_a?(self.class) &&
    other.pixels == pixels &&
    other.width == width &&
    other.height == 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.


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

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:


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

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.


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

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.


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

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.


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

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

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


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

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.


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

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.


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

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


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

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)

  • color (Integer)

    The new color for the provided coordinates.

Returns:

  • (Integer)

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


150
151
152
# File 'lib/chunky_png/canvas.rb', line 150

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)

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


162
163
164
165
# File 'lib/chunky_png/canvas.rb', line 162

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

#to_imageChunkyPNG::Image

Creates an ChunkyPNG::Image object from this canvas.

Returns:


292
293
294
# File 'lib/chunky_png/canvas.rb', line 292

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