class Image < Object (class methods and instance methods a-d)
mixes in Comparable

Table of Contents

class methods

instance methods

class methods

capture

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

Description

Reads an image from an X window. Unless you identify a window to capture via the optional arguments block, when capture is invoked the cursor will turn into a cross. Click the cursor on the window to be captured.

Within the optional arguments block, specify options.filename = "root" to capture the entire desktop. To programatically specify the window to be captured, use options.filename = window_id, where window_id is the id displayed by xwininfo(1).

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.
optional arguments
You can specify any of these Image::Info attributes in the optional arguments block: colorspace, depth, dither, interlace, and image_type.

Returns

A new image.

Example

img = Magick::Image.capture { |options|
  options.filename = "root"
}

combine

Image.combine(red_ch=nil, green_ch=nil, blue_ch=nil, opacity_ch=nil) ->image

Description

Combines the grayscale value of the pixels in each image to form a new image.

Arguments

The red channel of the image specified in the first argument is used as the red channel in the new image. The green channel of the image specified in the second argument is used as the green channel in the new image. The blue channel of the image specified in the third argument is used as the blue channel in the new image. The opacity channel of the image specified in the fourth argument is used as the opacity channel in the new image.

Any of the arguments may be nil. Trailing nil arguments may be omitted. You must specify at least one image argument.

Returns

A new image

See also

The same results can be obtained using the composite method and the CopyRed/Green/Blue/OpacityCompositeOp CompositeOperator enum values.

Magick API

CombineImages

constitute

Image.constitute(width, height, map, pixels) -> image

Description

Creates an image from an array of pixels. This method is the reverse of dispatch.

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..QuantumRange]. If the elements are Floats, they must be in the range [0..1].

Returns

An image constructed from the pixel data.

Example

image = Magick::Image.constitute(width, height, "RGB", pixels)

See also

import_pixels, store_pixels

Magick API

ConstituteImage

from_blob

Image.from_blob(string) [ { optional arguments } ] -> array

Description

Creates an array of images from a BLOB, that is, a Binary Large OBject. In RMagick, a BLOB is a string.

Arguments

A blob can be a string containing an image file such as a JPEG or GIF. The string can contain a multi-image file such as an animated GIF or a Photoshop image with multiple layers. A blob can also be one of the strings produced by to_blob. 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

new

Image.new(columns, rows [, fill]) [ { optional arguments } ] -> image

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

columns
The number of columns
rows
The number of rows
fill
A Fill object

Returns

A new image.

Example

img = Magick::Image.new(256, 64) { |options|
  options.background_color = 'red'
}

See also

ImageList.new_image

Magick API

AllocateImage

ping

Image.ping(filename) [ { optional arguments } ] -> array
Image.ping(file) [ { optional arguments } ] -> array

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

See also

read

Magick API

PingImage

read

Image.read(filename) [ { optional arguments } ] -> array
Image.read(file) [ { optional arguments } ] -> array

Description

Reads all the images from the specified file.

Note: Because an image file can contain multiple images or multiple image layers, read always returns an array containing 0 or more elements, one element for each image or image layer in the 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]

See also

ping

Note

The read method does not accept a StringIO object. If you want to create an image from a string buffer, use from_blob.

Magick API

ReadImage

read_inline

Image.read_inline(content) [ { optional arguments } ] -> array

Description

Converts a Base64-encoded image or multi-image sequence to an array of Image objects.

Arguments

A Base64-encoded string. Generally no optional arguments are required. If the image format cannot be deduced from the image data, you can use the format attribute. If you want to extract a subset of an image sequence, see here.

Returns

An array containing 0 or more Image objects. If the content is a multi-image sequence 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

content = "R0lGODlhnAEuAferAAAAAAcIBggJBgw..."
img = Magick::Image.read_inline(content)

See also

read

instance methods

[ ]

img[key] -> string

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. ImageMagick predefines some properties, including Label, Comment, Signature, and in some cases EXIF.

Arguments

The key may be a String or a Symbol.

Returns

The value of the property.

Example

mom['Label'] = 'My Mother'

See also

[ ]=, properties

Magick API

GetImageAttribute

Note

ImageMagick calls properties "attributes." I use the word "properties" to reduce the confusion with image object attributes such as rows and columns.

[ ]=

img[key] = string -> self

Description

Sets the value of an image property. An image may have any number of properties.

Arguments

The key may be a string or a symbol. The value can be any string.

Returns

self

Example

See demo.rb for an example of the use of the Label property.

See also

[ ], properties

Magick API

SetImageAttribute

<=>

img <=> other_image -> -1, 0, 1

Description

Compares two images and returns -1, 0, or 1 if img is less than, equal to, or greater than other_image as determined by comparing the signatures of the images. If one of the arguments is not an image, this method raises a TypeError exception (in Ruby 1.6) or returns nil (in Ruby 1.8)

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

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

Returns

The value of img.signature <=> other_image.signature.

See also

signature, difference, compare_channel

Magick API

SignatureImage

adaptive_blur

img.adaptive_blur(radius=0.0, sigma=1.0) -> image

Description

Adaptively blurs the image by blurring more intensely near image edges and less intensely far from edges. The adaptive_blur method blurs 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 adaptive_blur selects a suitable radius for you.

Arguments

radius
The radius of the Gaussian in pixels, not counting the center pixel. The default is 0.0.
sigma
The standard deviation of the Laplacian, in pixels. The default is 1.0.

Returns

A new image

See also

adaptive_blur_channel

Magick API

AdaptiveBlurImage

adaptive_blur_channel

img.adaptive_blur(radius=0.0, sigma=1.0 [,channel...]) -> image

Description

The same as adaptive_blur except only the specified channels are blurred.

Arguments

radius
The radius of the Gaussian in pixels, not counting the center pixel. The default is 0.0.
sigma
The standard deviation of the Laplacian, in pixels. The default is 1.0.
channel...
0 or more ChannelType arguments. If no channels are specified, blurs all the channels. Specifying no channel arguments has the same effect as the adaptive_blur method, above.

Returns

A new image

See also

adaptive_blur

Magick API

AdaptiveBlurImageChannel

adaptive_resize

img.adaptive_resize(new_width, new_height) -> image
img.adaptive_resize(scale_factor) -> image

Description

Resizes the image with data dependent triangulation.

Arguments

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.

Use the change_geometry method to compute new dimensions for an image with constraints such as "maintain the current proportions."

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

See also

resize

Magick API

AdaptiveResizeImage

adaptive_sharpen

img.adaptive_sharpen(radius=0.0, sigma=1.0) -> image

Description

Adaptively sharpens the image by sharpening more intensely near image edges and less intensely far from edges. The adaptive_sharpen method sharpens 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 adaptive_sharpen selects a suitable radius for you.

Arguments

radius
The radius of the Gaussian in pixels, not counting the center pixel. The default is 0.0.
sigma
The standard deviation of the Laplacian, in pixels. The default is 1.0.

Returns

A new image

See also

adaptive_sharpen_channel

Magick API

AdaptiveSharpenImage

adaptive_sharpen_channel

img.adaptive_sharpen(radius=0.0, sigma=1.0 [,channel...]) -> image

Description

The same as adaptive_sharpen except only the specified channels are sharpened.

Arguments

radius
The radius of the Gaussian in pixels, not counting the center pixel. The default is 0.0.
sigma
The standard deviation of the Laplacian, in pixels. The default is 1.0.
channel...
0 or more ChannelType arguments. If no channels are specified, sharpens all the channels. Specifying no channel arguments has the same effect as the adaptive_sharpen method, above.

Returns

A new image

See also

adaptive_sharpen

Magick API

AdaptiveSharpenImageChannel

adaptive_threshold

img.adaptive_threshold(width=3, height=3, offset=0) -> image

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

See also

bilevel_channel, random_threshold_channel, threshold

Magick API

AdaptiveThresholdImage

add_compose_mask

img.add_compose_mask(mask) -> self

Description

Associates a mask with an image that will be used as the destination image in a composite operation. The areas of the destination image that are masked by white pixels will be modified by the composite method, while areas masked by black pixels are unchanged.

See Using a Compose Mask to Limit the Composed Area in Anthony Thyssen's Examples of ImageMagick Usage.

Arguments

The mask image must have the same dimensions as the destination image.

Returns

self

Example

Source image for add_compose_mask example Background image for add_compose_mask example Mask image for compose_mask example Result image for compose_mask example
Background Source Mask Result

See also

composite, delete_compose_mask

Notes

This method uses a copy of the argument as the mask. If you change the mask image you must call this method again to update the mask.

Magick API

SetImageMask

add_noise

img.add_noise(noise_type) -> image

Description

Adds random noise to the image. The amount of time add_noise requires depends on the NoiseType argument.

Arguments

A NoiseType value.

Returns

A new image

Example

add_noise example

Click the NoiseType to see the effect.

Notes

The RandomNoise type was added in ImageMagick 6.3.5.

Magick API

AddNoiseImage

See also

add_noise_channel

add_profile

img.add_profile(filename) -> self

Description

Adds an ICC (a.k.a. ICM), IPTC, or generic profile. If the file contains more than one profile all the profiles are added.

Arguments

The filename of a file containing the profile.

Returns

self

Example

img.add_profile('my_cmyk.icm')

See also

The iptc_profile and color_profile attributes provide very similar functionality, except that these attributes accept the profile data in the form of a string. The profile! method can also be used to add a profile. The type of profile must be specified and the profile data must be in the form of a string. Also see delete_profile and each_profile.

Magick API

ProfileImage

add_noise_channel

img.add_noise_channel(noise_type [,channel...]) -> image

Description

Adds random noise to the specified channel or channels in the image.

Arguments

noise_type
A NoiseType value.
channel...
0 or more ChannelType arguments. If no channels are specified, adds noise to all the channels. Specifying no channel arguments has the same effect as the add_noise method, above.

Returns

A new image

Magick API

AddNoiseImageChannel

See also

add_noise

affine_transform

img.affine_transform(matrix) -> image

Description

Transforms the image as specified by the affine matrix.

See Coordinate system transformations in the Scalable Vector Graphics (SVG) 1.0 Specification for more information about transformation matrices.

Arguments

An AffineMatrix object.

Returns

A new image

Example

The affine matrix in this example skews the receiver by π/6 radians along both axes.

affine_transform example

See also

rotate, shear

Magick API

AffineTransformImage

alpha

img.alpha(type) -> type

Description

Set a flag to indicate whether or not to use alpha channel data.

Arguments

One of the following values of the AlphaChannelOption enumeration:

OnAlphaChannel
Enable the images use of transparency. If transparency data did not exist, allocate the data and set to opaque. If the image previously had transparency data, the data is again enable as it was when turned off. The transparency data is not changed or modified in any way.
BackgroundAlphaChannel
Set fully transparent pixels to the background color. (Available in IM 6.5.2-5.)
CopyAlphaChannel
Turns on the alpha/matte channel, then copies the gray-scale intensity of the image, as an alpha mask, into the alpha channel, converting a gray-scale mask into a transparent shaped image ready to be colored appropriately. The color channels are not modified.
OffAlphaChannel
Disables the image's transparency channel. Does not delete or change the existing data, just turns of the use of that data. This is the same as assigning false to the old matte= attribute.
ExtractAlphaChannel
Creates a grayscale mask of the image's shape by copying the alpha channel values into all the color channels, and then turning off the image's transparency. The inverse of CopyAlphaChannel
OpaqueAlphaChannel
Turns on the alpha/matte channel and forces it to be fully opaque.
SetAlphaChannel
Turns on the alpha/matte channel and if it was previously turned off resets the channel to opaque. If the image already had the alpha channel turned on, it will have no effect.
ShapeAlphaChannel
As CopyAlphaChannel but also colors the resulting shape mask with the current background color.
TransparentAlphaChannel
Turns on the alpha/matte channel and forces it to be fully transparent. This effectivally creates a transparent image the same size as the original, with all its meta-data still attached.

Returns

The argument.

See also

alpha?

Notes

Available in ImageMagick 6.3.5 and later.

Magick API

SetImageAlphaChannel

alpha?

img.alpha? -> true or false

Description

Returns true if the alpha channel will be used, false otherwise.

See also

alpha

Magick API

GetImageAlphaChannel

annotate

img.annotate(draw, width, height, x, y, text) [ { additional parameters } ] -> self

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. Some users feel like annotate is better placed in Image than in Draw. Okay, here it is!

Returns

self

auto_gamma_channel

img.auto_gamma_channel([channel...]) -> image

Description

"Automagically" adjust the gamma level of an image.

Arguments

channel...
0 or more ChannelType arguments. If no channels are specified, automagically adjusts the gamma level of all the channels.

Returns

A new image

auto_level_channel

img.auto_level_channel([channel...]) -> image

Description

"Automagically" adjust the color levels of an image.

Arguments

channel...
0 or more ChannelType arguments. If no channels are specified, automagically adjusts the color level of all the channels.

Returns

A new image

auto_orient

img.auto_orient -> image

Description

Rotates or flips the image based on the image's EXIF orientation tag. Note that only some models of modern digital cameras can tag an image with the orientation. If the image does not have an orientation tag, or the image is already properly oriented, then auto_orient returns an exact copy of the image.

Returns

A new image

See also

auto_orient!

Magick API

FlipImage, FlopImage, RotateImage, TransposeImage, TransverseImage

auto_orient!

img.auto_orient! -> self

Description

Rotates or flips the image based on the image's EXIF orientation tag. Note that only some models of modern digital cameras can tag an image with the orientation. If the image does not have an orientation tag, or the image is already properly oriented, then auto_orient! returns nil.

Returns

self. or nil if the image is already properly oriented

See also

auto_orient

bilevel_channel

img.bilevel_channel(threshold [,channel...]) -> image

Description

Changes the value of individual pixels based on the intensity of each pixel channel. The result is a high-contrast image.

Arguments

threshold
The threshold value, a number between 0 and QuantumRange.
channel...
0 or more ChannelType arguments. If no channels are specified, all the channels are thresholded.

Returns

A new image

Example

bilevel_channel(2*QuantumRange/3, RedChannel)

bilevel_channel example

See also

adaptive_threshold, random_threshold_channel

Magick API

BilevelImageChannel

black_threshold

img.black_threshold(red_channel [, green_channel [, blue_channel [, opacity_channel]]]) -> image

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 QuantumRange. 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, bilevel_channel

Magick API

BlackThresholdImage

blend

img.blend(overlay, src_percentage, dst_percentage, x_offset=0, y_offset=0) -> image
img.blend(overlay, src_percentage, dst_percentage, gravity, x_offset=0, y_offset=0) -> image

Description

Adds the overlay image to the target image according to src_percent and dst_percent.

This method corresponds to the -blend option of ImageMagick's composite command.

Arguments

overlay
The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.
src_percentage
Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.
dst_percentage
Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no other arguments follow it. In this case the default is 100%-src_percentage.

The blend method can be called with or without a gravity argument. The gravity, x_offset, and y_offset arguments are described in the documentation for watermark.

Example

See "Blend Two Images Together".

Returns

A new image

See also

dissolve, composite

blue_shift

img.blue_shift(factor=1.5) -> image

Description

Simulate a scene at nighttime in the moonlight.

Arguments

factor
Larger values increase the effect. The default is 1.5.

Returns

A new image

Notes

Available in ImageMagick 6.5.4-3 and later.

Magick API

BlueShiftImage

blur_channel

img.blur_channel(radius=0.0, sigma=1.0[, channel...]]) -> image

Description

Blurs the specified channel. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma) . The blur_channel method differs from gaussian_blur_channel in that it uses a separable kernel which is faster but mathematically equivalent to the non-separable kernel.

Arguments

For reasonable results, the radius should be larger than sigma. Use a radius of 0 and blur_channel selects a suitable radius for you.

channel...
One or more ChannelType values. If none are specified, the red, green, and blue channels are blurred. This is the equivalent of blur_image.

Returns

A new image

See also

blur_image, gaussian_blur_channel, motion_blur, radial_blur, selective_blur_channel

Magick API

BlurImageChannel

blur_image

img.blur_image(radius=0.0, sigma=1.0) -> image

Description

Blurs the image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).

Arguments

For reasonable results, the radius should be larger than sigma. Use a radius of 0 and blur_image selects a suitable radius for you.

Returns

A new image.

Example

blur_image example

See also

blur_channel, gaussian_blur, motion_blur, radial_blur, selective_blur_channel

Magick API

BlurImage

border

img.border(width, height, color) -> image

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

See also

border!, frame

Magick API

BorderImage

border!

img.border!(width, height, color) -> self

Description

In-place form of border

Returns

self

bounding_box

img.bounding_box -> rectangle

Description

The image's bounding box. The bounding box is the rectangle that encloses all the pixels not in the border color. Uses the current fuzz value.

Returns

A Rectangle object.

Example

In this example, the bounding box is the gray square enclosing the blue circle. (The coordinates and red circles were added after the bounding box was computed.)

ex/bounding_box.rb

change_geometry

img.change_geometry(string) {|cols,rows,image| block} -> ??? (see Returns)
img.change_geometry(geometry) {|cols,rows,image| block} -> ??? (see Returns)

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 may be either a geometry string or a Geometry object. Change_geometry yields to the block, passing new width and height values based on the argument with respect to self. The return value is the return value of the block.

Arguments

An geometry string or a Geometry object

Returns

The value returned by the block

Example

mona = Magick::Image.read('MonaLisa.jpg').first
mona.change_geometry!('320x240') { |cols, rows, img|
  img.resize!(cols, rows)
}

Magick API

ParseSizeString

Note

change_geometry! is an alias for change_geometry.

changed?

img.changed? -> true or false

Description

Returns true if any pixel has been altered since the image was constituted.

Magick API

IsTaintImage

channel

img.channel(channel) -> image

Description

Extracts a channel from the image. A channel is a particular color component of each pixel in the [image].

Arguments

A ChannelType value.

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_depth

img.channel_depth([channel...]) -> number

Description

Returns the maximum depth for the specified channel or channels.

Arguments

channel...
Zero or more ChannelType values. If no arguments are specified, the default is all channels.

Returns

The maximum depth

See also

set_channel_depth

Magick API

GetImageChannelDepth

channel_extrema

img.channel_extrema([channel...]) -> [number, number]

Description

Returns the minimum and maximum intensity values for the specified channel or channels.

Arguments

channel...
Zero or more ChannelType values. If no arguments are specified, the default is all channels.

Returns

An array. The first element in the array is the minimum value. The second element is the maximum value.

Magick API

GetImageChannelExtrema

channel_mean

img.channel_mean([channel...]) -> [number, number]

Description

Returns the mean and standard deviation values for the specified channel or channels.

Arguments

channel...
Zero or more ChannelType values. If no arguments are specified, the default is all channels.

Returns

An array. The first element in the array is the mean value. The second element is the standard deviation.

Magick API

GetImageChannelMean

charcoal

img.charcoal(radius=0.0, sigma=1.0) -> image

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

Example

charcoal example

Magick API

CharcoalImage

check_destroyed

img.check_destroyed -> nil

Description

Raises DestroyedImageError if the image has been destroyed. Returns nil otherwise.

See also

destroy!, destroyed?

chop

img.chop(x, y, width, height) -> image

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 chop rectangle is highlighted in the "before" image. The result may seem counter-intuitive!

chop example

See also

crop

Magick API

ChopImage

clone

img.clone -> image

Description

Same as dup except the frozen state of the original is propagated to the new copy.

Returns

A new image

See also

dup

clut_channel

img.clut(clut_image [, channel...]) -> self

Description

Replace the channel values in the target image with a lookup of its replacement value in an LUT gradient image.

The LUT image should be either a single row or column image of replacement colors. The lookup is controlled by the -interpolate setting, especially for an LUT which is not the full length needed by the IM installed Quality (Q) level. Good settings for this is the default 'bilinear' or 'bicubic' interpolation setting for a smooth color gradient, or 'integer' for a direct unsmoothed lookup of color values.

This method is especially suited to replacing a grayscale image with specific color gradient from the CLUT image.

Note that color replacements involving transparency (alpha/matte channel) will lookup the replacement alpha/matte value using the alpha/matte value of the original image. As such correct alpha channel lookup for a pure gray-scale original image will require a copy of that grayscale to be transferred into its alpha channel before applying the -clut operator.

Arguments

clut_image
The LUT gradient image. Specify which interpolation method to use by setting this image's pixel_interpolation_method attribute to a PixelInterpolateMethod value.
channel...
Limit which channels are modified by specifying one or more ChannelType values. Only these channels will be changed. If no channels are specified, all channels will be changed.

Returns

self

See also

ImageMagick's -clut option.

color_fill_to_border

img.color_fill_to_border(x, y, fill_color) -> image

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

In this example, the aquamarine fill starts at the center of the circle and fills to the black border. All non-black pixels are replaced by the fill color. Contrast the result of color_fill_to_border with that of color_floodfill example, below.

color_fill_to_border example

See also

color_floodfill

Magick API

ColorFloodfillImage

color_floodfill

img.color_floodfill(x, y, fill_color) -> image

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

In this example, the aquamarine fill starts at the center of the circle and replaces all neighboring white pixels. Contrast the result of color_floodfill with that of color_fill_to_border, above.

color_floodfill example

See also

color_fill_to_border, opaque

Magick API

ColorFloodfillImage

color_histogram

img.color_histogram() -> hash

Description

Computes the number of times each unique color appears in the image.

Returns

A hash. Each key in the hash is a pixel representing a color that appears in the image. The value associated with the key is the number of times that color appears in the image. Caution: if the image contains many colors the hash will be very large. You may want to use the quantize method to reduce the number of colors before using color_histogram.

Example

This histogram was produced by sorting the hash returned by color_histogram by increasing frequency.

color_histogram example

Magick API

GetImageHistogram

colorize

img.colorize(red_pct, green_pct, blue_pct, [matte_pct, ] fill) -> image

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 (transparency) 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

Returns

A new image

Example

This example converts a color image to a "sepia-tone-ish" image using the quantize and colorize methods.

colorize example

See also

sepiatone

Magick API

ColorizeImage

colormap

img.colormap(index[, new_color]) -> string

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.

Raises IndexError if the image does not contain a color map. Only PseudoClass images have a color map.

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

color_point

img.color_point(x, y, fill) -> image

Description

Set the color of the pixel at x,y to the fill color. This method creates a new image object. If you want to set a single pixel in the image without creating a new image, 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 new image

Example

f.color_point(50,50, 'red')

See also

pixel_color, Draw#point

Magick API

GetImagePixels, SyncImagePixels

color_reset!

img.color_reset!(fill) -> self

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

self

Example

f.color_reset!(red)

See also

erase!

Magick API

SetImage

compare_channel

img.compare_channel(img, metric [, channel...]) [ { optional arguments } ] -> [image, float]

Description

Compares img with the receiver.

Arguments

image
Either an imagelist or an image. If an imagelist, uses the current image.
metric
The desired distortion metric. A MetricType value.
channel...
Zero or more ChannelType values. All the specified channels contribute to the comparison and the distortion value. If no channels are specified, compares all channels.
optional arguments
If present, compare_channel yields to a block in which you can set optional arguments by setting attributes on self. In both cases color may be either a color name or a pixel.
options.highlight_color = color
Emphasize pixel differences with this color. The default is partially transparent red.
options.lowlight_color = color
Demphasize pixel differences with this color. The default is partially transparent white.

Returns

An array. The first element is a difference image, the second is a the value of the computed distortion represented as a Float.

See also

difference, <=>, distortion_channel

Magick API

ImageCompareChannels

Notes

This method was named channel_compare in earlier releases of RMagick. That name remains an alias for compare_channel.

composite

dest.composite(src, x, y, composite_op) -> image
dest.composite(src, gravity, composite_op) -> image
dest.composite(src, gravity, x, y, composite_op) -> image

Description

Composites src onto dest using the specified composite operator.

Arguments

The composite method can be called three different ways:

1. Without a gravity argument:
src
Either an imagelist or an image. If an imagelist, uses the current image.
x, y
The x- and y-offset of the composited image, measured from the upper-left corner of the image.
composite_op
A CompositeOperator value.
2. With a gravity argument, without x and y arguments:
src
Either an imagelist or an image. If an imagelist, uses the current image.
gravity
A GravityType value that specifies the location of img on image:
NorthWestGravity
The composited image abuts the top and left sides of the image.
NorthGravity
The composited image is centered left-to-right and abuts the top of the image.
NorthEastGravity
The composited image abuts the top and right sides of the image.
EastGravity
The composited image is centered top-to-bottom and abuts the right side of the image.
SouthEastGravity
The composited image abuts the bottom and right sides of the image.
SouthGravity
The composited image is centered left-to-right and abuts the bottom of the image.
SouthWestGravity
The composited image abuts the bottom and left sides of the image.
WestGravity
The composited image is centered top-to-bottom and abuts the left side of the image.
CenterGravity
The composited image is centered left-to-right and top-to-bottom.
composite_op
A CompositeOperator value.
3. With gravity, x, and y arguments:
src
Either an imagelist or an image. If an imagelist, uses the current image.
gravity
A GravityType value.
x, y
The x- and y-offset of the composited image, measured relative to the gravity argument.
composite_op
A CompositeOperator value.

Returns

A new image

Example

This example shows the effect of some of the composite operators.

composite example

See also

composite!, dissolve, watermark

Magick API

CompositeImage

composite!

dest.composite!(src, x, y, composite_op) -> self
dest.composite!(src, gravity, composite_op) -> self
dest.composite!(src, gravity, x, y, composite_op) -> self

Description

In-place form of composite.

Returns

self

composite_affine

dest.composite_affine(src, affine) -> image

Description

Composite src over dest as dictated by the affine argument.

Arguments

img
An image or imagelist
affine
An AffineMatrix

Returns

A new image

See also

composite, affine_transform

Magick API

DrawAffineImage

composite_mathematics

dest.composite_mathematics(src, a, b, c, d, gravity) -> image
dest.composite_mathematics(src, a, b, c, d, x, y) -> image
dest.composite_mathematics(src, a, b, c, d, gravity, x, y) -> image

Description

Merge the source and destination images according to the formula a*Sc*Dc + b*Sc + c*Dc + d where Sc is the source pixel and Dc is the destination pixel.

Equivalent to the -compose Mathematics -set option:compose:args a,b,c,d options to ImagMagick's convert command. See Examples of ImageMagick Usage.

Arguments

src
Either an imagelist or an image. If an imagelist, uses the current image.
a, b, c, d
See the description.
gravity
A GravityType value. If omitted, the default gravity is NorthWestGravity.
x, y
The x- and y-offset of the composited image, measured relative to the gravity argument. If omitted, the default value is 0.0.

Returns

A new image

See also

composite

Magick API

CompositeImage

composite_tiled

img.composite_tiled(src, composite_op = Magick::OverCompositeOp) -> image

Description

Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile option.

Arguments

src
The source image
composite_op
A CompositeOperator value

Returns

A new image

See also

composite, composite_tiled!

Magick API

CompositeImage

composite_tiled!

img.composite_tiled!(src, composite_op = Magick::OverCompositeOp) -> self

Description

In-place form of composite_tiled.

Example

composite_tiled example

Returns

self

See also

composite!, composite_tiled

Magick API

CompositeImage

compress_colormap!

img.compress_colormap! -> self

Description

Removes duplicate or unused entries in the colormap. Only PseudoClass images have a colormap. If the image is DirectClass then compress_colormap! converts it to PseudoClass.

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

img.contrast(sharpen=false) -> image

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

In this example the contrast is reduced in each successive image.

contrast example

See also

contrast_stretch_channel, sigmoidal_contrast_channel

Magick API

ContrastImage

contrast_stretch_channel

img.contrast_stretch_channel(black_point [, white_point] [, channel...]) -> image

Description

This method is a simple image enhancement technique that attempts to improve the contrast in an image by `stretching' the range of intensity values it contains to span a desired range of values. It differs from the more sophisticated histogram equalization in that it can only apply a linear scaling function to the image pixel values. As a result the `enhancement' is less harsh.

Arguments

black_point
black out at most this many pixels. Specify an absolute number of pixels as a numeric value, or a percentage as a string in the form 'NN%'.
white_point
burn at most this many pixels. Specify an absolute number of pixels as a numeric value, or a percentage as a string in the form 'NN%'. This argument is optional. If not specified the default is all pixels - black_point pixels.
channel...
0 or more ChannelType arguments. If no channels are specified all channels are included.

Returns

A new image

See also

contrast, equalize

Magick API

ContrastStretchImage

convolve

img.convolve(order, kernel) -> image

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

See also

convolve_channel. The edge, emboss, gaussian_blur, motion_blur and sharpen methods use convolution to do their work.

Magick API

ConvolveImage

Note

See Convolution in the Hypermedia Image Processing Reference

convolve_channel

img.convolve_channel(order, kernel [, channel...]) -> image

Description

Applies a custom convolution kernel to the specified channel or channels in the image.

Arguments

order
The number of columns and rows in the kernel.
kernel
An order*order matrix of Float values.
channel...
0 or more ChannelType arguments. If no channels are specified the effect is the same as calling convolve.

Returns

A new image

Magick API

ConvolveImageChannel

See also

convolve

copy

img.copy -> other_image

Description

Returns a copy of the image. The tainted state of the original is propagated to the copy.

Example

f2 = f.copy

See also

clone, dup, ImageList#copy

Magick API

CloneImage

crop

img.crop(x, y, width, height) -> image
img.crop(gravity, x, y, width, height) -> image
img.crop(gravity, width, height) -> image

Description

Extracts the specified rectangle from the image.

Arguments

The crop method can be called three different ways:

1. Without a gravity argument:
x, y
The x- and y-offset of the rectangle relative to the upper-left corner of the image
width, height
The width and height of the rectangle.
2. With a gravity argument, but without x and y arguments:
gravity
A GravityType value specifying the position of the rectangle.
NorthWestGravity
The rectangle abuts the top and left sides of the image.
NorthGravity
The rectangle is centered left-to-right and abuts the top of the image.
NorthEastGravity
The rectangle abuts the top and right sides of the image.
EastGravity
The rectangle is centered top-to-bottom and abuts the right side of the image.
SouthEastGravity
The rectangle abuts the bottom and right sides of the image.
SouthGravity
The rectangle is centered left-to-right and abuts the bottom of the image.
SouthWestGravity
The rectangle abuts the bottom and left sides of the image.
WestGravity
The rectangle is centered top-to-bottom and abuts the left side of the image.
CenterGravity
The rectangle is centered left-to-right and top-to-bottom.
width, height
The width and height of the rectangle.
3. With gravity, x, and y arguments:
gravity
A GravityType value. If the argument is NorthEastGravity, EastGravity, or SouthEastGravity, the x-offset is measured from the right side of the image. If the argument is SouthEastGravity, SouthGravity, or SouthWestGravity, the y-offset is measured from the bottom of the image. All other values are ignored and the x- and y-offsets are measured from the upper-left corner of the image.
x, y
The x- and y-offset of the rectangle from the sides specified by the gravity argument.
width, height
The width and height of the rectangle.

Notes

The crop method retains the offset information in the cropped image. This may cause the image to appear to be surrounded by blank or black space when viewed with an external viewer. This only occurs when the image is saved in a format (such as GIF) that saves offset information. To reset the offset data, add true as the last argument to crop. For example,
cropped = img.crop(x, y, width, height, true)

You can add true as the last argument with any of the three argument list formats described above.

Returns

A new image

Example

The crop rectangle is highlighted in the "before" image.

crop example

Example 2

crop_with_gravity.rb

See also

crop!, chop, excerpt

Magick API

CropImage

crop!

img.crop!(x, y, width, height) -> self
img.crop!(gravity, x, y, width, height) -> self
img.crop!(gravity, width, height) -> self

Description

The in-place form of crop.

Returns

self

crop_resized

img.crop_resized(width, height, gravity=CenterGravity) -> image

Description

An alias for resize_to_fill.

cycle_colormap

img.cycle_colormap(amount) -> image

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.

The returned image is always a PseudoClass image, regardless of the type of the original image.

Arguments

The number of positions to cycle.

Returns

A new image

Example

Mouse over the image to see an animation made by cycling the colormap between each copy.

cycle_colormap example

Magick API

CycleColormapImage

decipher

img.decipher(passphrase) -> image

Description

Decipher an enciphered image.

Arguments

The passphrase used to encipher the image.

Returns

A new image

Example

deciphered_img = img.decipher("magic word")

Magick API

DecipherImage

See also

encipher

delete_compose_mask

img.delete_compose_mask() -> self

Description

Deletes the mask added by add_compose_mask.

Returns

self

See also

add_compose_mask

Magick API

SetImageMask

delete_profile

img.delete_profile(profile_name) -> self

Description

Deletes the specified profile. This method is effectively the same as passing a nil 2nd argument to profile!.

Arguments

The profile name, "IPTC" or "ICC" for example. Specify "*" to delete all the profiles in the image.

See also

Setting the iptc_profile attribute or color_profile attribute to nil causes the profile to be deleted. Also see strip! and add_profile.

Magick API

ProfileImage

deskew

img.deskew(threshold=0.40, auto_crop_width=nil) -> image

Description

Straightens an image. A threshold of 40% works for most images.

Arguments

threshold
A percentage of QuantumRange. Either a Float between 0 and 1.0, inclusive, or a string in the form "NN%" where NN is between 0 and 100.
auto_crop_width
Specify a value for this argument to cause the deskewed image to be auto-cropped. The argument is the pixel width of the image background (e.g. 40).

Returns

A new image

Example

img2 = img.deskew

Magick API

DeskewImage (available in 6.4.2)

despeckle

img.despeckle -> image

Description

Reduces the speckle noise while preserving the edges.

Returns

A new image

Magick API

DespeckleImage

destroy!

img.destroy! -> self

Description

Returns all the memory associated with the image to the system. After an image has been destroyed, all Image methods (except destroyed? and inspect) called on the image will raise a DestroyedImageError.

It is not possible to recover a destroyed image.

Returns

self

See also

check_destroyed, destroyed?

destroyed?

img.destroyed? -> true or false

Description

Returns true if the image has been destroyed, false otherwise.

See also

check_destroyed, destroy!

difference

img.difference(other) -> array

Description

Compares two images and computes statistics about their difference.

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

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.

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

See also

<=>

Magick API

IsImagesEqual

dispatch

img.dispatch(x, y, columns, rows, map, float=false) -> array

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..QuantumRange.

Returns

An array

Example

pixels = f.dispatch(0, 0, f.columns, f.rows, "RGB")

See also

constitute, export_pixels, get_pixels

Magick API

ExportImagePixels

Note

This method is deprecated in ImageMagick. Use the export_pixels method instead.

displace

img.displace(displacement_map, x_amplitude, y_amplitude, x_offset=0, y_offset=0) -> image
img.displace(displacement_map, x_amplitude, y_amplitude, gravity, x_offset=0, y_offset=0) -> image

Description

Uses displacement_map to move color from img to the output image.

This method corresponds to the -displace option of ImageMagick's composite command.

Arguments

displacement_map
The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.
x_amplitude
The maximum displacement on the x-axis.
y_amplitude
The maximum displacement on the y-axis. This argument may omitted if no other arguments follow it. In this case the default is the value of x_amplitude.

The displace method can be called with or without a gravity argument. The gravity, x_offset, and y_offset arguments are described in the documentation for watermark.

Example

See "Composite Displacement Maps" in Anthony Thyssen's Examples of ImageMagick Usage.

Returns

A new image

See also

composite

display

img.display [ { optional arguments } ] -> self

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

Note

The display method is not supported on native MS Windows.

Magick API

DisplayImages

dissolve

img.dissolve(overlay, src_percentage, dst_percentage, x_offset=0, y_offset=0) -> image
img.dissolve(overlay, src_percentage, dst_percentage, gravity, x_offset=0, y_offset=0) -> image

Description

Composites the overlay image into the target image. The opacity of img is multiplied by dst_percentage and opacity of overlay is multiplied by src_percentage.

This method corresponds to the -dissolve option of ImageMagick's composite command.

Arguments

overlay
The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.
src_percentage
Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.
dst_percentage
Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no other arguments follow it. In this case img's opacity is unchanged.

The dissolve method can be called with or without a gravity argument. The gravity, x_offset, and y_offset arguments are described in the documentation for watermark.

Example

See " Dissolve One Image Over Another" in Anthony Thyssen's Examples of ImageMagick Usage.

bgnd.dissolve(overlay, 0.50, 1.0)

dissolve example

Returns

A new image

See also

blend, composite

distort

img.distort(type, points, bestfit=false) [ { optional arguments } ] -> image

Description

Distort an image using the specified distortion type and its required arguments. This method is equivalent to ImageMagick's -distort option.

Arguments

type
One of the following values:
  • AffineDistortion
  • AffineProjectionDistortion
  • ArcDistortion
  • BarrelDistortion
  • BarrelInverseDistortion
  • BilinearDistortion
  • PerspectiveDistortion
  • PerspectiveProjectionDistortion
  • PolynomialDistortion
  • ScaleRotateTranslateDistortion
  • ShepardsDistortion
points
An array of numbers. The size of the array depends on the distortion type.
bestfit
If bestfit is enabled, and the distortion allows it, the destination image is adjusted to ensure the whole source image will just fit within the final destination image, which will be sized and offset accordingly. Also in many cases the virtual offset of the source image will be taken into account in the mapping.
optional arguments
If present, distort yields to a block in which you can set optional arguments by calling methods on self.
options.define("distort:viewport", "WxH+X+Y")
Specify the size and offset of the generated viewport image of the distorted image space. W and H are the width and height, and X and Y are the offset.
options.define("distort:scale", N)
N is an integer factor. Scale the output image (viewport or otherwise) by that factor without changing the viewed contents of the distorted image. This can be used either for 'super-sampling' the image for a higher quality result, or for panning and zooming around the image (with appropriate viewport changes, or post-distort cropping and resizing).
options.verbose(true)
Attempt to output the internal coefficients, and the -fx equivalent to the distortion, for expert study, and debugging purposes. This many not be available for all distorts.

Returns

A new image

Example

result = img.distort(Magick::ScaleRotateTranslateDistortion, [0]) do |options|
  options.define "distort:viewport", "44x44+15+0"
  options.define "distort:scale", 2
end

Note

See Distortion Operator in Anthony Thyssen's excellent Examples of ImageMagick Usage for more information about distortion operations.

distortion_channel

img.distortion_channel(reconstructed_image, metric[, channel...]) -> float

Description

(C)ompares one or more image channels of an image to a reconstructed image and returns the specified distortion metric.

Arguments

reconstructed_image
Either an imagelist or an image. If an imagelist, uses the current image.
metric
The desired distortion metric. A MetricType value.
channel...
Zero or more ChannelType values. All the specified channels contribute to the comparison and the distortion value. If no channels are specified, compares all channels.

Returns

The distortion metric, represented as a floating-point number.

Magick API

GetImageChannelDistortion

See also

compare_channel, difference

dup

img.dup -> other_image

Description

Same as copy.

Returns

A new image

See also

clone