Module ChunkyPNG::Canvas::Operations
In: lib/chunky_png/canvas/operations.rb

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

Methods

Public Instance methods

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

[Source]

    # File lib/chunky_png/canvas/operations.rb, line 80
80:       def compose(other, offset_x = 0, offset_y = 0)
81:         dup.compose!(other, offset_x, offset_y)
82:       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.

@see replace! @see compose

[Source]

    # File lib/chunky_png/canvas/operations.rb, line 54
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, y + offset_y, ChunkyPNG::Color.compose(other.get_pixel(x, y), get_pixel(x + offset_x, y + offset_y)))
60:           end
61:         end
62:         self
63:       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.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 139
139:       def crop(x, y, crop_width, crop_height)
140:         dup.crop!(x, y, crop_width, crop_height)
141:       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.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 155
155:       def crop!(x, y, crop_width, crop_height)
156:         
157:         raise ChunkyPNG::OutOfBounds, "Image width is too small!" if crop_width + x > width
158:         raise ChunkyPNG::OutOfBounds, "Image width is too small!" if crop_height + y > height
159:         
160:         new_pixels = []
161:         for cy in 0...crop_height do
162:           new_pixels += pixels.slice((cy + y) * width + x, crop_width)
163:         end
164:         replace_canvas!(crop_width, crop_height, new_pixels)
165:       end
flip()

Alias for flip_horizontally

flip!()

Alias for flip_horizontally!

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!

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 175
175:       def flip_horizontally
176:         dup.flip_horizontally!
177:       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

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 187
187:       def flip_horizontally!
188:         for y in 0..((height - 1) >> 1) do
189:           other_y   = height - (y + 1)
190:           other_row = row(other_y)
191:           replace_row!(other_y, row(y))
192:           replace_row!(y, other_row)
193:         end
194:         return self
195:       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!

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 208
208:       def flip_vertically
209:         dup.flip_vertically!
210:       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

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 220
220:       def flip_vertically!
221:         for y in 0...height do
222:           replace_row!(y, row(y).reverse)
223:         end
224:         return self
225:       end

Converts the canvas to grascale, 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 grasycale. @see {grayscale!} @see {ChunkyPNG::Color#to_grayscale}

[Source]

    # File lib/chunky_png/canvas/operations.rb, line 35
35:       def grayscale
36:         dup.grayscale!
37:       end

Converts the canvas to grascale.

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}

[Source]

    # File lib/chunky_png/canvas/operations.rb, line 22
22:       def grayscale!
23:         pixels.map! { |pixel| ChunkyPNG::Color.to_grayscale(pixel) }
24:         return self
25:       end
mirror()

Alias for flip_vertically

mirror!()

Alias for flip_vertically!

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

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 124
124:       def replace(other, offset_x = 0, offset_y = 0)
125:         dup.replace!(other, offset_x, offset_y)
126:       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.

@see compose! @see replace

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 98
 98:       def replace!(other, offset_x = 0, offset_y = 0)
 99:         check_size_constraints!(other, offset_x, offset_y)
100: 
101:         for y in 0...other.height do
102:           for d in 0...other.width
103:             pixels[(y + offset_y) * width + offset_x + d] = other.pixels[y * other.width + d]
104:           end
105:         end
106:         self
107:       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!

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 287
287:       def rotate_180
288:         dup.rotate_180!
289:       end

Rotates the image 180 degrees in place.

@return [ChunkyPNG::Canvas] Itself, but rotated 180 degrees. @see rotate_180

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 295
295:       def rotate_180!
296:         pixels.reverse!
297:         return self
298:       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!

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

This method will leave the original object intact and return a new canvas. See {rotate_left!} for the in place version.

@return [ChunkyPNG::Canvas] A rotated copy of itself.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 262
262:       def rotate_left
263:         dup.rotate_left!
264:       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.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 273
273:       def rotate_left!
274:         new_pixels = []
275:         (width - 1).downto(0) { |i| new_pixels += column(i) }
276:         replace_canvas!(height, width, new_pixels)
277:       end

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

This method will return a new canvas and leaves the original intact. See {rotate_right!} for the in place version.

@return [ChunkyPNG::Canvas] A clockwise-rotated copy.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 236
236:       def rotate_right
237:         dup.rotate_right!
238:       end

Rotates the image 90 degrees clockwise in place.

This method will change the current canvas. See {rotate_right} for a version that leaves th current canvas intact

@return [ChunkyPNG::Canvas] Itself, but rotated clockwise.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 246
246:       def rotate_right!
247:         rotated = self.class.new(height, width)
248:         new_pixels = []
249:         0.upto(width - 1) { |i| new_pixels += column(i).reverse }
250:         replace_canvas!(height, width, new_pixels)
251:       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.

[Source]

     # File lib/chunky_png/canvas/operations.rb, line 308
308:       def check_size_constraints!(other, offset_x, offset_y)
309:         raise ChunkyPNG::OutOfBounds, "Background image width is too small!"  if width  < other.width  + offset_x
310:         raise ChunkyPNG::OutOfBounds, "Background image height is too small!" if height < other.height + offset_y
311:       end

[Validate]