Module: ChunkyPNG::Canvas::Operations

Included in:
ChunkyPNG::Canvas
Defined in:
lib/chunky_png/canvas/operations.rb

Overview

The ChunkyPNG::Canvas::Operations module defines methods to perform operations on a ChunkyPNG::Canvas. The module is included into the Canvas class so all these methods are available on every canvas.

Note that some of these operations modify the canvas, while some operations return a new canvas and leave the original intact.

See Also:

Instance Method Summary collapse

Instance Method Details

#border(size, color = ChunkyPNG::Color::BLACK) ⇒ ChunkyPNG::Canvas

Draws a border around the image.

Parameters:

  • size (Integer) —

    The size of the border.

  • color (Integer) (defaults to: ChunkyPNG::Color::BLACK) —

    The color of the border.

Returns:

See Also:



362
363
364
 
# File 'lib/chunky_png/canvas/operations.rb', line 362

def border(size, color = ChunkyPNG::Color::BLACK)
  dup.border!(size, color)
end

#border!(size, color = ChunkyPNG::Color::BLACK) ⇒ ChunkyPNG::Canvas

Draws a border around the image in place.

Parameters:

  • size (Integer) —

    The size of the border.

  • color (Integer) (defaults to: ChunkyPNG::Color::BLACK) —

    The color of the border.

Returns:

See Also:



372
373
374
375
376
377
378
 
# File 'lib/chunky_png/canvas/operations.rb', line 372

def border!(size, color = ChunkyPNG::Color::BLACK)
  new_width  = width  + size * 2
  new_height = height + size * 2

  bg = Canvas.new(new_width, new_height, color).replace(self, size, size)
  replace_canvas!(new_width, new_height, bg.pixels)
end

#compose(other, offset_x = 0, offset_y = 0) ⇒ ChunkyPNG::Canvas

Note:

API changed since 1.0 - This method now no longer is in place, but returns a new canvas and leaves the original intact. Use #compose! if you want to compose on the canvas in place.

Composes another image onto this image using alpha blending. This will return a new canvas and leave the original intact.

If you simply want to replace pixels or when the other image does not have transparency, it is faster to use #replace.

Parameters:

  • other (ChunkyPNG::Canvas) —

    The foreground canvas to compose on the current canvas, using alpha compositing.

  • offset_x (Integer) (defaults to: 0) —

    The x-offset to apply the new foreground on.

  • offset_y (Integer) (defaults to: 0) —

    The y-offset to apply the new foreground on.

Returns:

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the other canvas doesn’t fit on this one, given the offset and size of the other canvas.

See Also:



85
86
87
 
# File 'lib/chunky_png/canvas/operations.rb', line 85

def compose(other, offset_x = 0, offset_y = 0)
  dup.compose!(other, offset_x, offset_y)
end

#compose!(other, offset_x = 0, offset_y = 0) ⇒ ChunkyPNG::Canvas

Composes another image onto this image using alpha blending. This will modify the current canvas.

If you simply want to replace pixels or when the other image does not have transparency, it is faster to use #replace!.

Parameters:

  • other (ChunkyPNG::Canvas) —

    The foreground canvas to compose on the current canvas, using alpha compositing.

  • offset_x (Integer) (defaults to: 0) —

    The x-offset to apply the new foreground on.

  • offset_y (Integer) (defaults to: 0) —

    The y-offset to apply the new foreground on.

Returns:

  • (ChunkyPNG::Canvas) —

    Returns itself, but with the other canvas composed onto it.

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the other canvas doesn’t fit on this one, given the offset and size of the other canvas.

See Also:



54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/chunky_png/canvas/operations.rb', line 54

def compose!(other, offset_x = 0, offset_y = 0)
  check_size_constraints!(other, offset_x, offset_y)

  for y in 0...other.height do
    for x in 0...other.width do
      set_pixel(x + offset_x,
                y + offset_y,
                ChunkyPNG::Color.compose(other.get_pixel(x, y),
                                         get_pixel(x + offset_x,
                                                   y + offset_y)))
    end
  end
  self
end

#crop(x, y, crop_width, crop_height) ⇒ ChunkyPNG::Canvas

Crops an image, given the coordinates and size of the image that needs to be cut out. This will leave the original image intact and return a new, cropped image with pixels copied from the original image.

Parameters:

  • x (Integer) —

    The x-coordinate of the top left corner of the image to be cropped.

  • y (Integer) —

    The y-coordinate of the top left corner of the image to be cropped.

  • crop_width (Integer) —

    The width of the image to be cropped.

  • crop_height (Integer) —

    The height of the image to be cropped.

Returns:

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the crop dimensions plus the given coordinates are bigger then the original image.



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

def crop(x, y, crop_width, crop_height)
  dup.crop!(x, y, crop_width, crop_height)
end

#crop!(x, y, crop_width, crop_height) ⇒ ChunkyPNG::Canvas

Crops an image, given the coordinates and size of the image that needs to be cut out.

This will change the size and content of the current canvas. Use #crop if you want to have a new canvas returned instead, leaving the current canvas intact.

Parameters:

  • x (Integer) —

    The x-coordinate of the top left corner of the image to be cropped.

  • y (Integer) —

    The y-coordinate of the top left corner of the image to be cropped.

  • crop_width (Integer) —

    The width of the image to be cropped.

  • crop_height (Integer) —

    The height of the image to be cropped.

Returns:

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the crop dimensions plus the given coordinates are bigger then the original image.



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/chunky_png/canvas/operations.rb', line 170

def crop!(x, y, crop_width, crop_height)
  if crop_width + x > width
    raise ChunkyPNG::OutOfBounds, 'Original image width is too small!'
  end
  if crop_height + y > height
    raise ChunkyPNG::OutOfBounds, 'Original image height is too small!'
  end

  if crop_width == width && x == 0
    # We only need to crop off the top and/or bottom, so we can take a
    # shortcut.
    replace_canvas!(crop_width, crop_height,
                    pixels.slice(y * width, width * crop_height))
  else
    new_pixels = []
    for cy in 0...crop_height do
      new_pixels.concat pixels.slice((cy + y) * width + x, crop_width)
    end
    replace_canvas!(crop_width, crop_height, new_pixels)
  end
end

#flip_horizontally ⇒ ChunkyPNG::Canvas Also known as: flip

Flips the image horizontally, leaving the original intact.

This will flip the image on its horizontal axis, e.g. pixels on the top will now be pixels on the bottom. Chaining this method twice will return the original canvas. This method will leave the original object intact and return a new canvas.

Returns:

See Also:



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

def flip_horizontally
  dup.flip_horizontally!
end

#flip_horizontally! ⇒ ChunkyPNG::Canvas Also known as: flip!

Flips the image horizontally in place.

This will flip the image on its horizontal axis, e.g. pixels on the top will now be pixels on the bottom. Chaining this method twice will return the original canvas. This method will leave the original object intact and return a new canvas.

Returns:

See Also:



214
215
216
217
218
219
220
221
222
 
# File 'lib/chunky_png/canvas/operations.rb', line 214

def flip_horizontally!
  for y in 0..((height - 1) >> 1) do
    other_y   = height - (y + 1)
    other_row = row(other_y)
    replace_row!(other_y, row(y))
    replace_row!(y, other_row)
  end
  self
end

#flip_vertically ⇒ ChunkyPNG::Canvas Also known as: mirror

Flips the image vertically, leaving the original intact.

This will flip the image on its vertical axis, e.g. pixels on the left will now be pixels on the right. Chaining this method twice will return the original canvas. This method will leave the original object intact and return a new canvas.

Returns:

See Also:



236
237
238
 
# File 'lib/chunky_png/canvas/operations.rb', line 236

def flip_vertically
  dup.flip_vertically!
end

#flip_vertically! ⇒ ChunkyPNG::Canvas Also known as: mirror!

Flips the image vertically in place.

This will flip the image on its vertical axis, e.g. pixels on the left will now be pixels on the right. Chaining this method twice will return the original canvas. This method will leave the original object intact and return a new canvas.

Returns:

See Also:



249
250
251
252
253
254
 
# File 'lib/chunky_png/canvas/operations.rb', line 249

def flip_vertically!
  for y in 0...height do
    replace_row!(y, row(y).reverse)
  end
  self
end

#grayscale ⇒ ChunkyPNG::Canvas

Converts the canvas to grayscale, returning a new canvas.

This method will not modify the canvas. To modift the current canvas, use #grayscale! instead.

Returns:

See Also:

  • ChunkyPNG::Canvas::Operations.{{#grayscale!}
  • ChunkyPNG::Canvas::Operations.{ChunkyPNG{ChunkyPNG::Color{ChunkyPNG::Color#to_grayscale}


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

def grayscale
  dup.grayscale!
end

#grayscale! ⇒ ChunkyPNG::Canvas

Converts the canvas to grayscale.

This method will modify the canvas. The obtain a new canvas and leave the current instance intact, use #grayscale instead.

Returns:

See Also:

  • ChunkyPNG::Canvas::Operations.{{#grayscale}
  • ChunkyPNG::Canvas::Operations.{ChunkyPNG{ChunkyPNG::Color{ChunkyPNG::Color#to_grayscale}


20
21
22
23
 
# File 'lib/chunky_png/canvas/operations.rb', line 20

def grayscale!
  pixels.map! { |pixel| ChunkyPNG::Color.to_grayscale(pixel) }
  self
end

#replace(other, offset_x = 0, offset_y = 0) ⇒ ChunkyPNG::Canvas

Note:

API changed since 1.0 - This method now no longer is in place, but returns a new canvas and leaves the original intact. Use #replace! if you want to replace pixels on the canvas in place.

Replaces pixels on this image by pixels from another pixels, on a given offset. This method will modify the current canvas.

This will completely replace the pixels of the background image. If you want to blend them with semi-transparent pixels from the foreground image, see #compose!.

Parameters:

  • other (ChunkyPNG::Canvas) —

    The foreground canvas to get the pixels from.

  • offset_x (Integer) (defaults to: 0) —

    The x-offset to apply the new foreground on.

  • offset_y (Integer) (defaults to: 0) —

    The y-offset to apply the new foreground on.

Returns:

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the other canvas doesn’t fit on this one, given the offset and size of the other canvas.

See Also:



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

def replace(other, offset_x = 0, offset_y = 0)
  dup.replace!(other, offset_x, offset_y)
end

#replace!(other, offset_x = 0, offset_y = 0) ⇒ ChunkyPNG::Canvas

Replaces pixels on this image by pixels from another pixels, on a given offset. This method will modify the current canvas.

This will completely replace the pixels of the background image. If you want to blend them with semi-transparent pixels from the foreground image, see #compose!.

Parameters:

  • other (ChunkyPNG::Canvas) —

    The foreground canvas to get the pixels from.

  • offset_x (Integer) (defaults to: 0) —

    The x-offset to apply the new foreground on.

  • offset_y (Integer) (defaults to: 0) —

    The y-offset to apply the new foreground on.

Returns:

Raises:

  • (ChunkyPNG::OutOfBounds) —

    when the other canvas doesn’t fit on this one, given the offset and size of the other canvas.

See Also:



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/chunky_png/canvas/operations.rb', line 106

def replace!(other, offset_x = 0, offset_y = 0)
  check_size_constraints!(other, offset_x, offset_y)

  for y in 0...other.height do
    for d in 0...other.width
      pixels[(y + offset_y) * width + offset_x + d] = other.pixels[y * other.width + d]
    end
  end
  self
end

#rotate_180 ⇒ ChunkyPNG::Canvas

Rotates the image 180 degrees.

This method will leave the original object intact and return a new canvas.

Returns:

See Also:



318
319
320
 
# File 'lib/chunky_png/canvas/operations.rb', line 318

def rotate_180
  dup.rotate_180!
end

#rotate_180! ⇒ ChunkyPNG::Canvas

Rotates the image 180 degrees in place.

Returns:

See Also:



326
327
328
329
 
# File 'lib/chunky_png/canvas/operations.rb', line 326

def rotate_180!
  pixels.reverse!
  self
end

#rotate_left ⇒ ChunkyPNG::Canvas Also known as: rotate_counter_clockwise

Returns an image that is rotated 90 degrees counter-clockwise.

This method will leave the original object intact and return a new canvas.

Returns:

See Also:



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

def rotate_left
  dup.rotate_left!
end

#rotate_left! ⇒ ChunkyPNG::Canvas Also known as: rotate_counter_clockwise!

Rotates the image 90 degrees counter-clockwise in place.

This method will change the original canvas. See #rotate_left for a version that leaves the canvas intact and returns a new rotated canvas instead.

Returns:



302
303
304
305
306
 
# File 'lib/chunky_png/canvas/operations.rb', line 302

def rotate_left!
  new_pixels = []
  (width - 1).downto(0) { |i| new_pixels += column(i) }
  replace_canvas!(height, width, new_pixels)
end

#rotate_right ⇒ ChunkyPNG::Canvas Also known as: rotate_clockwise

Returns a new canvas instance that is rotated 90 degrees clockwise.

This method will return a new canvas and leaves the original intact.

Returns:

See Also:



265
266
267
 
# File 'lib/chunky_png/canvas/operations.rb', line 265

def rotate_right
  dup.rotate_right!
end

#rotate_right! ⇒ ChunkyPNG::Canvas Also known as: rotate_clockwise!

Rotates the image 90 degrees clockwise in place.

This method will change the current canvas.

Returns:

See Also:



275
276
277
278
279
 
# File 'lib/chunky_png/canvas/operations.rb', line 275

def rotate_right!
  new_pixels = []
  0.upto(width - 1) { |i| new_pixels += column(i).reverse }
  replace_canvas!(height, width, new_pixels)
end

#trim(border = pixels.first) ⇒ ChunkyPNG::Canvas

Trims the border around the image, presumed to be the color of the first pixel.

Parameters:

  • border (Integer) (defaults to: pixels.first) —

    The color to attempt to trim.

Returns:

See Also:



337
338
339
 
# File 'lib/chunky_png/canvas/operations.rb', line 337

def trim(border = pixels.first)
  dup.trim!
end

#trim!(border = pixels.first) ⇒ ChunkyPNG::Canvas

Trims the border around the image in place.

Parameters:

  • border (Integer) (defaults to: pixels.first) —

    The color to attempt to trim.

Returns:

See Also:



347
348
349
350
351
352
353
354
 
# File 'lib/chunky_png/canvas/operations.rb', line 347

def trim!(border = pixels.first)
  x1 = [*0...width].index   { |c| column(c).uniq != [border] }
  x2 = [*0...width].rindex  { |c| column(c).uniq != [border] }
  y1 = [*0...height].index  { |r|    row(r).uniq != [border] }
  y2 = [*0...height].rindex { |r|    row(r).uniq != [border] }

  crop! x1, y1, x2 - x1 + 1, y2 - y1 + 1
end