# class Image

### Table Of Contents

### class methods

- constitute
- from_blob
- new
- ping
- read

### instance methods

- [ ]
- [ ]=
- <=>
- ==
- add_noise
- affine_transform
- blur_image
- border
- changed?
- channel
- charcoal
- chop
- color_fill_to_border
- color_floodfill
- colorize
- colormap
- color_point
- color_reset!
- composite
- composite_affine
- compress_colormap!
- contrast
- convolve
- copy
- crop
- cycle_colormap
- despeckle
- difference
- dispatch
- display
- edge
- emboss
- enhance

- equalize
- erase!
- flip
- flop
- frame
- gamma_correct
- gaussian_blur
- get_pixels
- gray?
- grey?
- implode
- inspect
- level
- magnify
- map
- matte_fill_to_border
- matte_floodfill
- matte_point
- matte_replace
- matte_reset!
- median_filter
- minify
- modulate
- monochrome?
- motion_blur
- negate
- normalize
- oil_paint
- opaque
- opaque?
- ordered_dither
- palette?

- pixel_color
- profile!
- properties
- quantize
- raise
- reduce_noise
- resize
- roll
- rotate
- sample
- scale
- segment
- shade
- sharpen
- shave
- shear
- signature
- solarize
- spread
- stegano
- stereo
- store_pixels
- swirl
- texture_fill_to_border
- texture_floodfill
- threshold
- to_blob
- to_color
- transparent
- unsharp_mask
- wave
- write

## class methods

constitute | Image.constitute(width, height, map, pixels) -> anImage
Description | Creates an image from an array of pixels.

Arguments

width
  The number of columns in the image
height
  The number of rows in the image
map
  A string describing the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
pixels
  The pixel data. The pixel data in the array must be stored in scanline order, left-to-right and top-to-bottom. The elements in the array must be either all `Integers` or all `Floats`. If the elements are `Integers`, the `Integers` must be in the range [0..MaxRGB]. If the elements are `Floats`, they must be in the range [0..1].

Returns | An image constructed from the pixel data.
Example |
ImageMagick API | ConstituteImage
See also | dispatch store_pixels
Advanced | This method is the reverse of dispatch. Since all the pixel data must be in memory at once, constitute is useful for constructing only relatively small images, or processing large images in many small chunks. For medium-to-large images, use set_pixels instead. Also, constitute is as slow as Christmas.
from_blob | Image.from_blob(aString) [ { optional arguments } ] -> anArray
Description | Creates an array of images from a BLOB, that is, a Binary Large OBject. In RMagick, a BLOB is a string.
Arguments | A string produced by the to_blob method. Control the format of the created image(s) by setting additional Image::Info attributes in the optional block argument.
Returns | An array of one or more images constructed from the BLOB.
Example | See to_blob.
ImageMagick API | BlobToImage
See also | to_blob Image#from_blob Image#to_blob
new | Image.new(width, height [, fill]) [ { optional arguments } ] -> anImage
Description | Creates a new instance with the specified number of columns and rows. You can specify other arguments by setting Image::Info attributes in the optional block. If the optional fill argument is not specified, the image is set to the background color.

Arguments

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

Returns | An image
ImageMagick API | AllocateImage
See also | ImageList.new_image
ping | Image.ping(filename) [ { optional arguments } ] -> anArray
Description | Creates one or more images from the image file, omitting the pixel data. Only the attributes are stored in the images. This method is faster than read and uses less memory.
Arguments | An image file name. 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

ImageMagick API | PingImage
See also | read
read | Image.read(filename) [ { optional arguments } ] -> anArray
Description | Creates one or more images from the image file.
Arguments | An image file name. You can specify other arguments by setting Image::Info attributes in the optional block.
Returns | An array containing 0 or more images.

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]

ImageMagick API | ReadImage

## instance methods

[ ] | image[key] -> value
Description | Returns the value of the image property identified by `key`. An image may have any number of properties. Each property is identified by a string (or symbol) key. The property value is a string. ImageMagick predefines some properties, including `Label`, `Comment`, and `Signature`.
Arguments | The key may be a string or a symbol.
Returns | The value of the property, a string.
Example | `mom['Label'] = 'My Mother'`
ImageMagick API | GetImageAttribute
See also | [ ]=
Advanced | ImageMagick calls properties "attributes." I use the word "properties" to reduce the confusion with image object attributes such as rows and columns.
[ ]= | image[key] = value -> image
Description | Sets the value of an image property.
Arguments | The key may be a string or a symbol. The value can be any string.
Example | See demo.rb for an example of the use of the `Label` property.
ImageMagick API | SetImageAttribute
See also | [ ]
<=> | image <=> anOtherImage -> -1, 0, 1
Description | Compares two images and returns -1, 0, or 1 if `image` is less than, equal to, or greater than `anOtherImage`. The value returned is the value of `image.signature <=> anOtherImage.signature`.
See also | signature, difference
Advanced | The difference method compares images (for equality only) but also returns information about the amount two images differ, which may be more useful.
== | image == anOtherImage -> `true` or `false`
Description | Compares two images for equality. To be equal, the images must match exactly, pixel-for-pixel.

Example

    violin  = Magick::Image.read("Violin.jpg").first
            » Violin.jpg JPEG 416x622 DirectClass 8-bit 39188b
    violin2 = violin.copy
            » Violin.jpg JPEG 416x622 DirectClass 8-bit 39188b
    violin2 == violin
            » true

ImageMagick API | IsImagesEqual
See also | <=>, difference
add_noise | image.add_noise(aNoiseType) -> anImage
Description | Adds random noise to the image.
Arguments | A NoiseType constant.
Returns | A copy of the image with the noise added.

Example

The right-hand side of this image shows the effect of the add_noise method with the MultiplicativeGaussianNoise argument. |

ImageMagick API | AddNoiseImage
Advanced | The amount of time add_noise requires depends on the NoiseType constant.
affine_transform | image.affine_transform(anAffineMatrix) -> anImage
Description | Transforms the image as specified by the affine matrix.
Arguments | An `AffineMatrix` object.
Returns | A copy of the image, suitably transformed.

Example

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

ImageMagick API | AffineTransformImage
See also | rotate, shear
Advanced | See Coordinate system transformations in the Scalable Vector Graphics (SVG) 1.0 Specification for more information about transformation matrices.
blur_image | image.blur_image(radius=0.0, sigma=1.0) -> anImage
Description | Blurs the image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).
Returns | A copy of the image with blurring added.

Example

The right-hand side of this image shows the effect of the blur_image method. |

See Also | gaussian_blur, motion_blur
ImageMagick API | BlurImage
border | image.border(width, height, color) -> anImage
Description | Add a border around the image.

Arguments

width
  Border width in pixels
height
  Border height in pixels
color
  Border color. Use a named color or a Pixel object.

Returns | A new image.
Example |
ImageMagick API | BorderImage
See also | frame
changed? | image.changed? -> `true` or `false`
Description | Returns `true` if any pixel has been altered since the image was constituted.
ImageMagick API | IsTaintImage
channel | image.channel(aChannelType) -> anImage
Description | Extracts a channel from the image. A channel is a particular color component of each pixel in the [image].
Arguments | A ChannelType constant.

Returns

An image in which the RGB values of all the pixels have been set to a gray corresponding to the specified channel value. For example, given a pixel in the original image with the value R=255, G=128, B=0 and the RedChannel argument, the equivalent pixel in the result image will have the value R=255, G=255, and B=255. For the BlueChannel argument, the pixel would have the value R=0, G=0, B=0.

Example | `redch = image.channel(Magick::RedChannel)`
ImageMagick API | ChannelImage
charcoal | image.charcoal(radius=0.0, sigma=1.0) -> anImage
Description | Adds a "charcoal" effect to the image. You can alter the intensity of the effect by changing the radius and sigma arguments.

Arguments

radius
  The radius of the pixel neighborhood.
sigma
  The standard deviation of the Gaussian, in pixels.

Returns | A new image with the charcoal effect.
Example |
ImageMagick API | CharcoalImage
chop | image.chop(x, y, width, height) -> anImage
Description | Removes the specified rectangle and collapses the rest of the image to fill the removed portion.

Arguments

x
  The x offset of the rectangle from the upper-left corner of the image.
y
  The y offset of the rectangle from the upper-left corner of the image.
width
  The width of the rectangle.
height
  The height of the rectangle.

Returns | A new image.

Example

The darkened rectangle in the upper-left corner of the left-hand image corresponds to the rectangle that is to be chopped away. The right-hand image shows the result of chop. |

ImageMagick API | ChopImage
See also | crop
color_fill_to_border | image.color_fill_to_border(x, y, fill) -> anImage
Description | Changes any pixel that is a neighbor of the target pixel and is not the border color to the fill color.

Arguments

x, y
  The target pixel's location.
fill_color
  The fill color. The fill color can be either color name or a Pixel object.

Returns | A new image.

Example

| The left-hand side of the circle is before the call to color_fill_to_border. The right-hand side is after filling with aquamarine, starting from the center and using black as the border color. Contrast the result with the color_floodfill example, below.

ImageMagick API | ColorFloodfillImage
See also | color_floodfill
color_floodfill | image.color_floodfill(x, y, fill) -> anImage
Description | Changes any pixel that is the same color and is a neighbor of the target pixel to the fill color.

Arguments

x, y
  The target pixel's location.
fill_color
  The fill color, either color name or a Pixel object.

Returns | A new image.

Example

The left-hand side of the circle is before the call to color_floodfill. The right half is after filling with aquamarine, starting from the center. Notice that the small plum circles are not changed, unlike in the color_fill_to_border example above. |

ImageMagick API | ColorFloodfillImage
See also | color_fill_to_border, opaque
colorize | image.colorize(red_pct, green_pct, blue_pct, fill) -> anImage
Description | Blend the fill color with the image pixels. The red_pct, green_pct, and blue_pct arguments are the percentage to blend with the red, green, and blue channels.

Arguments

red_pct, green_pct, blue_pct
  The percentage of the fill color red, green, and blue components to blend with the image pixel. For example, `.25` is 25%.
fill
  A color name or a Pixel structure.

Returns | A new image.

Example

| Convert a color image to sepia-tone using the quantize and colorize methods

ImageMagick API | ColorizeImage
colormap | image.colormap(index[, new_color]) -> aString
Description | Returns the color in the color map at the specified index. If the new_color argument is specified, replaces the color at that index with the new color.

Arguments

index
  A number between 0 and the number of colors in the color map. If the value is out of range, colormap raises an IndexError. You can get the number of colors in the color map from the colors attribute.
new_color
  Optional. If specified, may be either a color name or a Pixel.

Returns | The name of the color at the specified location in the color map.
Advanced | Raises IndexError if the image does not contain a color map. Only PseudoClass images have a color map.
color_point | image.color_point(x, y, fill) -> anImage
Description | Set the color of the pixel at x,y to the fill color. Note: this method creates a new image object. If you must set a single pixel, use pixel_color or the Draw#point method.

Arguments

x, y
  The location of the pixel.
fill
  The fill color, either color name or a Pixel object.

Returns | A copy of the image with the pixel set to the new color.

Example

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

ImageMagick API | GetImagePixels, SyncImagePixels
See also | pixel_color
color_reset! | image.color_reset!(fill) -> image
Description | Sets all the pixels in the image to the specified fill color.
Arguments | The fill color, either color name or a Pixel object.
Returns | The image.

Example

`f.color_reset!(red)`

ImageMagick API | SetImage
See also | erase!
composite | image.composite(img, x, y, composite_op) -> anImage image.composite(img, gravity, composite_op) -> anImage
Description | Composites img onto image using the specified composite operator.

Arguments

img
  Either an imagelist or an image. If an imagelist, uses the current image.
x, y
  The x- and y-offset of the composited image.
gravity
  A GravityType constant that specifies the location of img on image. For example, NorthwestGravity causes img to be positioned at the upper left corner of image.
composite_op
  A CompositeOperator constant.

Returns | A new image.

Example

This example shows the effect of some of the composite_op arguments. (The image is half-size. Click here to see the full-size image.) |

ImageMagick API | CompositeImage
composite_affine | image.composite(img, affine) -> anImage
Description | Composite img over the receiver image as dictated by the affine matrix.

Arguments

img
  An image or image
affine
  An `AffineMatrix`

Returns | A new image.
ImageMagick API | DrawAffineImage
See also | composite, affine_transform
compress_colormap! | image.compress_colormap! -> image
Description | Removes duplicate or unused entries in the colormap. Only PseudoClass images have a colormap.
Returns | `self`

Example

    f = Magick::Image.read('cbezier1.gif').first »
             cbezier1.gif GIF 500x350+0+0 PseudoClass 128c 8-bit 177503b
    f.colors » 128
    f.compress_colormap! »
             cbezier1.gif GIF 500x350+0+0 PseudoClass 108c 8-bit 177503b
    f.colors » 108

ImageMagick API | CompressColormap
contrast | image.contrast(sharpen=`false`) -> anImage
Description | Enhances or reduces the intensity differences between the lighter and darker elements of the image.
Arguments | If sharpen is `true`, the contrast is increased, otherwise it is reduced.
Returns | A new image.

Example

Starting at the upper-left, the contrast is reduced in each image.

ImageMagick API | ContrastImage
convolve | image.convolve(order, kernel) -> anImage
Description | Applies a custom convolution kernel to the image.

Arguments

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

Returns | A new image.
ImageMagick API | ConvolveImage
See also | The edge, emboss, gaussian_blur, motion_blur and sharpen methods use convolution to do their work.
Advanced | See Convolution in the Hypermedia Image Processing Reference
copy | image.copy -> anImage
Description | Returns a deep copy of the image
Example | `f2 = f.copy`
ImageMagick API | CloneImage
See also | ImageList#copy
crop | image.crop(x, y, width, height) -> anImage
Description | Extracts the specified rectangle from the image.

Arguments

x, y
  The x- and y-offset of the rectangle relative to the upper-left corner of the image.
width, height
  The width and height of the rectangle.

Returns | A new image containing only the specified rectangle.
Example |
ImageMagick API | CropImage
See also | chop
cycle_colormap | image.cycle_colormap(amount) -> anImage
Description | Displaces the colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.
Returns | A new image
Arguments | The number of positions to cycle.

Example

This example is an animation made from a number of copies of the original image, cycling the colormap between each copy. |

ImageMagick API | CycleColormapImage
despeckle | image.despeckle -> anImage
Description | Reduces the speckle noise while preserving the edges.
Returns | A new image.
ImageMagick API | DespeckleImage
difference | image.difference(other) -> anArray
Description | Compares two images and computes statistics about their difference.
Arguments | Another image or image.

Returns

An array of three `Float` values:

mean error per pixel
  The mean error for any single pixel in the image.
normalized mean error
  The normalized mean quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in the image.
normalized maximum error
  The normalized maximum quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in your image.

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

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

ImageMagick API | IsImagesEqual
See also | ==, <=>
dispatch | image.dispatch(x, y, columns, rows, map, float=`false`) -> anArray
Description | Extracts the pixel data from the specified rectangle and returns it as an array of either `Integer` or `Float` values. The array returned by dispatch is suitable for use as an argument to constitute.

Arguments

x, y
  The offset of the rectangle from the upper-left corner of the image.
columns, rows
  The width and height of the rectangle.
map
  A `String` reflecting the order of the pixel data. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale).
float
  If `true`, the returned array elements will be `Float` values in the range 0..1. If `false`, the returned array elements will be `Integer` values in the range 0..MaxRGB.

Returns | An array.

Example

    #! /usr/local/bin/ruby -w
    require 'RMagick'
    f = Magick::Image.read("images/small.tif").first
    pixels = f.dispatch(0,0,f.columns,f.rows,"RGB")
    # Write the pixels to a file, to be included
    # in the constitute.rb example.
    File.open('pixels.txt', 'w') { |txt|
            txt.puts("Width = #{f.columns}")
            txt.puts("Height = #{f.rows}")
            txt.print('Pixels = [')
            pixels = pixels.join(',')
            pixels.gsub!(/(\d+,){1,10}/) { "#{$&}\n" }
            txt.print(pixels)
            txt.puts(']')
    }
    exit

ImageMagick API | DispatchImage
See also | constitute get_pixels
display | image.display [ { optional arguments } ] -> image
Description | Display the image on an X Window screen. By default, the screen is the local monitor. Right-click the window to display a context menu.
Arguments | You can specify additional arguments by setting Info attributes in a block associated with the method call. Specifically, you can set the name of a non-default X Window screen with the server_name attribute.
Returns | self
ImageMagick API | DisplayImages
edge | image.edge(radius=0.0) -> anImage
Description | Finds edges in the image.
Arguments | The radius of the convolution filter. If the radius is 0, edge selects a suitable default.
Returns | A new image.

Example

The right-hand side of the image has been altered by edge. |

ImageMagick API | EdgeImage
emboss | image.emboss(radius=0.0, sigma=1.0) -> anImage
Description | Adds a 3-dimensional effect.

Arguments

radius
  The radius of the Gaussian operator.
sigma
  The sigma (standard deviation) of the Gaussian operator. This value must be greater than 0.0.

Returns | A new image

Example

| The right-hand side of the image has been altered by emboss.

ImageMagick API | EmbossImage
enhance | image.enhance -> anImage
Description | Applies a digital filter that improves the quality of a noisy image.
Returns | A new image.

Example

The left-hand side has had noise added by add_noise. The right-hand side is the result after using enhance. |

ImageMagick API | EnhanceImage
See also | median_filter, reduce_noise, unsharp_mask
equalize | image.equalize -> anImage
Description | Applies a histogram equalization to the image.
Returns | A new image.

Example

| The right-hand side has been altered by equalize.

ImageMagick API | EqualizeImage
erase! | image.erase! -> image
Description | Sets the entire image to the background color.
Returns | self
ImageMagick API | SetImage
See also | color_reset!
flip | image.flip -> anImage
Description | Create a vertical mirror image of the receiver.
Returns | A new image
Example |
ImageMagick API | FlipImage
See also | flop, affine_transform
flop | image.flop -> anImage
Description | Create a horizontal mirror image of the receiver.
Returns | A new image
Example |
ImageMagick API | FlopImage
See also | flip, affine_transform
frame | image.frame(width=25, height=25, x=25, y=25, inner_bevel=6, outer_bevel=6, color=matte_color) -> anImage
Description | Adds a simulated 3D border.

Arguments

width
  The width of the left and right sides.
height
  The height of the top and bottom sides.
x, y
  The image does not have to be centered in the border. These two arguments specify the offset of the image from the upper-left outside corner of the border.
inner_bevel, outer_bevel
  The width of the inner and outer shadows of the border. These values should be much smaller than the width and height and cannot be greater than 1/2 the lesser of the width or height.
color
  The border color. By default the color is the matte color.

Returns | A new image.
Example |
ImageMagick API | ImageImage
See also | border
gamma_correct | image.gamma_correct(red_gamma[,green_gamma[, blue_gamma[, opacity_gamma]]]) -> anImage
Description | Gamma-correct an image. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen.
Arguments | You must specify at least `red_gamma`. Omitted arguments take on the value of the last specified argument. Values typically range from 0.8 to 2.3.
Returns | A new image.
ImageMagick API | GammanImage
gaussian_blur | image.gaussian_blur(radius, sigma) -> anImage
Description | Blurs an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).

Arguments

radius
  A `Float` value representing the radius of the Gaussian, in pixels, not counting the center pixel.
sigma
  A `Float` value representing the standard deviation of the Gaussian operator, in pixels. This argument must be > 0.0.

Returns | A new image

Example

`gaussian_blur(0.0, 3.0)`

See also | blur_image, motion_blur
ImageMagick API | GaussianBlurImage
get_pixels | image.get_pixels(x, y, columns, rows) -> anArray
Description | Gets the pixels from the specified rectangle within the image.

Arguments

x, y
  The x- and y-offset of the rectangle within the image.
columns, rows
  The width and height of the rectangle.

Returns | An array of pixels. There will be `columns*rows` elements in the array.

Example

This example composites a black-and-white version of an image over the same image in its original colors. It uses get_pixels and store_pixels to make each column of pixels in the black-and-white image slightly more opaque than the column on its left, so that the resulting composite changes smoothly from color on the left to black-and-white on the right.

ImageMagick API | AcquireImagePixels
See also | store_pixels
gray? | image.gray? -> `true` or `false`
Description | Returns `true` if all the pixels in the image have the same red, green, and blue intensities.
Returns | `true` or `false`
ImageMagick API | IsGrayImage
See also | monochrome?
grey? | image.qrey? -> `true` or `false`
Description | Synonym for gray?
implode | image.implode(amount=0.50) -> anImage
Description | A funhouse mirror effect. See the examples below.
Arguments | A `Float` value. Increasing the absolute value of the argument increases the effect. The value may be positive for implosion, or negative for explosion. The default is 0.50.
Returns | A new image
Example |
ImageMagick API | ImplodeImage
inspect | image.inspect -> aString
Description | Displays a description of the image.

Example

    f = Magick::Image.read('implode.jpg').first
    f.inspect » "implode.jpg JPEG 396x280 DirectClass 8-bit 18037b"

level | image.level(black_point=`0.0`, mid_point=`1.0`, white_point=`MaxRGB`) -> anImage
Description | Adjusts the levels of an image given these points: black, mid, and white.

Arguments

black_point
  The black point level. The default is 0.0.
mid_point
  The mid-point level. The default is 1.0.
white_point
  The white point level. The default is MaxRGB.

Returns | A new image
Example |
ImageMagick API | LevelImage
magnify | image.magnify -> anImage
Description | A convenience method that scales the receiver to twice its size.
Returns | A new image
ImageMagick API | MagnifyImage
See also | minify, resize, scale, sample
map | image.map(img, dither=`false`) -> anImage
Description | Replaces the colors of an image with the closest color from a reference image.

Arguments

img
  The reference image. May be either another image or an `Image` object.
dither
  If `true`, dithers the mapped image.

Returns | A new image

Example

The bottom half of this image has been mapped to the Netscape 216-color cube. |

ImageMagick API | MapImage
See also | Image#map
matte_fill_to_border | image.matte_fill_to_border(x, y) -> anImage
Description | Makes transparent all the pixels that are neighbors of the pixel at `x,y` and are not the border color.
Arguments | The x- and y- coordinates of the target pixel.
Returns | A new image
Example |
ImageMagick API | MatteFloodfillImage
See also | matte_floodfill, Draw#matte
matte_floodfill | image.matte_floodfill(x, y) -> anImage
Description | Makes transparent all the pixels that are the same color as the pixel at `x`, `y`, and are neighbors.
Arguments | The x- and y-coordinates of the target pixel.
Returns | A new image.
Example |
ImageMagick API | MatteFloodfilImage
See also | matte_replace, Draw#matte
matte_point | image.matte_point(x, y) -> anImage
Description | Makes the pixel at `x, y` transparent.
Arguments | The x- and y-coordinates of the target pixel.
Returns | A new image

Example

This example creates a transparent pixel in the upper-left portion of the "M". |

See also | Draw#matte
Notes | This method make a copy of the image, just to make one pixel transparent. I recommend using the Draw#matte method instead.
matte_replace | image.matte_replace(x, y) -> anImage
Description | Makes transparent all the pixels that are the same color as the pixel at `x`, `y`.
Arguments | The x- and y-coordinates of the target pixel.
Returns | A new image.
Example |
ImageMagick API | TransparentImage
See also | transparent, Draw#matte
matte_reset! | image.matte_reset! -> anImage
Description | Makes all the pixels in the image transparent.
Returns | A new image
ImageMagick API | SetImageOpacity
See also | opacity=
median_filter | image.median_filter(radius=1.0) -> anImage
Description | Applies a digital filter that improves the quality of a noisy image. Each pixel is replaced by the median in a set of neighboring pixels as defined by radius.
Arguments | The filter radius. The larger the value, the longer it takes to render. Values larger than 8 or 9 may take longer than you want to wait, and will not have significantly better results than much smaller values.
Returns | A new image

Example

The left side of the image has been modified by add_noise. The right side has been filtered by median_filter(0.05)

ImageMagick API | MedianFilterImage
See also | enhance, reduce_noise, unsharp_mask
minify | image.minify -> anImage
Description | A convenience method that scales the receiver to half its size.
Returns | A new image
ImageMagick API | MinifyImage
See also | magnify, resize, sample, scale
modulate | image.modulate(brightness=1.0, saturation=1.0, hue=1.0) -> anImage
Description | Changes the brightness, saturation, and hue.
Arguments | The percent change in the brightness, saturation, and hue, represented as `Float` numbers. For example, 0.25 means "25%". All three arguments may be omitted. The default value of each argument is 1.0, that is, 100%.
Returns | A new image
Example |
ImageMagick API | ModulateImage
monochrome? | image.monochrome? -> `true` or `false`
Description | Returns `true` if all the pixels have the same red, green, and blue values and the values are either 0 or MaxRGB. That is, the image is black-and-white.
ImageMagick API | IsMonochromeImage
See also | gray?
motion_blur | image.motion_blur(radius, sigma, angle) -> anImage
Description | Simulates motion blur. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). Use a radius of 0 and motion_blur selects a suitable radius for you. `Angle` gives the angle of the blurring motion.

Arguments

radius
  The radius of the Gaussian operator.
sigma
  The standard deviation of the Gaussian operator. Must be greater than 0.
angle
  The angle (in degrees) of the blurring motion.

Returns | A new image
Example |
ImageMagick API | MotionBlurImage
See also | blur_image, gaussian_blur
negate | image.negate(grayscale=`false`) -> anImage
Description | Negates the colors in the receiver.
Arguments | If the grayscale argument is true, only the grayscale values are negated.
Returns | A new image
Example |
ImageMagick API | NegateImage
normalize | image.normalize -> anImage
Description | Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available.
Returns | A new image
Example |
ImageMagick API | NormalizeImage
oil_paint | image.oil_paint(radius=3.0) -> anImage
Description | Applies a special effect filter that simulates an oil painting. Each pixel is replaced by the most frequent color occurring in a circular region defined by radius.
Returns | A new image
Example |
ImageMagick API | OilPaintImage
opaque | image.opaque(target, fill) -> anImage
Description | Changes all pixels having the target color to the fill color.

Arguments

target
  The color to be replaced. May be a color name or a `Pixel`
fill
  The replacement color. May be a color name or a `Pixel`

Returns | A new image.
Example |
ImageMagick API | OpaqueImage
See also | color_floodfill
opaque? | image.opaque? -> `true` or `false`
Description | Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.
Returns | `true` or `false`
ImageMagick API | IsOpaqueImage
ordered_dither | image.ordered_dither -> anImage
Description | Uses the ordered dithering technique of reducing color images to monochrome using positional information to retain as much information as possible.
Returns | A new image
Example |
ImageMagick API | OrderedDitherImage
See also | quantize
palette? | image.palette? -> `true` or `false`
Description | Returns true if the image is `PseudoClass` and has 256 unique colors or less.
Returns | `true` or `false`
ImageMagick API | IsPaletteImage
pixel_color | image.pixel_color(x, y[, new_color]) -> aPixel
Description | Returns the color of the pixel at x, y. Optionally, changes the color of the pixel to a new color.

Arguments

x, y
  The x- and y-coordinates of the pixel.
new_color
  If specified, the pixel is set to this color. May be either a color name or a Pixel.

Returns | A `Pixel` having the RGB values of the specified pixel.
Example | `old = image.pixel_color(20,40,"white")`
profile! | image.profile!(name, profile) -> image
Description | Adds or removes a ICM, IPTC, or generic profile from an image. If profile is `nil`, the specified profile is removed from the image. Use `profile('*', nil)` to remove all profiles from the image.

Arguments

name
  The profile name, or "*" to represent all the profiles in the image.
profile
  The profile value, or `nil` to cause the profile to be removed.

Returns | self
ImageMagick API | ProfileImage
Advanced | ImageMagick does not automatically remove profiles when resizing images. If you are trying to make your JPEG thumbnail images as small as possible, use profile! to remove any profiles from the image as well. See Why are my JPEG files larger than expected? in the ImageMagick FAQ.
properties | image.properties [ {|name,value| block} ] -> image image.properties -> aHash
Description | If called with an associated block, properties runs the block once for each property defined for the image. The block arguments are the property name and its value. If there is no block, properties returns a hash with one element for each property. The hash key is the property name and the associated value is the property value.
Returns | If called without a block, returns a hash, otherwise returns `self`.
See also | [ ], [ ]=
quantize | image.quantize(number_colors=256, colorspace=Magick::RGBColorspace, dither=`true`, tree_depth=0, measure_error=`false`) -> anImage
Description | Analyzes the colors within a reference image and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the difference between the input and output image while minimizing the processing time.

Arguments

number_colors
  The maximum number of colors in the result image. Must be <= MaxRGB.
colorspace
  The colorspace to quantize in. Color reduction, by default, takes place in the RGB color space. Empirical evidence suggests that distances in color spaces such as YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. The Transparent color space behaves uniquely in that it preserves the matte channel of the image if it exists.
dither
  Set to `true` to apply Floyd/Steinberg error diffusion to the image. When the size of the color palette is less than the image colors, this trades off spacial resolution for color resolution by dithering to achieve a similar looking image.
tree_depth
  The tree depth to use while quantizing. The values 0 and 1 support automatic tree depth determination. The tree depth may be forced via values ranging from 2 to 8. The ideal tree depth depends on the characteristics of the input image, and may be determined through experimentation.
measure_error
  Set to `true` to calculate quantization errors when quantizing the image.

Returns | A new image.
Example | See the example for colorize.
ImageMagick API | QuantizeImage
See also | Image#quantize
raise | image.raise(width=6, height=6, raised=`true`) -> anImage
Description | Creates a simulated three-dimensional button-like effect by lightening and darkening the edges of the image.

Arguments

width
  The width of the raised edge in pixels. The default is 6.
height
  The height of the raised edge in pixels. The default is 6.
raised
  If `true`, the image is raised, otherwise lowered.

Returns | A new image
Example |
ImageMagick API | RaiseImage
reduce_noise | image.reduce_noise(radius) -> anImage
Description | Smooths the contours of an image while still preserving edge information. The algorithm works by replacing each pixel with its neighbor closest in value.

Arguments

radius
  A neighbor is defined by radius. Use a radius of 0 and reduce_noise selects a suitable radius for you.

Returns | A new image

Example

The left side of the image has been modified by add_noise. The right side has been filtered by reduce_noise(0)

ImageMagick API | ReduceNoiseImage
See also | enhance, reduce_noise, unsharp_mask
resize | image.resize(new_width, new_height, filter=LanczosFilter, blur=1.0) -> anImage image.resize(scale_factor) -> anImage
Description | Changes the size of the receiver to the specified dimensions. You can specify the new size in two ways. Either specify the new width and height explicitly, or specify a scale factor, a number that represents the percentage change.

Arguments

new_width, new_height
  The desired width and height.
filter
  The filter to use when resizing. If you do not specify a filter argument, resize uses the value of the receiver's filter attribute. Most of the filters are FIR (finite impulse response), however, Bessel, Gaussian, and Sinc are IIR (infinite impulse response). Bessel and Sinc are windowed (brought down to zero) with the Blackman filter.
blur
  The blur factor. Values > 1 increase the blurriness. Values < 1 increase the sharpness. If this argument is not specified, resize uses the value of the receiver's blur attribute.
scale_factor
  You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.

Returns | A new image
ImageMagick API | ResizeImage
See also | magnify, minify, sample, scale
roll | image.roll(x_offset, y_offset) -> anImage
Description | Offsets an image as defined by x_offset and y_offset.

Arguments

x_offset
  The number of columns to offset the image.
y_offset
  The number of rows to offset the image.

Returns | A new image

Example

This image has been offset 25% in both directions. |

ImageMagick API | RollImage
rotate | image.rotate(amount) -> anImage
Description | Rotate the receiver by the specified angle. Positive angles rotate counter-clockwise (right-hand rule), while negative angles rotate clockwise. Rotated images are usually larger than the originals and have "empty" triangular corners. Empty triangles left over from shearing the image are filled with the color defined by the pixel at location (0,0).
Arguments | The number of degrees to rotate the image.
Returns | A new image
Example |
ImageMagick API | RotateImage
See also | affine_transform, shear
sample | image.sample(new_width, new_height) -> anImage image.sample(scale_factor) -> anImage
Description | Scales an image to the desired dimensions with pixel sampling. Unlike other scaling methods, this method does not introduce any additional color into the scaled image.

Arguments

new_width, new_height
  The desired width and height.
scale_factor
  You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.

Returns | A new image
ImageMagick API | SampleImage
See also | magnify, minify, resize, scale
scale | image.scale(new_width, new_height) -> anImage image.scale(scale_factor) -> anImage
Description | Changes the size of an image to the given dimensions.

Arguments

new_width, new_height
  The desired width and height.
scale_factor
  You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125% of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.

Returns | A new image
ImageMagick API | ScaleImage
See also | magnify, minify, resize, sample
segment | image.segment(colorspace=RGBColorspace, cluster_threshold=1.0, smoothing_threshold=1.5, verbose=`false`) -> anImage
Description | Segments an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique.

Arguments

colorspace
  A `ColorspaceType` constant. Empirical evidence suggests that distances in YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. The image is then returned to RGB colorspace after color reduction.
cluster_threshold
  The number of pixels in each cluster must exceed the the cluster threshold to be considered valid.
smoothing_threshold
  The smoothing threshold eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative.
verbose
  If `true`, segment prints detailed information about the identified classes.

Returns | A new image
Example |
ImageMagick API | SegmentImage
shade | image.shade(shading=`false`, azimuth=30, elevation=30) -> anImage
Description | Shines a distant light on an image to create a three-dimensional effect. You control the positioning of the light with azimuth and elevation; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis.

Arguments

shading
  If `true`, shade shades the intensity of each pixel.
azimuth, elevation
  The light source direction.

Returns | A new image
Example |
ImageMagick API | ShadeImage
sharpen | image.sharpen(radius=0.0, sigma=1.0) -> anImage
Description | Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and sharpen selects a suitable radius for you.
Arguments | The radius and standard deviation of the Gaussian operator.
Returns | A new image
ImageMagick API | SharpenImage
shave | image.shave(width, height) -> anImage
Description | Removes pixels from the edges of the image, leaving the center rectangle.

Arguments

width
  The number of pixels to remove from each side of the receiver, not to exceed half the original width.
height
  The number of pixels to remove from the top and bottom of the receiver, not to exceed half the original height.

Returns | A new image

Example

ImageMagick API | ShaveImage
See also | crop
shear | image.shear(x_shear, y_shear) -> anImage

Description

Shearing slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x_shear is measured relative to the Y axis, and similarly, for Y direction shears y_shear is measured relative to the X axis. Empty triangles left over from shearing the image are filled with the background color.

Arguments | The X and Y shear angles, measured in degrees. These values must not be 180.0. If either value is 0, no shearing will occur.
Returns | A new image
Example |
ImageMagick API | ShearImage
See also | affine_transform, rotate
signature | image.signature -> aString
Description | Computes a message digest from an image pixel stream with an implementation of the NIST SHA-256 Message Digest algorithm. This signature uniquely identifies the image and is convenient for determining if an image has been modified or whether two images are identical.
Returns | The signature as a 64-character string.

Example

    jj = Magick::Image.read('images/Jean_Jacket.jpg').first
       » images/Jean_Jacket.jpg JPEG 432x576 DirectClass 8-bit 23360b
    puts jj.signature
       » a1dfc12cc2c52cbc42a01dfda1f9c958ae61db3445e5185cee75f26b40effc9c

ImageMagick API | SignatureImage
See also | ==, difference
solarize | image.solarize(threshold=50) -> anImage
Description | Applies a special effect to the image similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light.

Arguments

threshold
  Ranges from 0 to MaxRGB and is a measure of the extent of the solarization. The default is 50.

Returns | A new image
Example |
ImageMagick API | SolarizeImage
spread | image.spread(radius=3) -> anImage
Description | Randomly displaces each pixel in a block defined by the radius parameter.
Returns | A new image
Example |
ImageMagick API | SpreadImage
stegano | image.stegano(watermark, offset) -> anImage
Description | Hides a digital watermark in the receiver. You can retrieve the watermark by reading the file with the `stegano:` prefix, thereby proving the authenticity of the file.

Arguments

watermark
  An image or image to be used as the watermark. The watermark must be grayscale and should be substantially smaller than the receiver. The recovery time is proportional to the size of the watermark.
offset
  The starting position within the receiver at which the watermark will be hidden. When you retrieve the watermark from the file, you must supply this value, along with the width and height of the watermark, in the size optional parameter to the read method.

Returns | A new image with the embedded watermark.
Example |
ImageMagick API | SteganoImage
Notes | The watermarked image must be saved in a lossless format such as GIF, MIFF, or PNG. You cannot save a watermarked image in a lossy format such as JPEG. Once written, the file must not be modified or processed in any way.
stereo | image.stereo(offset_image) -> anImage
Description | Combines two images and produces a single image that is the composite of a left and right image of a stereo pair. Special red-green stereo glasses are required to view this effect.
Arguments | Another image or image. If the argument is an image, uses the current image.
Returns | A new image
ImageMagick API | StereoImage
store_pixels | image.store_pixels(x, y, columns, rows, pixels) -> image
Description | Replace the pixels in the specified rectangle with the pixels in the pixels array.

Arguments

x, y
  The x- and y-offset of the rectangle to be replaced.
columns, rows
  The number of rows and columns in the rectangle.
pixels
  An array of pixels. The number of pixels in the array must be the same as the number of pixels in the rectangle, that is, `rows*columns`.

Returns | The image, with the rectangle suitably altered.
Example | Also see the example for get_pixels.
ImageMagick API | SetImagePixels, SyncImagePixels
See also | get_pixels
swirl | image.swirl(degrees) -> anImage
Description | Swirls the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360.
Arguments | The number of degrees to swirl the image.
Returns | A new image
Example |
ImageMagick API | SwirlImage
texture_fill_to_border | image.texture_fill_to_border(x, y, texture) -> anImage
Description | Replaces the target pixel at `x, y` and its neighbors that are not the border color with the specified texture. Use the fuzz attribute to specify how closely a pixel must match the border color.

Arguments

x, y
  The x- and y-offset of the target pixel.
texture
  An image or image. If an image, uses the current image.

Returns | A new image
Example |
ImageMagick API | ColorFloodfillImage
See also | color_fill_to_border, matte_fill_to_border
texture_floodfill | image.texture_floodfill(x, y, texture) -> anImage
Description | Replaces the target pixel at `x, y` and its neighbors that are the same color with the specified texture. By default, the neighbor pixels must be exactly the same color as the target pixel. Use the fuzz attribute to specify how much difference is acceptable.

Arguments

x, y
  The x- and y-offset of the target pixel.
texture
  An image or image. If an image, uses the current image.

Returns | A new image.
Example |
ImageMagick API | ColorFloodfillImage
See also | color_floodfill, matte_floodfill
threshold | image.threshold(threshold) -> anImage
Description | Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image.
Arguments | A value between 0 and MaxRGB.
Returns | A new image
Example |
ImageMagick API | ThresholdImage
to_blob | image.to_blob [ { optional arguments } ]-> aString
Description | Creates a Binary Large OBject, a direct-to-memory version of the image. The from_blob method constructs an image from a BLOB created by this method.
Arguments | None. However, you can specify the image format (such as JPEG, PNG, etc.) and depth by calling the format and depth attributes, as well as other Image::Info attributes as appropriate, in a block associated with the method.
Returns | A string containing the image data represented as a BLOB.
Example |
ImageMagick API | ImageToBlob
See also | from_blob
to_color | image.to_color(aPixel) -> aString
Description | Returns the color name for a pixel. Unlike the Pixel#to_color method, to_color uses the depth and matte attributes of the image to determine the color name.
Arguments | A Pixel object.
Returns | Either a color name or a color tuple in the form "#RRGGBBOO". If the image depth is 16, the tuple has the form "#RRRRGGGGBBBBOOOO".

Example

    f = Magick::Image.read('images/Jean_Jacket.jpg').first »
            images/Jean_Jacket.jpg JPEG 432x576 DirectClass 8-bit 23360b
    p = f.pixel_color(0,0) »
            #<Magick::Pixel red=16191, green=15677, blue=12593, opacity=0>
    f.to_color(p) » "#3F3D31"

ImageMagick API | QueryColorname
See also | Pixel#to_color
transparent | image.transparent(color[, opacity]) -> anImage
Description | Changes the opacity value of all the pixels that match color to the value specified by opacity. By default the pixel must match exactly, but you can specify a tolerence level by setting the fuzz attribute on the image.

Arguments

color
  Either a color name or a pixel.
opacity
  The new opacity value, either an opacity constant or a number between 0 and MaxRGB. The default is TransparentOpacity.

Returns | A new image.
Example |
ImageMagick API | TransparentImage
See also | matte_replace, Draw#matte
unsharp_mask | image.unsharp_mask(radius, sigma, amount, threshold) -> anImage
Description | Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and unsharp_mask selects a suitable radius for you.

Arguments

radius
  The radius of the Gaussian operator.
sigma
  The standard deviation of the Gaussian operator. A good starting value is 1.0.
amount
  The percentage of the blurred image to be added to the receiver, specified as a fraction between 0 and 1.0. A good starting value is 1.0.
threshold
  The threshold needed to apply the amount, specified as a fraction between 0 and 1.0. A good starting value is 0.05.

Returns | A new image
Example |
ImageMagick API | UnsharpMaskImage
See also | enhance, median_filter, reduce_noise
wave | image.wave(amplitude=25.0, wavelength=150.0) -> anImage
Description | Creates a "ripple" effect in the image by shifting the pixels vertically along a sine wave whose amplitude and wavelength is specified by the given parameters.
Returns | A new image
Example |
ImageMagick API | WaveImage
write | image.write(filename) [ { optional arguments } ] -> image
Description | Writes the image to the specified file. ImageMagick determines image format from the prefix or extension.
Arguments | The file name. You may also specify optional arguments by setting Image::Info attributes in an associated block.
Returns | self, or `nil` if the image format cannot be determined.
Example | Almost all of the examples call write.
ImageMagick API | WriteImage
See also | Image#write