RMagick User's Guide and Reference
class Image (class and instance methods)

Table Of Contents

class methods

instance methods

class methods

capture Image.capture(silent=false, frame=false, descend=false, screen=false, borders=false) [ { optional arguments } ] -> anImage
Description

Reads an image from an X Window.

In the optional arguments, you can set the filename attribute to "root", a numeric window ID, or a window name. If you don't set filename to any value, capture performs an interactive capture. Either click the desired window or press a mouse button and drag to draw the desired rectangle.

Arguments
silent
If true, suppress the beeps that signal the start and finish of the capture process. The bell rings once to signal the start of the capture and twice to signal the finish.
frame
If true, include the window frame.
descend
If true, obtain image by descending window hierarchy.
screen
If true, specifies that the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent windows but appear over the specified window.
borders
If true, include the border in the image.
Returns An new image.
Example
img = Magick::Image.capture {
    self.filename = "root"
    }
constitute Image.constitute(width, height, map, pixels) -> anImage
Description

Creates an image from an array of pixels.

Arguments
width
The number of columns in the image
height
The number of rows in the image
map
A string describing the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
pixels
The pixel data. The pixel data in the array must be stored in scanline order, left-to-right and top-to-bottom. The elements in the array must be either all Integers or all Floats. If the elements are Integers, the Integers must be in the range [0..MaxRGB]. If the elements are Floats, they must be in the range [0..1].
Returns An image constructed from the pixel data.
Example constitute example
×Magick API ConstituteImage
See also dispatch, import_pixels, store_pixels
Advanced

This method is the reverse of dispatch.

Since all the pixel data must be in memory at once, constitute is useful for constructing only relatively small images, or processing large images in many small chunks. For medium-to-large images, use set_pixels instead.

Also, constitute is as slow as Christmas.

Notes This method is deprecated in ImageMagick 5.5.7 and later. Use the import_pixels method instead.
from_blob Image.from_blob(aString) [ { optional arguments } ] -> anArray
Description Creates an array of images from a BLOB, that is, a Binary Large OBject. In RMagick, a BLOB is a string.
Arguments A string produced by the to_blob method. Control the format of the created image(s) by setting additional Image::Info attributes in the optional block argument.
Returns An array of one or more images constructed from the BLOB.
Example See to_blob.
×Magick API BlobToImage
See also to_blob, Image#from_blob, Image#to_blob
new Image.new(width, height [, fill]) [ { optional arguments } ] -> anImage
Description Creates a new instance with the specified number of columns and rows. You can specify other arguments by setting Image::Info attributes in the optional block. If the optional fill argument is not specified, the image is set to the background color.
Arguments
width
The number of columns
height
The number of rows
fill
A Fill object
Returns An image
×Magick API AllocateImage
See also ImageList.new_image
ping Image.ping(filename) [ { optional arguments } ] -> anArray
Image.ping(file) [ { optional arguments } ] -> anArray
Description Creates one or more images from the image file, omitting the pixel data. Only the attributes are stored in the images. This method is faster than read and uses less memory.
Arguments An image file name or open file object. You can specify other arguments by setting Image::Info attributes in the optional block.
Returns An array containing 0 or more images.
Example
cheetah = Magick::Image.ping("Cheetah.jpg")
                     » [Cheetah.jpg JPEG 1024x768 DirectClass 8-bit 101684b]
p cheetah[0].rows    » 768
p cheetah[0].columns » 1024
×Magick API PingImage
See also read
read Image.read(filename) [ { optional arguments } ] -> anArray
Image.read(file) [ { optional arguments } ] -> anArray
Description Creates one or more images from the image file.
Arguments An image file name or open file object. You can specify other arguments by setting Image::Info attributes in the optional block.
Returns An array containing 0 or more Image objects. If the file is a multi-image file such as an animated GIF or a Photoshop PSD file with multiple layers, the array contains an Image object for each image or layer in the file.
Example
animated = Magick::Image.read("animated.gif") »
         [animated.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b
          animated.gif[1] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b,
          animated.gif[2] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b]
×Magick API ReadImage

instance methods

[ ] image[key] -> value
Description Returns the value of the image property identified by key. An image may have any number of properties. Each property is identified by a string (or symbol) key. The property value is a string. ×Magick predefines some properties, including Label, Comment, and Signature.
Arguments The key may be a string or a symbol.
Returns The value of the property, a string.
Example mom['Label'] = 'My Mother'
×Magick API GetImageAttribute
See also [ ]=
Advanced ×Magick calls properties "attributes." I use the word "properties" to reduce the confusion with image object attributes such as rows and columns.
[ ]= image[key] = value -> image
Description Sets the value of an image property.
Arguments The key may be a string or a symbol. The value can be any string.
Example See demo.rb for an example of the use of the Label property.
×Magick API SetImageAttribute
See also [ ]
<=> image <=> anOtherImage -> -1, 0, 1
Description Compares two images and returns -1, 0, or 1 if image is less than, equal to, or greater than anOtherImage.

The value returned is the value of image.signature <=> anOtherImage.signature.

See also signature, difference
Advanced

The difference method compares images (for equality only) but also returns information about the amount two images differ, which may be more useful.

In addition to <=>, Image mixes in the Comparable module, which defines the <, <=, == >=, >, and between? methods.

adaptive_threshold (5.5.2) image.adaptive_threshold(width=3, height=3, offset=0) -> anImage
Description Selects an individual threshold for each pixel based on the range of intensity values in its local neighborhood. This allows for thresholding of an image whose global intensity histogram doesn't contain distinctive peaks
Arguments
width, height
define the width and height of the local neighborhood
offset
constant to subtract from pixel neighborhood mean
Returns A new image
Example
adaptive_threshold example The right-hand side of this image shows the effect of the adaptive_threshold method with the default arguments.
×Magick API AdaptiveThresholdImage
See also channel_threshold, random_channel_threshold, threshold
Advanced The adaptive_threshold method is only available in ImageMagick 5.5.2 and later.
add_noise image.add_noise(aNoiseType) -> anImage
Description Adds random noise to the image.
Arguments A NoiseType constant.
Returns A copy of the image with the noise added.
Example
The right-hand side of this image shows the effect of the add_noise method with the MultiplicativeGaussianNoise argument. add_noise example
×Magick API AddNoiseImage
Advanced The amount of time add_noise requires depends on the NoiseType constant.
affine_transform image.affine_transform(anAffineMatrix) -> anImage
Description Transforms the image as specified by the affine matrix.
Arguments An AffineMatrix object.
Returns A copy of the image, suitably transformed.
Example
affine_transform example The affine matrix in this example scales the receiver by -1 in both the x- and y-direction, and skews it by π/6 radians along both axes.
×Magick API AffineTransformImage
See also rotate, shear
Advanced See Coordinate system transformations in the Scalable Vector Graphics (SVG) 1.0 Specification for more information about transformation matrices.
annotate img.annotate(draw, width, height, x, y, text) [ { additional parameters } ] -> img
Description This is the same method as the annotate method in the Draw class, except that the first argument is a Draw object. Refer to the documentation for Draw#annotate for more information.
Returns self
Notes Some users feel like annotate is better placed in Image than in Draw. Okay, here it is!
blur_image image.blur_image(radius=0.0, sigma=1.0) -> anImage
Description Blurs the image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).
Returns A copy of the image with blurring added.
Example
The right-hand side of this image shows the effect of the blur_image method. blur_image example
See Also gaussian_blur, motion_blur
×Magick API BlurImage
black_threshold (5.5.7) image.black_threshold(red_channel [, green_channel[, blue_channel[, opacity_channel]]]) -> anImage
Description Forces all pixels below the threshold into black while leaving all pixels above the threshold unchanged.
Arguments Each channel argument is a number between 0 and MaxRGB. All arguments except the first may be omitted. If the green_channel or blue_channel argument is omitted, the default value is the red_channel value. If the opacity_channel argument is omitted, the default value is OpaqueOpacity.
Returns A new image.
See Also white_threshold, channel_threshold
×Magick API BlackThresholdImage
border image.border(width, height, color) -> anImage
Description Add a border around the image.
Arguments
width
Border width in pixels
height
Border height in pixels
color
Border color. Use a named color or a Pixel object.
Returns A new image.
Example border example
×Magick API BorderImage
See also frame
change_geometry image.change_geometry(aGeometryString) {|cols,rows,image| block} -> anObject
Description

The change_geometry method supports resizing a method by specifying constraints. For example, you can specify that the image should be resized such that the aspect ratio should be retained but the resulting image should be no larger than 640 pixels wide and 480 pixels tall.

The argument is an ×Magick geometry string. Change_geometry parses the string (ignoring the x and y values, if any) with respect to self. Yields to the block, passing the new width and height values. The return value is the return value of the block.

Arguments An ×Magick geometry string.
Returns whatever the block returns
Notes change_geometry! is an alias for change_geometry.
Example
mona = Magick::Image.read('MonaLisa.jpg').first
mona.change_geometry!('320x240') { |cols, rows, img|
  img.resize!(cols, rows)
  }
     
×Magick API ParseSizeString
changed? image.changed? -> true or false
Description Returns true if any pixel has been altered since the image was constituted.
×Magick API IsTaintImage
channel image.channel(aChannelType) -> anImage
Description Extracts a channel from the image. A channel is a particular color component of each pixel in the [image].
Arguments A ChannelType constant.
Returns An image in which the RGB values of all the pixels have been set to a gray corresponding to the specified channel value. For example, given a pixel in the original image with the value R=255, G=128, B=0 and the RedChannel argument, the equivalent pixel in the result image will have the value R=255, G=255, and B=255. For the BlueChannel argument, the pixel would have the value R=0, G=0, B=0.
Example
The channel image preserves the tone of the selected RGB component. channel example
×Magick API ChannelImage
channel_threshold image.channel_threshold(red_channel, [green_channel[, blue_channel[, opacity_channel]]]) -> anImage
Description Creates a high-contrast image by changing the pixels based on the intensity of each pixel channel.
Arguments Each channel argument is a number between 0 and MaxRGB. All arguments except the first may be omitted. If the green_channel or blue_channel argument is omitted, the default value is the red_channel value. If the opacity_channel argument is omitted, the default value is OpaqueOpacity.
Returns A new image
Example channel_threshold example
×Magick API ThresholdImageChannel
See also adaptive_threshold, black_threshold, random_channel_threshold, threshold, white_threshold
charcoal image.charcoal(radius=0.0, sigma=1.0) -> anImage
Description Adds a "charcoal" effect to the image. You can alter the intensity of the effect by changing the radius and sigma arguments.
Arguments
radius
The radius of the pixel neighborhood.
sigma
The standard deviation of the Gaussian, in pixels.
Returns A new image with the charcoal effect.
Example charcoal example
×Magick API CharcoalImage
chop image.chop(x, y, width, height) -> anImage
Description Removes the specified rectangle and collapses the rest of the image to fill the removed portion.
Arguments
x
The x offset of the rectangle from the upper-left corner of the image.
y
The y offset of the rectangle from the upper-left corner of the image.
width
The width of the rectangle.
height
The height of the rectangle.
Returns A new image.
Example
The darkened rectangle in the upper-left corner of the left-hand image corresponds to the rectangle that is to be chopped away. The right-hand image shows the result of chop. chop example
×Magick API ChopImage
See also crop
color_fill_to_border image.color_fill_to_border(x, y, fill) -> anImage
Description Changes any pixel that is a neighbor of the target pixel and is not the border color to the fill color.
Arguments
x, y
The target pixel's location.
fill_color
The fill color. The fill color can be either color name or a Pixel object.
Returns A new image.
Example
color_fill_to_border example The left-hand side of the circle is before the call to color_fill_to_border. The right-hand side is after filling with aquamarine, starting from the center and using black as the border color. Contrast the result with the color_floodfill example, below.
×Magick API ColorFloodfillImage
See also color_floodfill
color_floodfill image.color_floodfill(x, y, fill) -> anImage
Description Changes any pixel that is the same color and is a neighbor of the target pixel to the fill color.
Arguments
x, y
The target pixel's location.
fill_color
The fill color, either color name or a Pixel object.
Returns A new image.
Example
The left-hand side of the circle is before the call to color_floodfill. The right half is after filling with aquamarine, starting from the center. Notice that the small plum circles are not changed, unlike in the color_fill_to_border example above. color_floodfill example
×Magick API ColorFloodfillImage
See also color_fill_to_border, opaque
colorize image.colorize(red_pct, green_pct, blue_pct, [matte_pct, ] fill) -> anImage
Description Blend the fill color with the image pixels. The red_pct, green_pct, blue_pct and matte_pct arguments are the percentage to blend with the red, green, blue and matte channels.
Arguments
red_pct, green_pct, blue_pct, matte_pct
The percentage of the fill color red, green, blue and matte (tranparency) components to blend with the image pixel. For example, .25 is 25%. The matte_pct argument is optional.
fill
A color name or a Pixel structure.
Returns A new image.
Example
colorize example Convert a color image to sepia-tone using the quantize and colorize methods
×Magick API ColorizeImage
colormap image.colormap(index[, new_color]) -> aString
Description Returns the color in the color map at the specified index. If the new_color argument is specified, replaces the color at that index with the new color.
Arguments
index
A number between 0 and the number of colors in the color map. If the value is out of range, colormap raises an IndexError. You can get the number of colors in the color map from the colors attribute.
new_color
Optional. If specified, may be either a color name or a Pixel.
Returns The name of the color at the specified location in the color map.
Advanced Raises IndexError if the image does not contain a color map. Only PseudoClass images have a color map.
color_point image.color_point(x, y, fill) -> anImage
Description Set the color of the pixel at x,y to the fill color. Note: this method creates a new image object. If you must set a single pixel, use pixel_color or the Draw#point method.
Arguments
x, y
The location of the pixel.
fill
The fill color, either color name or a Pixel object.
Returns A copy of the image with the pixel set to the new color.
Example
f.color_point(50,50, red)
color_point example
×Magick API GetImagePixels, SyncImagePixels
See also pixel_color
color_reset! image.color_reset!(fill) -> image
Description Sets all the pixels in the image to the specified fill color.
Arguments The fill color, either color name or a Pixel object.
Returns The image.
Example
f.color_reset!(red)
color_reset example
×Magick API SetImage
See also erase!
composite image.composite(img, x, y, composite_op) -> anImage
image.composite(img, gravity, composite_op) -> anImage
Description Composites img onto image using the specified composite operator.
Arguments
img
Either an imagelist or an image. If an imagelist, uses the current image.
x, y
The x- and y-offset of the composited image.
gravity
A GravityType constant that specifies the location of img on image. For example, NorthwestGravity causes img to be positioned at the upper left corner of image.
composite_op
A CompositeOperator constant.
Returns A new image.
Example
This example shows the effect of some of the composite_op arguments. (The image is half-size. Click here to see the full-size image.) composite example
×Magick API CompositeImage
composite_affine image.composite(img, affine) -> anImage
Description Composite img over the receiver image as dictated by the affine matrix.
Arguments
img
An image or imagelist
affine
An AffineMatrix
Returns A new image.
×Magick API DrawAffineImage
See also composite, affine_transform
compress_colormap! image.compress_colormap! -> image
Description Removes duplicate or unused entries in the colormap. Only PseudoClass images have a colormap.
Returns self
Example
f = Magick::Image.read('cbezier1.gif').first »
         cbezier1.gif GIF 500x350+0+0 PseudoClass 128c 8-bit 177503b
f.colors » 128
f.compress_colormap! »
         cbezier1.gif GIF 500x350+0+0 PseudoClass 108c 8-bit 177503b
f.colors » 108
×Magick API CompressColormap
contrast image.contrast(sharpen=false) -> anImage
Description Enhances or reduces the intensity differences between the lighter and darker elements of the image.
Arguments If sharpen is true, the contrast is increased, otherwise it is reduced.
Returns A new image.
Example
Starting at the upper-left, the contrast is reduced in each image.
contrast example
×Magick API ContrastImage
convolve image.convolve(order, kernel) -> anImage
Description Applies a custom convolution kernel to the image.
Arguments
order
The number of columns and rows in the kernel.
kernel
An order*order matrix of Float values.
Returns A new image.
×Magick API ConvolveImage
See also The edge, emboss, gaussian_blur, motion_blur and sharpen methods use convolution to do their work.
Advanced See Convolution in the Hypermedia Image Processing Reference
copy image.copy -> anImage
Description Returns a deep copy of the image
Example f2 = f.copy
×Magick API CloneImage
See also ImageList#copy
crop image.crop(x, y, width, height) -> anImage
image.crop(gravity, width, height) -> anImage
Description Extracts the specified rectangle from the image.
Arguments
x, y
The x- and y-offset of the rectangle relative to the upper-left corner of the image, or
gravity
A GravityType constant indicating the position of the rectangle relative to the upper-left hand corner of the image.
width, height
The width and height of the rectangle.
Returns A new image containing only the specified rectangle.
Example crop example
Example 2 crop_with_gravity.rb
×Magick API CropImage
See also crop!, chop
crop! image.crop!(x, y, width, height) -> image
image.crop!(gravity, width, height) -> anImage
Description In-place form of crop.
Returns self
cycle_colormap image.cycle_colormap(amount) -> anImage
Description Displaces the colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.
Returns A new image
Arguments The number of positions to cycle.
Example
This example is an animation made from a number of copies of the original image, cycling the colormap between each copy. cycle_colormap example
×Magick API CycleColormapImage
despeckle image.despeckle -> anImage
Description Reduces the speckle noise while preserving the edges.
Returns A new image.
×Magick API DespeckleImage
difference image.difference(other) -> anArray
Description Compares two images and computes statistics about their difference.
Arguments Another image or imagelist
Returns An array of three Float values:
mean error per pixel
The mean error for any single pixel in the image.
normalized mean error
The normalized mean quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in the image.
normalized maximum error
The normalized maximum quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in your image.

A small normalized mean square error...suggests the images are very similiar in spatial layout and color.

After difference returns, these values are also available from the mean_error_per_pixel, normalized_mean_error, and normalized_maximum_error attributes.

×Magick API IsImagesEqual
See also <=>
dispatch image.dispatch(x, y, columns, rows, map, float=false) -> anArray
Description Extracts the pixel data from the specified rectangle and returns it as an array of either Integer or Float values.

The array returned by dispatch is suitable for use as an argument to constitute.

Arguments
x, y
The offset of the rectangle from the upper-left corner of the image.
columns, rows
The width and height of the rectangle.
map
A String reflecting the order of the pixel data. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
float
If true, the returned array elements will be Float values in the range 0..1. If false, the returned array elements will be Integer values in the range 0..MaxRGB.
Returns An array.
Example
#! /usr/local/bin/ruby -w
require 'RMagick'
f = Magick::Image.read("images/small.tif").first
pixels = f.dispatch(0,0,f.columns,f.rows,"RGB")
# Write the pixels to a file, to be included
# in the constitute.rb example.
File.open('pixels.r', 'w') { |txt|
        txt.puts("Width = #{f.columns}")
        txt.puts("Height = #{f.rows}")
        txt.print('Pixels = [')
        pixels = pixels.join(',')
        pixels.gsub!(/(\d+,){1,10}/) { "#{$&}\n" }
        txt.print(pixels)
        txt.puts(']')
}
exit
ImageMagick API ExportImagePixels
GraphicsMagick API DispatchImage
See also constitute, export_pixels, get_pixels
Notes This method is deprecated in ImageMagick 5.5.7 and later. Use the export_pixels method instead.
display image.display [ { optional arguments } ] -> image
Description Display the image on an X Window screen. By default, the screen is the local monitor.

Right-click the window to display a context menu.

Arguments You can specify additional arguments by setting Info attributes in a block associated with the method call. Specifically, you can set the name of a non-default X Window screen with the server_name attribute.
Returns self
×Magick API DisplayImages
edge image.edge(radius=0.0) -> anImage
Description Finds edges in the image.
Arguments The radius of the convolution filter. If the radius is 0, edge selects a suitable default.
Returns A new image.
Example
The right-hand side of the image has been altered by edge. edge example
×Magick API EdgeImage
emboss image.emboss(radius=0.0, sigma=1.0) -> anImage
Description Adds a 3-dimensional effect.
Arguments
radius
The radius of the Gaussian operator.
sigma
The sigma (standard deviation) of the Gaussian operator. This value must be greater than 0.0.
Returns A new image
Example
emboss example The right-hand side of the image has been altered by emboss.
×Magick API EmbossImage
enhance image.enhance -> anImage
Description Applies a digital filter that improves the quality of a noisy image.
Returns A new image.
Example
The left-hand side has had noise added by add_noise. The right-hand side is the result after using enhance. enhance example
×Magick API EnhanceImage
See also median_filter, reduce_noise, unsharp_mask
equalize image.equalize -> anImage
Description Applies a histogram equalization to the image.
Returns A new image.
Example
equalize example The right-hand side has been altered by equalize.
×Magick API EqualizeImage
erase! image.erase! -> image
Description Sets the entire image to the background color.
Returns self
×Magick API SetImage
See also color_reset!
export_pixels (5.5.7) image.export_pixels(x, y, columns, rows, map) -> anArray
Description Extracts the pixel data from the specified rectangle and returns it as an array of Integer values.

The array returned by export_pixels is suitable for use as an argument to import_pixels.

Arguments
x, y
The offset of the rectangle from the upper-left corner of the image.
columns, rows
The width and height of the rectangle.
map
A String reflecting the order of the pixel data. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
Returns An array.
Example
# Export the r'th scanline from an image in red-green-blue order
scanline = img.export_pixels(0, r, img.columns, 1, "RGB");
ImageMagick API ExportImagePixels
See also dispatch, import_pixels, get_pixels
Notes This method replaces the dispatch method.
flip image.flip -> anImage
Description Create a vertical mirror image of the receiver.
Returns A new image
Example flip example
×Magick API FlipImage
See also flip!, flop, affine_transform
flip! image.flip! -> image
Description In-place form of flip.
Returns self
flop image.flop -> anImage
Description Create a horizontal mirror image of the receiver.
Returns A new image
Example flop example
×Magick API FlopImage
See also flop!, flip, affine_transform
flop! image.flop! -> image
Description In-place form of flop.
Returns self
frame image.frame(width=25, height=25, x=25, y=25, inner_bevel=6, outer_bevel=6, color=matte_color) -> anImage
Description Adds a simulated 3D border.
Arguments
width
The width of the left and right sides.
height
The height of the top and bottom sides.
x, y
The image does not have to be centered in the border. These two arguments specify the offset of the image from the upper-left outside corner of the border.
inner_bevel, outer_bevel
The width of the inner and outer shadows of the border. These values should be much smaller than the width and height and cannot be greater than 1/2 the lesser of the width or height.
color
The border color. By default the color is the matte color.
Returns A new image.
Example frame example
×Magick API FrameImage
See also border
gamma_correct image.gamma_correct(red_gamma[,green_gamma[, blue_gamma[, opacity_gamma]]]) -> anImage
Description Gamma-correct an image. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen.
Arguments You must specify at least red_gamma. Omitted arguments take on the value of the last specified argument. Values typically range from 0.8 to 2.3.
Returns A new image.
×Magick API GammaImage
gaussian_blur image.gaussian_blur(radius=0.0, sigma=1.0) -> anImage
Description Blurs an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).
Arguments
radius
A Float value representing the radius of the Gaussian, in pixels, not counting the center pixel.
sigma
A Float value representing the standard deviation of the Gaussian operator, in pixels. This argument must be > 0.0.
Returns A new image
Example
gaussian_blur(0.0, 3.0)
gaussian_blur example
See also blur_image, motion_blur
×Magick API GaussianBlurImage
get_pixels image.get_pixels(x, y, columns, rows) -> anArray
Description Gets the pixels from the specified rectangle within the image.
Arguments
x, y
The x- and y-offset of the rectangle within the image.
columns, rows
The width and height of the rectangle.
Returns An array of pixels. There will be columns*rows elements in the array.
Example
This example composites a black-and-white version of an image over the same image in its original colors. It uses get_pixels and store_pixels to make each column of pixels in the black-and-white image slightly more opaque than the column on its left, so that the resulting composite changes smoothly from color on the left to black-and-white on the right.
get_pixels example
×Magick API AcquireImagePixels
See also store_pixels
gray? image.gray? -> true or false
Description Returns true if all the pixels in the image have the same red, green, and blue intensities.
Returns true or false
×Magick API IsGrayImage
See also monochrome?
grey? image.qrey? -> true or false
Description Synonym for gray?
implode image.implode(amount=0.50) -> anImage
Description A funhouse mirror effect. See the examples below.
Arguments A Float value. Increasing the absolute value of the argument increases the effect. The value may be positive for implosion, or negative for explosion. The default is 0.50.
Returns A new image
Example implode example
×Magick API ImplodeImage
import_pixels (5.5.7) image.import_pixels(x, y, columns, rows, map, pixels) -> self
Description

Replaces the pixels in the specified rectangle with pixel data from the supplied array.

Arguments
x, y
The offset of the rectangle from the upper-left corner of the image
columns, rows
The width and height of the rectangle
map
A string describing the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
pixels
The pixel data. The pixel data in the array must be stored in scanline order, left-to-right and top-to-bottom. The elements in the array must be Numeric values in the range [0..MaxRGB]. The easiest way to obtain such an array is by using the export_pixels method.
Returns The image as transformed by the pixel data.
Example
# Replace the r'th scanline of the image using
# pixel data stored in red-green-blue order.
img.import_pixels(0, r, img.columns, 1, "RGB", scanline);
ImageMagick API ImportImagePixels
See also constitute, export_pixels, store_pixels
Note

This method is the reverse of export_pixels.

Note This method replaces the constitute class method.
inspect image.inspect -> aString
Description Displays a description of the image.
Example
f = Magick::Image.read('implode.jpg').first
f.inspect » "implode.jpg JPEG 396x280 DirectClass 8-bit 18037b"
level image.level(black_point=0.0, mid_point=1.0, white_point=MaxRGB) -> anImage
Description Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range. The parameters provided represent the black, mid, and white points. The black point specifies the darkest color in the image. Colors darker than the black point are set to zero. Mid point specifies a gamma correction to apply to the image. White point specifies the lightest color in the image. Colors brighter than the white point are set to the maximum quantum value.
Arguments
black_point
The black point level. The default is 0.0.
mid_point
The mid-point level. The default is 1.0.
white_point
The white point level. The default is MaxRGB.
Returns A new image
Example level example
See also level_channel
×Magick API LevelImage
level_channel(5.5.3) image.level_channel(channel, black_point=0.0, mid_point=1.0, white_point=MaxRGB) -> anImage
Description Same as level but operates only on the specified channel.
Arguments
channel
A ChannelType value.
black_point
The black point level. The default is 0.0.
mid_point
The mid-point level. The default is 1.0.
white_point
The white point level. The default is MaxRGB.
Returns A new image
Example
level_channel example This example shows the results of 3 calls to level_channel. The left-most strip has the RedChannel enhanced. The center strip has the GreenChannel, and the right-most the BlueChannel.
See also level
×Magick API LevelImage
magnify image.magnify -> anImage
Description A convenience method that scales the receiver to twice its size.
Returns A new image
×Magick API MagnifyImage
See also magnify!, minify, resize, scale, sample, thumbnail
magnify! image.magnify! -> image
Description In-place form of magnify.
Returns self
map image.map(img, dither=false) -> anImage
Description Replaces the colors of an image with the closest color from a reference image.
Arguments
img
The reference image. May be either another image or an Image object.
dither
If true, dithers the mapped image.
Returns A new image
Example
The bottom half of this image has been mapped to the Netscape 216-color cube. map_f example
×Magick API MapImage
See also Image#map
matte_fill_to_border image.matte_fill_to_border(x, y) -> anImage
Description Makes transparent all the pixels that are neighbors of the pixel at x,y and are not the border color.
Arguments The x- and y- coordinates of the target pixel.
Returns A new image
Example matte_fill_to_border example
×Magick API MatteFloodfillImage
See also matte_floodfill, Draw#matte
matte_floodfill image.matte_floodfill(x, y) -> anImage
Description Makes transparent all the pixels that are the same color as the pixel at x, y, and are neighbors.
Arguments The x- and y-coordinates of the target pixel.
Returns A new image.
Example matte_floodfill example
×Magick API MatteFloodfilImage
See also matte_replace, Draw#matte
matte_point image.matte_point(x, y) -> anImage
Description Makes the pixel at x, y transparent.
Arguments The x- and y-coordinates of the target pixel.
Returns A new image
Example
This example creates a transparent pixel in the upper-left portion of the "M". matte_point example
See also Draw#matte
Notes This method makes a copy of the image, just to make one pixel transparent. I recommend using the Draw#matte method instead.
matte_replace image.matte_replace(x, y) -> anImage
Description Makes transparent all the pixels that are the same color as the pixel at x, y.
Arguments The x- and y-coordinates of the target pixel.
Returns A new image.
Example matte_replace example
×Magick API TransparentImage
See also transparent, Draw#matte
matte_reset! image.matte_reset! -> anImage
Description Makes all the pixels in the image transparent.
Returns A new image
×Magick API SetImageOpacity
See also opacity=
median_filter image.median_filter(radius=1.0) -> anImage
Description Applies a digital filter that improves the quality of a noisy image. Each pixel is replaced by the median in a set of neighboring pixels as defined by radius.
Arguments The filter radius. The larger the value, the longer it takes to render. Values larger than 8 or 9 may take longer than you want to wait, and will not have significantly better results than much smaller values.
Returns A new image
Example
The left side of the image has been modified by add_noise. The right side has been filtered by median_filter(0.05)
median_filter example
×Magick API MedianFilterImage
See also enhance, reduce_noise, unsharp_mask
minify image.minify -> anImage
Description A convenience method that scales the receiver to half its size.
Returns A new image
×Magick API MinifyImage
See also minify! magnify, resize, sample, scale, thumbnail
minify! image.minify! -> image
Description In-place form of minify.
Returns self
modulate image.modulate(brightness=1.0, saturation=1.0, hue=1.0) -> anImage
Description Changes the brightness, saturation, and hue.
Arguments The percent change in the brightness, saturation, and hue, represented as Float numbers. For example, 0.25 means "25%". All three arguments may be omitted. The default value of each argument is 1.0, that is, 100%.
Returns A new image
Example modulate example
×Magick API ModulateImage
monochrome? image.monochrome? -> true or false
Description Returns true if all the pixels have the same red, green, and blue values and the values are either 0 or MaxRGB. That is, the image is black-and-white.
×Magick API IsMonochromeImage
See also gray?
motion_blur image.motion_blur(radius, sigma, angle) -> anImage
Description Simulates motion blur. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). Use a radius of 0 and motion_blur selects a suitable radius for you. Angle gives the angle of the blurring motion.
Arguments
radius
The radius of the Gaussian operator.
sigma
The standard deviation of the Gaussian operator. Must be greater than 0.
angle
The angle (in degrees) of the blurring motion.
Returns A new image
Example motion_blur example
×Magick API MotionBlurImage
See also blur_image, gaussian_blur
negate image.negate(grayscale=false) -> anImage
Description Negates the colors in the receiver.
Arguments If the grayscale argument is true, only the grayscale values are negated.
Returns A new image
Example negate example
×Magick API NegateImage
normalize image.normalize -> anImage
Description Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available.
Returns A new image
Example normalize example
×Magick API NormalizeImage
oil_paint image.oil_paint(radius=3.0) -> anImage
Description Applies a special effect filter that simulates an oil painting. Each pixel is replaced by the most frequent color occurring in a circular region defined by radius.
Returns A new image
Example oil_paint example
×Magick API OilPaintImage
opaque image.opaque(target, fill) -> anImage
Description Changes all pixels having the target color to the fill color.
Arguments
target
The color to be replaced. May be a color name or a Pixel
fill
The replacement color. May be a color name or a Pixel
Returns A new image.
Example opaque example
×Magick API OpaqueImage
See also color_floodfill
opaque? image.opaque? -> true or false
Description Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.
Returns true or false
×Magick API IsOpaqueImage
ordered_dither image.ordered_dither -> anImage
Description Uses the ordered dithering technique of reducing color images to monochrome using positional information to retain as much information as possible.
Returns A new image
Example ordered_dither example
×Magick API OrderedDitherImage
See also quantize
palette? image.palette? -> true or false
Description Returns true if the image is PseudoClass and has 256 unique colors or less.
Returns true or false
×Magick API IsPaletteImage
pixel_color image.pixel_color(x, y[, new_color]) -> aPixel
Description Returns the color of the pixel at x, y. Optionally, changes the color of the pixel to a new color.
Arguments
x, y
The x- and y-coordinates of the pixel.
new_color
If specified, the pixel is set to this color. May be either a color name or a Pixel.
Returns A Pixel having the RGB values of the specified pixel.
Example old = image.pixel_color(20,40,"white")
profile! image.profile!(name, profile) -> image
Description Adds or removes a ICM, IPTC, or generic profile from an image. If profile is nil, the specified profile is removed from the image. Use profile('*', nil) to remove all profiles from the image.
Arguments
name
The profile name, or "*" to represent all the profiles in the image.
profile
The profile value, or nil to cause the profile to be removed.
Returns self
×Magick API ProfileImage
Advanced ×Magick does not automatically remove profiles when resizing images. If you are trying to make your JPEG thumbnail images as small as possible, use profile! to remove any profiles from the image as well. See Why are my JPEG files larger than expected? in the ×Magick FAQ.
properties image.properties [ {|name,value| block} ] -> image
image.properties -> aHash
Description If called with an associated block, properties runs the block once for each property defined for the image. The block arguments are the property name and its value. If there is no block, properties returns a hash with one element for each property. The hash key is the property name and the associated value is the property value.
Returns If called without a block, returns a hash, otherwise returns self.
See also [ ], [ ]=
quantize image.quantize(number_colors=256, colorspace=Magick::RGBColorspace, dither=true, tree_depth=0, measure_error=false) -> anImage
Description Analyzes the colors within a reference image and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the difference between the input and output image while minimizing the processing time.
Arguments
number_colors
The maximum number of colors in the result image. Must be <= MaxRGB.
colorspace
The colorspace to quantize in. Color reduction, by default, takes place in the RGB color space.  Empirical evidence suggests that distances in color spaces such as YUV or YIQ  correspond  to  perceptual  color differences more closely than  do distances in RGB space. The Transparent color space behaves uniquely in that it preserves the matte channel of the image if it exists.
dither
Set to true to apply Floyd/Steinberg error diffusion to the image. When the size of the color palette is less than the image colors, this trades off spacial resolution for color resolution by dithering to achieve a similar looking image.
tree_depth
The tree depth to use while quantizing. The values 0 and 1 support automatic tree depth determination. The tree depth may be forced via values ranging from 2 to 8. The ideal tree depth depends on the characteristics of the input image, and may be determined through experimentation.
measure_error
Set to true to calculate quantization errors when quantizing the image.
Returns A new image.
Example See the example for colorize.
×Magick API QuantizeImage
See also Image#quantize
raise image.raise(width=6, height=6, raised=true) -> anImage
Description Creates a simulated three-dimensional button-like effect by lightening and darkening the edges of the image.
Arguments
width
The width of the raised edge in pixels. The default is 6.
height
The height of the raised edge in pixels. The default is 6.
raised
If true, the image is raised, otherwise lowered.
Returns A new image
Example raise example
×Magick API RaiseImage
random_channel_threshold (5.5.7) (1.0.1) image.random_channel_threshold(channel, thresholds) -> anImage
Description
Changes the value of individual pixels based on the intensity of each pixel compared to a random threshold. The result is a low-contrast, two color image.
Arguments
channel
The channel or channels to be thresholded. One of the strings "all", "intensity", "matte", or "opacity".
thresholds
A geometry string containing LOWxHIGH thresholds. The string is in the form `XxY'. The Y value may be omitted, in which case it is assigned the value MaxRGB-X. If an % appears in the string then the values are assumed to be percentages of MaxRGB. If the string contains 2x2, 3x3, or 4x4, then an ordered dither of order 2, 3, or 4 will be performed instead.
Returns A new image
Example
randomc_channel_threshold example The right side of the image has been transformed by random_channel_threshold('intensity', '35%')
×Magick API RandomChannelThreshold
See also adaptive_threshold, channel_threshold, threshold
reduce_noise image.reduce_noise(radius) -> anImage
Description Smooths the contours of an image while still preserving edge information. The algorithm works by replacing each pixel with its neighbor closest in value.
Arguments
radius
A neighbor is defined by radius. Use a radius of 0 and reduce_noise selects a suitable radius for you.
Returns A new image
Example
The left side of the image has been modified by add_noise. The right side has been filtered by reduce_noise(0)
reduce_noise example
×Magick API ReduceNoiseImage
See also enhance, reduce_noise, unsharp_mask
resize image.resize(new_width, new_height, filter=LanczosFilter, blur=1.0) -> anImage
image.resize(scale_factor) -> anImage
Description Changes the size of the receiver to the specified dimensions. You can specify the new size in two ways. Either specify the new width and height explicitly, or specify a scale factor, a number that represents the percentage change.
Arguments
new_width, new_height
The desired width and height.
filter
The filter to use when resizing. If you do not specify a filter argument, resize uses the value of the receiver's filter attribute. Most of the filters are FIR (finite impulse response), however, Bessel, Gaussian, and Sinc are IIR (infinite impulse response). Bessel and Sinc are windowed (brought down to zero) with the Blackman filter.
blur
The blur factor. Values > 1 increase the blurriness. Values < 1 increase the sharpness. If this argument is not specified, resize uses the value of the receiver's blur attribute.
scale_factor
You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.
Returns A new image
×Magick API ResizeImage
See also resize!, magnify, minify, sample, scale, thumbnail
resize! image.resize!(new_width, new_height, filter=LanczosFilter, blur=1.0) -> image
image.resize!(scale_factor) -> image
Description In-place form of resize.
Returns self
roll image.roll(x_offset, y_offset) -> anImage
Description Offsets an image as defined by x_offset and y_offset.
Arguments
x_offset
The number of columns to offset the image.
y_offset
The number of rows to offset the image.
Returns A new image
Example
This image has been offset 25% in both directions. roll example
×Magick API RollImage
rotate image.rotate(amount) -> anImage
Description Rotate the receiver by the specified angle. Positive angles rotate counter-clockwise (right-hand rule), while negative angles rotate clockwise. Rotated images are usually larger than the originals and have "empty" triangular corners. Empty triangles left over from shearing the image are filled with the color defined by the pixel at location (0,0).
Arguments The number of degrees to rotate the image.
Returns A new image
Example rotate example
×Magick API RotateImage
See also affine_transform, shear
rotate! image.rotate!(amount) -> image
Description In-place form of rotate.
Returns self
sample image.sample(new_width, new_height) -> anImage
image.sample(scale_factor) -> anImage
Description Scales an image to the desired dimensions with pixel sampling. Unlike other scaling methods, this method does not introduce any additional color into the scaled image.
Arguments
new_width, new_height
The desired width and height.
scale_factor
You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.
Returns A new image
×Magick API SampleImage
See also sample!, magnify, minify, resize, scale, thumbnail
sample! image.sample!(new_width, new_height) -> image
image.sample!(scale_factor) -> image
Description In-place form of sample.
Returns self
scale image.scale(new_width, new_height) -> anImage
image.scale(scale_factor) -> anImage
Description Changes the size of an image to the given dimensions.
Arguments
new_width, new_height
The desired width and height.
scale_factor
You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.
Returns A new image
×Magick API ScaleImage
See also scale!, magnify, minify, resize, sample, thumbnail
scale! image.scale!(new_width, new_height) -> image
image.scale!(scale_factor) -> image
Description In-place form of scale.
segment image.segment(colorspace=RGBColorspace, cluster_threshold=1.0, smoothing_threshold=1.5, verbose=false) -> anImage
Description Segments an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique.
Arguments
colorspace
A ColorspaceType constant. Empirical evidence suggests that distances in YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. The image is then returned to RGB colorspace after color reduction.
cluster_threshold
The number of pixels in each cluster must exceed the the cluster threshold to be considered valid.
smoothing_threshold
The smoothing threshold eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative.
verbose
If true, segment prints detailed information about the identified classes.
Returns A new image
Example segment example
×Magick API SegmentImage
shade image.shade(shading=false, azimuth=30, elevation=30) -> anImage
Description Shines a distant light on an image to create a three-dimensional effect. You control the positioning of the light with azimuth and elevation; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis.
Arguments
shading
If true, shade shades the intensity of each pixel.
azimuth, elevation
The light source direction.
Returns A new image
Example shade example
×Magick API ShadeImage
sharpen image.sharpen(radius=0.0, sigma=1.0) -> anImage
Description Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and sharpen selects a suitable radius for you.
Arguments The radius and standard deviation of the Gaussian operator.
Returns A new image
×Magick API SharpenImage
shave image.shave(width, height) -> anImage
Description Removes pixels from the edges of the image, leaving the center rectangle.
Arguments
width
The number of pixels to remove from each side of the receiver, not to exceed half the original width.
height
The number of pixels to remove from the top and bottom of the receiver, not to exceed half the original height.
Returns A new image
Example
shave example (before) shave example (after)
×Magick API ShaveImage
See also shave!, crop
shave! image.shave!(width, height) -> image
Description In-place form of shave.
Returns self
shear image.shear(x_shear, y_shear) -> anImage
Description Shearing slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x_shear is measured relative to the Y axis, and similarly, for Y direction shears y_shear is measured relative to the X axis. Empty triangles left over from shearing the image are filled with the background color.
Arguments The X and Y shear angles, measured in degrees. These values must not be 180.0. If either value is 0, no shearing will occur.
Returns A new image
Example shear example
×Magick API ShearImage
See also affine_transform, rotate
signature image.signature -> aString
Description Computes a message digest from an image pixel stream with an implementation of the NIST SHA-256 Message Digest algorithm. This signature uniquely identifies the image and is convenient for determining if an image has been modified or whether two images are identical.
Returns The signature as a 64-character string.
Example
jj = Magick::Image.read('images/Jean_Jacket.jpg').first
   » images/Jean_Jacket.jpg JPEG 432x576 DirectClass 8-bit 23360b
puts jj.signature
   » a1dfc12cc2c52cbc42a01dfda1f9c958ae61db3445e5185cee75f26b40effc9c
×Magick API SignatureImage
See also <=>, difference
solarize image.solarize(threshold=50) -> anImage
Description Applies a special effect to the image similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light.
Arguments
threshold
Ranges from 0 to MaxRGB and is a measure of the extent of the solarization. The default is 50.
Returns A new image
Example solarize example
×Magick API SolarizeImage
spread image.spread(radius=3) -> anImage
Description Randomly displaces each pixel in a block defined by the radius parameter.
Returns A new image
Example spread example
×Magick API SpreadImage
stegano image.stegano(watermark, offset) -> anImage
Description Hides a digital watermark in the receiver. You can retrieve the watermark by reading the file with the stegano: prefix, thereby proving the authenticity of the file.
Arguments
watermark
An image or imagelist to be used as the watermark. The watermark must be grayscale and should be substantially smaller than the receiver. The recovery time is proportional to the size of the watermark.
offset
The starting position within the receiver at which the watermark will be hidden. When you retrieve the watermark from the file, you must supply this value, along with the width and height of the watermark, in the size optional parameter to the read method.
Returns A new image with the embedded watermark.
Example stegano example
×Magick API SteganoImage
Notes The watermarked image must be saved in a lossless RGB format such as MIFF, or PNG. You cannot save a watermarked image in a lossy format such as JPEG or a pseudocolor format such as GIF. Once written, the file must not be modified or processed in any way.
stereo image.stereo(offset_image) -> anImage
Description Combines two images and produces a single image that is the composite of a left and right image of a stereo pair. Special red-green stereo glasses are required to view this effect.
Arguments Another image or imagelist. If the argument is an imagelist, uses the current image.
Returns A new image
×Magick API StereoImage
store_pixels image.store_pixels(x, y, columns, rows, pixels) -> image
Description Replace the pixels in the specified rectangle with the pixels in the pixels array.
Arguments
x, y
The x- and y-offset of the rectangle to be replaced.
columns, rows
The number of rows and columns in the rectangle.
pixels
An array of pixels. The number of pixels in the array must be the same as the number of pixels in the rectangle, that is, rows*columns.
Returns The image, with the rectangle suitably altered.
Example smile example

Also see the example for get_pixels.

×Magick API SetImagePixels, SyncImagePixels
See also get_pixels
strip!  (5.5.8) image.strip! -> self
Description
Strips an image of all profiles and comments.
Returns self
ImageMagick API StripImage
swirl image.swirl(degrees) -> anImage
Description Swirls the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360.
Arguments The number of degrees to swirl the image.
Returns A new image
Example swirl example
×Magick API SwirlImage
texture_fill_to_border image.texture_fill_to_border(x, y, texture) -> anImage
Description Replaces the target pixel at x, y and its neighbors that are not the border color with the specified texture. Use the fuzz attribute to specify how closely a pixel must match the border color.
Arguments
x, y
The x- and y-offset of the target pixel.
texture
An image or imagelist. If an imagelist, uses the current image.
Returns A new image
Example texture_fill_to_border example
×Magick API ColorFloodfillImage
See also color_fill_to_border, matte_fill_to_border
texture_floodfill image.texture_floodfill(x, y, texture) -> anImage
Description Replaces the target pixel at x, y and its neighbors that are the same color with the specified texture. By default, the neighbor pixels must be exactly the same color as the target pixel. Use the fuzz attribute to specify how much difference is acceptable.
Arguments
x, y
The x- and y-offset of the target pixel.
texture
An image or imagelist. If an imagelist, uses the current image.
Returns A new image.
Example texture_floodfill example
×Magick API ColorFloodfillImage
See also color_floodfill, matte_floodfill
threshold image.threshold(threshold) -> anImage
Description Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image.
Arguments A value between 0 and MaxRGB.
Returns A new image
Example threshold example
×Magick API ThresholdImage
See also adaptive_threshold, channel_threshold, random_channel_threshold
thumbnail  (5.5.2) image.thumbnail(new_width, new_height) -> anImage
image.thumbnail(scale_factor) -> anImage
Description The thumbnail method is a fast resizing method suitable for use when the size of the resulting image is < 10% of the original.
Arguments You can call thumbnail with either the new width and height or the scale factor.
new_width, new_height
The desired width and height in pixels.
scale_factor
The desired size represented as a floating-point number. For example, to make a thumbnail that is 9.5% of the size of the original image, use 0.095.
Returns A new image
Example
img = Magick::Image.read("images/Cheetah.jpg").first
thumbnail = img.thumbnail(img.columns*0.09, img.rows*0.09)
×Magick API ThumbnailImage
See also minify, resize, sample, scale
Notes The thumbnail method is only available with ImageMagick 5.5.2 and later.
thumbnail!  (5.5.2) image.thumbnail!(new_width, new_height) -> image
image.thumbnail!(scale_factor) -> i
Description In-place form of thumbnail.
Returns self
Notes The thumbnail! method is only available with ImageMagick 5.5.2 and later.
to_blob image.to_blob [ { optional arguments } ]-> aString
Description Creates a Binary Large OBject, a direct-to-memory version of the image. The from_blob method constructs an image from a BLOB created by this method.
Arguments None. However, you can specify the image format (such as JPEG, PNG, etc.) and depth by calling the format and depth attributes, as well as other Image::Info attributes as appropriate, in a block associated with the method.
Returns A string containing the image data represented as a BLOB.
Example to_blob example
×Magick API ImageToBlob
See also from_blob
to_color image.to_color(aPixel) -> aString
Description Returns the color name for a pixel. Unlike the Pixel#to_color method, to_color uses the depth and matte attributes of the image to determine the color name.
Arguments A Pixel object.
Returns Either a color name or a color tuple in the form "#RRGGBBOO". If the image depth is 16, the tuple has the form "#RRRRGGGGBBBBOOOO".
Example
f = Magick::Image.read('images/Jean_Jacket.jpg').first »
        images/Jean_Jacket.jpg JPEG 432x576 DirectClass 8-bit 23360b
p = f.pixel_color(0,0) »
        #<Magick::Pixel red=16191, green=15677, blue=12593, opacity=0>
f.to_color(p) » "#3F3D31"
       
×Magick API QueryColorname
See also Pixel#to_color
transparent image.transparent(color, opacity=Magick::OpaqueOpacity) -> anImage
Description Changes the opacity value of all the pixels that match color to the value specified by opacity. By default the pixel must match exactly, but you can specify a tolerence level by setting the fuzz attribute on the image.
Arguments
color
Either a color name or a pixel.
opacity
The new opacity value, either an opacity constant or a number between 0 and MaxRGB. The default is TransparentOpacity.
Returns A new image.
Example transparent example
×Magick API TransparentImage
See also matte_replace, Draw#matte
unsharp_mask image.unsharp_mask(radius, sigma, amount, threshold) -> anImage
Description Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and unsharp_mask selects a suitable radius for you.
Arguments
radius
The radius of the Gaussian operator.
sigma
The standard deviation of the Gaussian operator. A good starting value is 1.0.
amount
The percentage of the blurred image to be added to the receiver, specified as a fraction between 0 and 1.0. A good starting value is 1.0.
threshold
The threshold needed to apply the amount, specified as a fraction between 0 and 1.0. A good starting value is 0.05.
Returns A new image
Example unsharp_mask example
×Magick API UnsharpMaskImage
See also enhance, median_filter, reduce_noise
wave image.wave(amplitude=25.0, wavelength=150.0) -> anImage
Description Creates a "ripple" effect in the image by shifting the pixels vertically along a sine wave whose amplitude and wavelength is specified by the given parameters.
Returns A new image
Example wave example
×Magick API WaveImage
white_threshold (5.5.7) image.white_threshold(red_channel [, green_channel[, blue_channel[, opacity_channel]]]) -> anImage
Description Forces all pixels above the threshold into white while leaving all pixels below the threshold unchanged.
Arguments Each channel argument is a number between 0 and MaxRGB. All arguments except the first may be omitted. If the green_channel or blue_channel argument is omitted, the default value is the red_channel value. If the opacity_channel argument is omitted, the default value is OpaqueOpacity.
Returns A new image.
See Also black_threshold, channel_threshold
×Magick API BlackThresholdImage
write image.write(filename) [ { optional arguments } ] -> image
image.write(file) [ { optional arguments } ] -> image
Description Writes the image to the specified file. ×Magick determines image format from the prefix or extension.
Arguments A file name or open file object. You may also specify optional arguments by setting Image::Info attributes in an associated block.
Returns self, or nil if the image format cannot be determined.
Example Almost all of the examples call write.
Advanced If the argument is an open file, you can write the image in a different format by setting the image's format attribute.
×Magick API WriteImage
See also ImageList#write