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

border(size, color = ChunkyPNG::Color::BLACK) click to toggle source

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
366 def border(size, color = ChunkyPNG::Color::BLACK)
367   dup.border!(size, color)
368 end
border!(size, color = ChunkyPNG::Color::BLACK) click to toggle source

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
376 def border!(size, color = ChunkyPNG::Color::BLACK)
377   new_width  = width  + size * 2
378   new_height = height + size * 2
379 
380   bg = Canvas.new(new_width, new_height, color).replace(self, size, size)
381   replace_canvas!(new_width, new_height, bg.pixels)
382 end
compose(other, offset_x = 0, offset_y = 0) click to toggle source

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
90 def compose(other, offset_x = 0, offset_y = 0)
91   dup.compose!(other, offset_x, offset_y)
92 end
compose!(other, offset_x = 0, offset_y = 0) click to toggle source

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.

@see replace! @see compose

   # File lib/chunky_png/canvas/operations.rb
56 def compose!(other, offset_x = 0, offset_y = 0)
57   check_size_constraints!(other, offset_x, offset_y)
58 
59   for y in 0...other.height do
60     for x in 0...other.width do
61       set_pixel(
62         x + offset_x,
63         y + offset_y,
64         ChunkyPNG::Color.compose(
65           other.get_pixel(x, y),
66           get_pixel(x + offset_x, y + offset_y)
67         )
68       )
69     end
70   end
71   self
72 end
crop(x, y, crop_width, crop_height) click to toggle source

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
155 def crop(x, y, crop_width, crop_height)
156   dup.crop!(x, y, crop_width, crop_height)
157 end
crop!(x, y, crop_width, crop_height) click to toggle source

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
175 def crop!(x, y, crop_width, crop_height)
176   if crop_width + x > width
177     raise ChunkyPNG::OutOfBounds, "Original image width is too small!"
178   end
179   if crop_height + y > height
180     raise ChunkyPNG::OutOfBounds, "Original image height is too small!"
181   end
182 
183   if crop_width == width && x == 0
184     # We only need to crop off the top and/or bottom, so we can take a
185     # shortcut.
186     replace_canvas!(crop_width, crop_height, pixels.slice(y * width, width * crop_height))
187   else
188     new_pixels = []
189     for cy in 0...crop_height do
190       new_pixels.concat pixels.slice((cy + y) * width + x, crop_width)
191     end
192     replace_canvas!(crop_width, crop_height, new_pixels)
193   end
194 end
flip()
Alias for: flip_horizontally
flip!()
Alias for: flip_horizontally!
flip_horizontally() click to toggle source

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
205 def flip_horizontally
206   dup.flip_horizontally!
207 end
Also aliased as: flip
flip_horizontally!() click to toggle source

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
218 def flip_horizontally!
219   for y in 0..((height - 1) >> 1) do
220     other_y   = height - (y + 1)
221     other_row = row(other_y)
222     replace_row!(other_y, row(y))
223     replace_row!(y, other_row)
224   end
225   self
226 end
Also aliased as: flip!
flip_vertically() click to toggle source

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
240 def flip_vertically
241   dup.flip_vertically!
242 end
Also aliased as: mirror
flip_vertically!() click to toggle source

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
253 def flip_vertically!
254   for y in 0...height do
255     replace_row!(y, row(y).reverse)
256   end
257   self
258 end
Also aliased as: mirror!
grayscale() click to toggle source

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
36 def grayscale
37   dup.grayscale!
38 end
grayscale!() click to toggle source

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
22 def grayscale!
23   pixels.map! { |pixel| ChunkyPNG::Color.to_grayscale(pixel) }
24   self
25 end
mirror()
Alias for: flip_vertically
mirror!()
Alias for: flip_vertically!
replace(other, offset_x = 0, offset_y = 0) click to toggle source

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
138 def replace(other, offset_x = 0, offset_y = 0)
139   dup.replace!(other, offset_x, offset_y)
140 end
replace!(other, offset_x = 0, offset_y = 0) click to toggle source

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.

@see compose! @see replace

    # File lib/chunky_png/canvas/operations.rb
111 def replace!(other, offset_x = 0, offset_y = 0)
112   check_size_constraints!(other, offset_x, offset_y)
113 
114   for y in 0...other.height do
115     for d in 0...other.width
116       pixels[(y + offset_y) * width + offset_x + d] = other.pixels[y * other.width + d]
117     end
118   end
119   self
120 end
rotate_180() click to toggle source

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
322 def rotate_180
323   dup.rotate_180!
324 end
rotate_180!() click to toggle source

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
330 def rotate_180!
331   pixels.reverse!
332   self
333 end
rotate_clockwise()
Alias for: rotate_right
rotate_clockwise!()
Alias for: rotate_right!
rotate_counter_clockwise()
Alias for: rotate_left
rotate_counter_clockwise!()
Alias for: rotate_left!
rotate_left() click to toggle source

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
295 def rotate_left
296   dup.rotate_left!
297 end
Also aliased as: rotate_counter_clockwise
rotate_left!() click to toggle source

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
306 def rotate_left!
307   new_pixels = []
308   (width - 1).downto(0) { |i| new_pixels += column(i) }
309   replace_canvas!(height, width, new_pixels)
310 end
Also aliased as: rotate_counter_clockwise!
rotate_right() click to toggle source

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
269 def rotate_right
270   dup.rotate_right!
271 end
Also aliased as: rotate_clockwise
rotate_right!() click to toggle source

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
279 def rotate_right!
280   new_pixels = []
281   0.upto(width - 1) { |i| new_pixels += column(i).reverse }
282   replace_canvas!(height, width, new_pixels)
283 end
Also aliased as: rotate_clockwise!
trim(border = pixels.first) click to toggle source

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
341 def trim(border = pixels.first)
342   dup.trim!
343 end
trim!(border = pixels.first) click to toggle source

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
351 def trim!(border = pixels.first)
352   x1 = [*0...width].index   { |c| column(c).uniq != [border] }
353   x2 = [*0...width].rindex  { |c| column(c).uniq != [border] }
354   y1 = [*0...height].index  { |r|    row(r).uniq != [border] }
355   y2 = [*0...height].rindex { |r|    row(r).uniq != [border] }
356 
357   crop! x1, y1, x2 - x1 + 1, y2 - y1 + 1
358 end

Protected Instance Methods

check_size_constraints!(other, offset_x, offset_y) click to toggle source

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
395 def check_size_constraints!(other, offset_x, offset_y)
396   if width < other.width + offset_x
397     raise ChunkyPNG::OutOfBounds, "Background image width is too small!"
398   end
399   if height < other.height + offset_y
400     raise ChunkyPNG::OutOfBounds, "Background image height is too small!"
401   end
402 end