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/masking.rb,
lib/chunky_png/canvas/drawing.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_importing.rb,
lib/chunky_png/canvas/stream_exporting.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 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.



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

#heightInteger (readonly)



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

def height
  @height
end

#pixelsArray<ChunkyPNG::Color> (readonly)



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

def pixels
  @pixels
end

#widthInteger (readonly)



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.



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.

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.

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

#areaInteger

Returns the area of this canvas in number of pixels.



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.



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

#dimensionChunkyPNG::Dimension

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



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.



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.



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

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



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



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



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

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

#paletteChunkyPNG::Palette

Returns the palette used for this canvas.



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.



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.



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



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.



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.



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_imageChunkyPNG::Image

Creates an ChunkyPNG::Image object from this canvas.



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

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