RMagick: class Image (class and instance methods, part 1)

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 = Magick::Image.capture {
 self.filename = "root"
 }

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

Returns

An image constructed from the pixel data.

Example

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

Creates one or more images from the image file.

Arguments

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

Returns

An array containing 0 or more Image objects. If the file is a multi-image file such as an animated GIF or a Photoshop PSD file with multiple layers, the array contains an Image object for each image or layer in the file.

Example

animated = Magick::Image.read("animated.gif") »
[animated.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b
animated.gif[1] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b,
animated.gif[2] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b]

Magick API

ReadImage

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, you can use the scene and number_scenes attributes.

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. ×Magick 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

×Magick 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 image is less than, equal to, or greater than anOtherImage 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 image.signature <=> anOtherImage.signature.

Magick API

SignatureImage

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 (available in ImageMagick 6.2.7)

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 (available in ImageMagick 6.2.7)

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

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.

Magick API

AddNoiseImage

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 (available in ImageMagick 6.2.5)

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 scales the receiver by -1 in both the x- and y-direction, and skews it by π/6 radians along both axes.

Magick API

AffineTransformImage

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

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 (available in ImageMagick 6.2.8), TransverseImage (available in ImageMagick 6.2.8)

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 MaxRGB.
channel...: 0 or more ChannelType arguments. If no channels are specified, all the channels are thresholded.

Returns

A new image

Example

bilevel_channel(2*MaxRGB/3, RedChannel)

Magick API

BilevelImageChannel

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, all channels are blurred. This is the equivalent of blur_image.

Returns

A new image

RMagick User's Guide and Reference

class Image < Object (class and instance methods, part 1) mixes in Comparable

Table of Contents

class methods

instance methods

class methods

capture

Description

Arguments

Returns

Example

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

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_sharpen

Description

Arguments

Returns

See also

Magick API

adaptive_sharpen_channel

Description

class Image < Object (class and instance methods, part 1)
mixes in Comparable