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

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"
}

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

Magick API

CombineImages

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)

Magick API

ConstituteImage

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

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'
}

Magick API

AllocateImage

Description

Creates one or more images from the image file, omitting the pixel data. Only the attributes are stored in the images. This method is faster than read and uses less memory.

Arguments

An image file name or open file object. You can specify other arguments by setting Image::Info attributes in the optional block.

Returns

An array containing 0 or more images.

Example

cheetah = Magick::Image.ping("Cheetah.jpg") #=> [Cheetah.jpg JPEG 1024x768 DirectClass 8-bit 101684b]
p cheetah[0].rows    #=> 768
p cheetah[0].columns #=> 1024

Magick API

PingImage

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]

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

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)

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'

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.

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.

Magick API

SetImageAttribute

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.

Magick API

SignatureImage

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

Magick API

AdaptiveBlurImage

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

Magick API

AdaptiveBlurImageChannel

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

Magick API

AdaptiveResizeImage

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

Magick API

AdaptiveSharpenImage

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

Magick API

AdaptiveSharpenImageChannel

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

Magick API

AdaptiveThresholdImage

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

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

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.

Notes

The RandomNoise type was added in ImageMagick 6.3.5.

Magick API

AddNoiseImage

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')

Magick API

ProfileImage

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

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.

Magick API

AffineTransformImage

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.

Notes

Available in ImageMagick 6.3.5 and later.

Magick API

SetImageAlphaChannel

Description

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

Magick API

GetImageAlphaChannel

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

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

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

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

Magick API

FlipImage, FlopImage, RotateImage, TransposeImage, TransverseImage

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

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)

Magick API

BilevelImageChannel

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

Magick API

BlackThresholdImage

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

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

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

Magick API

BlurImageChannel

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

Magick API

BlurImage

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

Magick API

BorderImage

Description

In-place form of border

Returns

self

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

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.

Description

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

Magick API

IsTaintImage

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

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

Magick API

GetImageChannelDepth

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

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

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

Description

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

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!

Magick API

ChopImage

Description

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

Returns

A new image

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

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.

Magick API

ColorFloodfillImage

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.

Magick API

ColorFloodfillImage

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

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.

Magick API

ColorizeImage

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

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')

Magick API

GetImagePixels, SyncImagePixels

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)

Magick API

SetImage

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.

Magick API

ImageCompareChannels

Notes

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

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.

Magick API

CompositeImage

Description

In-place form of composite.

Returns

self

Description

Composite src over dest as dictated by the affine argument.

Arguments

img: An image or imagelist
affine: An AffineMatrix

Returns

A new image

Magick API

DrawAffineImage

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

Magick API

CompositeImage

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

Magick API

CompositeImage

Description

In-place form of composite_tiled.

Example

Returns

self

Magick API

CompositeImage

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

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.

Magick API

ContrastImage

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

Magick API

ContrastStretchImage

Description

Applies a custom convolution kernel to the image.

Arguments

order: The number of columns and rows in the kernel.
kernel: An order*order matrix of Float values.

Returns

A new image

Magick API

ConvolveImage

Note

See Convolution in the Hypermedia Image Processing Reference

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

Description

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

Example

f2 = f.copy

Magick API

CloneImage

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

Magick API

CropImage

Description

The in-place form of crop.

Returns

self

Description

An alias for resize_to_fill.

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

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

Description

Deletes the mask added by add_compose_mask.

Returns

self

Magick API

SetImageMask

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.

Magick API

ProfileImage

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)

Description

Reduces the speckle noise while preserving the edges.

Returns

A new image

Magick API

DespeckleImage

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

Description

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

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.

Magick API

IsImagesEqual

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")

Magick API

ExportImagePixels

Note

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

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

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

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

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.

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

Description

Same as copy.

Returns

A new image

RMagick 6.0.1 User's Guide and Reference

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

Table of Contents

class methods

instance methods

class methods

capture

Description

Arguments

Returns

Example

combine

Description

Arguments

Returns

See also

Magick API

constitute

Description

Arguments

Returns

Example

See also

Magick API

from_blob

Description

Arguments

Returns

Example

Magick API

new

Description

Arguments

Returns

Example

See also

Magick API

ping

Description

Arguments

Returns

Example

See also

Magick API

read

Description

Arguments

Returns

Example

See also

Note

Magick API

read_inline

Description

Arguments

Returns

Example

See also

instance methods

[ ]

Description

Arguments

Returns

Example

See also

Magick API

Note

[ ]=

Description

Arguments

Returns

Example

See also

Magick API

<=>

Description

Returns

See also

Magick API

adaptive_blur

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