module ChunkyPNG::Canvas::Operations
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 ChunkyPNG::Canvas
Public Instance Methods
Draws a border around the image.
@param [Integer] size The size of the border. @param [Integer] color The color of the border. @return [ChunkyPNG::Canvas] Returns a bordered version of the image. @see border!
# File lib/chunky_png/canvas/operations.rb 362 def border(size, color = ChunkyPNG::Color::BLACK) 363 dup.border!(size, color) 364 end
Draws a border around the image in place.
@param [Integer] size The size of the border. @param [Integer] color The color of the border. @return [ChunkyPNG::Canvas] Returns itself with the border added. @see border
# File lib/chunky_png/canvas/operations.rb 372 def border!(size, color = ChunkyPNG::Color::BLACK) 373 new_width = width + size * 2 374 new_height = height + size * 2 375 376 bg = Canvas.new(new_width, new_height, color).replace(self, size, size) 377 replace_canvas!(new_width, new_height, bg.pixels) 378 end
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}.
@param (see compose!
) @return [ChunkyPNG::Canvas] Returns the new canvas, composed of the
other 2
@raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
this one, given the offset and size of the other 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.
@see replace
# File lib/chunky_png/canvas/operations.rb 85 def compose(other, offset_x = 0, offset_y = 0) 86 dup.compose!(other, offset_x, offset_y) 87 end
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!}.
@param [ChunkyPNG::Canvas] other The foreground canvas to compose on
the current canvas, using alpha compositing.
@param [Integer] offset_x The x-offset to apply the new foreground on. @param [Integer] offset_y The y-offset to apply the new foreground on. @return [ChunkyPNG::Canvas] Returns itself, but with the other canvas
composed onto it.
@raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
this one, given the offset and size of the other canvas.
# File lib/chunky_png/canvas/operations.rb 54 def compose!(other, offset_x = 0, offset_y = 0) 55 check_size_constraints!(other, offset_x, offset_y) 56 57 for y in 0...other.height do 58 for x in 0...other.width do 59 set_pixel(x + offset_x, 60 y + offset_y, 61 ChunkyPNG::Color.compose(other.get_pixel(x, y), 62 get_pixel(x + offset_x, 63 y + offset_y))) 64 end 65 end 66 self 67 end
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.
@param [Integer] x The x-coordinate of the top left corner of the image
to be cropped.
@param [Integer] y The y-coordinate of the top left corner of the image
to be cropped.
@param [Integer] crop_width The width of the image to be cropped. @param [Integer] crop_height The height of the image to be cropped. @return [ChunkyPNG::Canvas] Returns the newly created cropped image. @raise [ChunkyPNG::OutOfBounds] when the crop dimensions plus the given
coordinates are bigger then the original image.
# File lib/chunky_png/canvas/operations.rb 150 def crop(x, y, crop_width, crop_height) 151 dup.crop!(x, y, crop_width, crop_height) 152 end
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.
@param [Integer] x The x-coordinate of the top left corner of the image
to be cropped.
@param [Integer] y The y-coordinate of the top left corner of the image
to be cropped.
@param [Integer] crop_width The width of the image to be cropped. @param [Integer] crop_height The height of the image to be cropped. @return [ChunkyPNG::Canvas] Returns itself, but cropped. @raise [ChunkyPNG::OutOfBounds] when the crop dimensions plus the given
coordinates are bigger then the original image.
# File lib/chunky_png/canvas/operations.rb 170 def crop!(x, y, crop_width, crop_height) 171 if crop_width + x > width 172 raise ChunkyPNG::OutOfBounds, 'Original image width is too small!' 173 end 174 if crop_height + y > height 175 raise ChunkyPNG::OutOfBounds, 'Original image height is too small!' 176 end 177 178 if crop_width == width && x == 0 179 # We only need to crop off the top and/or bottom, so we can take a 180 # shortcut. 181 replace_canvas!(crop_width, crop_height, 182 pixels.slice(y * width, width * crop_height)) 183 else 184 new_pixels = [] 185 for cy in 0...crop_height do 186 new_pixels.concat pixels.slice((cy + y) * width + x, crop_width) 187 end 188 replace_canvas!(crop_width, crop_height, new_pixels) 189 end 190 end
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.
@return [ChunkyPNG::Canvas] The flipped image @see flip_horizontally!
# File lib/chunky_png/canvas/operations.rb 201 def flip_horizontally 202 dup.flip_horizontally! 203 end
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.
@return [ChunkyPNG::Canvas] Itself, but flipped @see flip_horizontally
# File lib/chunky_png/canvas/operations.rb 214 def flip_horizontally! 215 for y in 0..((height - 1) >> 1) do 216 other_y = height - (y + 1) 217 other_row = row(other_y) 218 replace_row!(other_y, row(y)) 219 replace_row!(y, other_row) 220 end 221 self 222 end
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.
@return [ChunkyPNG::Canvas] The flipped image @see flip_vertically!
# File lib/chunky_png/canvas/operations.rb 236 def flip_vertically 237 dup.flip_vertically! 238 end
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.
@return [ChunkyPNG::Canvas] Itself, but flipped @see flip_vertically
# File lib/chunky_png/canvas/operations.rb 249 def flip_vertically! 250 for y in 0...height do 251 replace_row!(y, row(y).reverse) 252 end 253 self 254 end
Converts the canvas to grayscale, returning a new canvas.
This method will not modify the canvas. To modift the current canvas, use {#grayscale!} instead.
@return [ChunkyPNG::Canvas] A copy of the canvas, converted to
grayscale.
@see {#grayscale!} @see {ChunkyPNG::Color#to_grayscale}
# File lib/chunky_png/canvas/operations.rb 34 def grayscale 35 dup.grayscale! 36 end
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.
@return [ChunkyPNG::Canvas] Returns itself, converted to grayscale. @see {#grayscale} @see {ChunkyPNG::Color#to_grayscale}
# File lib/chunky_png/canvas/operations.rb 20 def grayscale! 21 pixels.map! { |pixel| ChunkyPNG::Color.to_grayscale(pixel) } 22 self 23 end
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!}.
@param (see replace!
) @return [ChunkyPNG::Canvas] Returns a new, combined canvas. @raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
this one, given the offset and size of the other 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.
@see compose
# File lib/chunky_png/canvas/operations.rb 133 def replace(other, offset_x = 0, offset_y = 0) 134 dup.replace!(other, offset_x, offset_y) 135 end
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!}.
@param [ChunkyPNG::Canvas] other The foreground canvas to get the
pixels from.
@param [Integer] offset_x The x-offset to apply the new foreground on. @param [Integer] offset_y The y-offset to apply the new foreground on. @return [ChunkyPNG::Canvas] Returns itself, but with the other canvas
placed onto it.
@raise [ChunkyPNG::OutOfBounds] when the other canvas doesn't fit on
this one, given the offset and size of the other canvas.
# File lib/chunky_png/canvas/operations.rb 106 def replace!(other, offset_x = 0, offset_y = 0) 107 check_size_constraints!(other, offset_x, offset_y) 108 109 for y in 0...other.height do 110 for d in 0...other.width 111 pixels[(y + offset_y) * width + offset_x + d] = other.pixels[y * other.width + d] 112 end 113 end 114 self 115 end
Rotates the image 180 degrees.
This method will leave the original object intact and return a new canvas.
@return [ChunkyPNG::Canvas] The rotated image. @see rotate_180!
# File lib/chunky_png/canvas/operations.rb 318 def rotate_180 319 dup.rotate_180! 320 end
Rotates the image 180 degrees in place.
@return [ChunkyPNG::Canvas] Itself, but rotated 180 degrees. @see rotate_180
# File lib/chunky_png/canvas/operations.rb 326 def rotate_180! 327 pixels.reverse! 328 self 329 end
Returns an image that is rotated 90 degrees counter-clockwise.
This method will leave the original object intact and return a new canvas.
@return [ChunkyPNG::Canvas] A rotated copy of itself. @see rotate_left!
for the in-place version.
# File lib/chunky_png/canvas/operations.rb 291 def rotate_left 292 dup.rotate_left! 293 end
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.
@return [ChunkyPNG::Canvas] Itself, but rotated.
# File lib/chunky_png/canvas/operations.rb 302 def rotate_left! 303 new_pixels = [] 304 (width - 1).downto(0) { |i| new_pixels += column(i) } 305 replace_canvas!(height, width, new_pixels) 306 end
Returns a new canvas instance that is rotated 90 degrees clockwise.
This method will return a new canvas and leaves the original intact.
@return [ChunkyPNG::Canvas] A clockwise-rotated copy. @see rotate_right!
for the in place version.
# File lib/chunky_png/canvas/operations.rb 265 def rotate_right 266 dup.rotate_right! 267 end
Rotates the image 90 degrees clockwise in place.
This method will change the current canvas.
@return [ChunkyPNG::Canvas] Itself, but rotated clockwise. @see rotate_right
for a version that leaves the current canvas intact
# File lib/chunky_png/canvas/operations.rb 275 def rotate_right! 276 new_pixels = [] 277 0.upto(width - 1) { |i| new_pixels += column(i).reverse } 278 replace_canvas!(height, width, new_pixels) 279 end
Trims the border around the image, presumed to be the color of the first pixel.
@param [Integer] border The color to attempt to trim. @return [ChunkyPNG::Canvas] The trimmed image. @see trim!
# File lib/chunky_png/canvas/operations.rb 337 def trim(border = pixels.first) 338 dup.trim! 339 end
Trims the border around the image in place.
@param [Integer] border The color to attempt to trim. @return [ChunkyPNG::Canvas] Returns itself, but with the border
trimmed.
@see trim
# File lib/chunky_png/canvas/operations.rb 347 def trim!(border = pixels.first) 348 x1 = [*0...width].index { |c| column(c).uniq != [border] } 349 x2 = [*0...width].rindex { |c| column(c).uniq != [border] } 350 y1 = [*0...height].index { |r| row(r).uniq != [border] } 351 y2 = [*0...height].rindex { |r| row(r).uniq != [border] } 352 353 crop! x1, y1, x2 - x1 + 1, y2 - y1 + 1 354 end
Protected Instance Methods
Checks whether another image has the correct dimension to be used for an operation on the current image, given an offset coordinate to work with. @param [ChunkyPNG::Canvas] other The other canvas @param [Integer] offset_x The x offset on which the other image will be
applied.
@param [Integer] offset_y The y offset on which the other image will be
applied.
@raise [ChunkyPNG::OutOfBounds] when the other image doesn't fit.
# File lib/chunky_png/canvas/operations.rb 391 def check_size_constraints!(other, offset_x, offset_y) 392 if width < other.width + offset_x 393 raise ChunkyPNG::OutOfBounds, 'Background image width is too small!' 394 end 395 if height < other.height + offset_y 396 raise ChunkyPNG::OutOfBounds, 'Background image height is too small!' 397 end 398 end