RMagick 2.13.2: class Image (class methods and instance methods a-d)

###### RMagick 2.13.2 User's Guide and Reference

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

## 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 `self.filename = "root"` to capture the entire desktop. To programatically specify the window to be captured, use `self.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 type.

#### Returns

A new image.

#### Example

    img = Image.capture {
     self.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 = 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 = Image.new(256, 64) {
     self.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 = 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 = 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 = 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

#### 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

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

Click the NoiseType to see the effect.

- No noise
- UniformNoise
- GaussianNoise
- MultiplicativeGaussianNoise
- ImpulseNoise
- LaplacianNoise
- PoissonNoise

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

#### 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 AlphaChannelType enumeration:

ActivateAlphaChannel
  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.
DeactivateAlphaChannel
  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.
ResetAlphaChannel
  (Deprecated as of IM 6.4.3-7.) Set the alpha channel to 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)`

#### 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" in Anthony Thyssen's Examples of ImageMagick Usage.

#### 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

#### 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

#### 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.)

### 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 = 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.

#### 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

#### 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!

#### 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 InterpolatePixelMethod 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.

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

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

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

#### 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.
  self.highlight_color = color
    Emphasize pixel differences with this color. The default is partially transparent red.
  self.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.

#### 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

#### 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 = 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.

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

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

#### 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)`

#### 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.
  self.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.
  self.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).
  self.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
                         self.define "distort:viewport", "44x44+15+0"
                         self.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