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

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

## instance methods

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

#### See also

median_filter, reduce_noise, unsharp_mask

#### Magick API

EnhanceImage

### equalize

image.equalize -> anImage

#### Description

Applies a histogram equalization to the image.

#### Returns

A new image

#### Example

#### Magick API

EqualizeImage

### erase!

image.erase! -> image

#### Description

Sets the entire image to the background color.

#### Returns

self

#### See also

color_reset!

#### Magick API

SetImage

### export_pixels

image.export_pixels(x, y, columns, rows, map) -> anArray

#### Description

Extracts the pixel data from the specified rectangle and returns it as an array of `Integer` values.

The array returned by `export_pixels` is suitable for use as an argument to `import_pixels`.

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

#### Returns

An array

#### Example

    # Export the r'th scanline from an image in red-green-blue order
    scanline = img.export_pixels(0, r, img.columns, 1, "RGB");

#### See also

dispatch, import_pixels, get_pixels

#### Magick API

ExportImagePixels

#### Note

This method replaces the `dispatch` method.

### flip

image.flip -> anImage

#### Description

Create a vertical mirror image of the receiver.

#### Returns

A new image

#### Example

#### See also

flip!, flop, affine_transform

#### Magick API

FlipImage

### flip!

image.flip! -> image

#### Description

In-place form of flip.

#### Returns

self

### flop

image.flop -> anImage

#### Description

Create a horizontal mirror image of the receiver.

#### Returns

A new image

#### Example

#### See also

flop!, flip, affine_transform

#### Magick API

FlopImage

### flop!

image.flop! -> image

#### Description

In-place form of flop.

#### Returns

self

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

#### See also

border

#### Magick API

FrameImage

### gamma_channel

image.gamma_channel(gamma, [channel...]) = anImage

#### Description

Gamma-correct a particular image channel. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen.

#### Arguments

gamma
  Values typically range from 0.8 to 2.3. You can also reduce the influence of a particular channel with a gamma value of 0.
channel...
  0 or more ChannelType arguments. If no channels are specified, all the channels are corrected using the gamma value.

#### Returns

A new image

#### See also

The older gamma_correct method is implemented in terms of `gamma_channel`.

#### Magick API

GammaImageChannel

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

#### See also

gamma_channel

#### Magick API

GammaImage

### gaussian_blur

image.gaussian_blur(radius=0.0, sigma=1.0) -> 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, radial_blur

#### Magick API

GaussianBlurImage

### gaussian_blur_channel

image.gaussian_blur_channel(radius=0.0, sigma=1.0[, channel...]) -> anImage

#### Description

Blurs the selected channel or channels using a Gaussian operator of the specified radius and standard deviation.

#### 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.
channel...
  0 or more ChannelType arguments. If no channels are specified, all the channels are blurred. This is the same as using gaussian_blur.

#### Returns

A new image

#### See also

blur_channel

#### Magick API

GaussianBlurImageChannel (available in ImageMagick 6.0.0)

### get_exif_by_entry

image.get_exif_by_entry([name]*) -> anArray

#### Description

Returns the value associated with the specified EXIF entry name or names. If no names are specified, returns all the entries. The return value is an array containing one or more [name, value] elements.

#### Arguments

Zero or more EXIF entry names.

#### Returns

The elements in the returned array are 2-element arrays in the form [name, value]. If ×Magick does not know the name for an entry it uses "unknown." There may be more than one entry for "unknown" in the returned array. If there is no entry with the specified name the value is set to `nil`.

#### Example

    image.get_exif_by_entry('Make') » [["Make", "Canon"]]
    image.get_exif_by_entry("ShutterSpeedValue") »
        [["ShutterSpeedValue", "189/32"]]
    image.get_exif_by_entry() »
        [["Make", "Canon"], ["ShutterSpeedValue", "189/32"] ...]

#### See also

get_exif_by_number

### get_exif_by_number

image.get_exif_by_number([tag]*) -> aHash

#### Description

Returns the value associated with the specified EXIF tag number or numbers. If no numbers are specified, returns all the tags. The return value is a hash. The hash keys are EXIF tag numbers. The values are the values associated with the tags.

#### Arguments

Zero or more EXIF tag numbers.

#### Returns

A hash. If there is no tag with the specified number the value is set to `nil`.

#### Example

    image.get_exif_by_number(271) » {271=>"Canon"}
    image.get_exif_by_number(37377) » {37377=>"189/32"}
    image.get_exif_by_number() »
        {271=>"Canon", 37377=>"189/32" ...}

#### See also

get_exif_by_entry

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

#### See also

store_pixels, view

#### Magick API

AcquireImagePixels

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

#### See also

monochrome?

#### Magick API

IsGrayImage

### grayscale_pseudo_class

image.grayscale_pseudo_class(optimize=`true`) -> anImage

#### Description

Converts an image to a PseudoClass grayscale representation with an optionally compressed and sorted colormap.. This method is only available in GraphicsMagick 1.1 and later.

#### Arguments

optimize
  If true, compress and sort the colormap by increasing intensity.

#### Returns

A new image

#### Magick API

GrayscalePseudoClass

### grey?

image.qrey? -> `true` or `false`

#### Description

Synonym for gray?

### implode

image.implode(amount=0.50) -> anImage

#### Description

A funhouse mirror effect. See the example 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

This example is an animated image. Mouse over the image to start the animation.

#### Magick API

ImplodeImage

### import_pixels

image.import_pixels(x, y, columns, rows, map, pixels, type=Magick::CharPixel) -> image

#### Description

Replaces the pixels in the specified rectangle with pixel data from the supplied array or string. When the pixels argument is an array of pixel data, this method is the reverse of `export_pixels`. When the pixels argument is a string, `import_pixels` is ideal for loading very large amounts of binary pixel data.

#### 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 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. Pixel data can be supplied as an array or as a string.
  If pixels responds to `:to_str`
    `import_pixels` assumes that pixels can be converted to a string by `to_str` and that the result is a C array of the type specified by type containing binary pixel data in the order specified by map. The elements in the buffer must be in the range specified by type.
  Otherwise
    `import_pixels` assumes that pixels is an array or an object that can be converted to an array by the `Kernel::Array` method. The elements in the array must be `Numeric` values in the range [0..MaxRGB]. In either case, the pixel data must be stored in scanline order: left-to-right and top-to-bottom.
type
  Specifies the type and range of the pixel data when pixels is a string. One of the following constants:
  CharPixel
    type `unsigned char`, range 0-255
  ShortPixel
    type `unsigned short`, range 0-65535
  LongPixel, IntegerPixel
    type `unsigned long`, range 0-4294967295
  QuantumPixel
    the Quantum type used by ×Magick (depends on how ×Magick is configured) range 0-MaxRGB
  The default is `Magick::CharPixel`. This argument is ignored when pixels is an array.

#### Returns

The image as transformed by the pixel data.

#### Example

    # Replace the r'th scanline of the image using
    # pixel data stored in red-green-blue order.
    img.import_pixels(0, r, img.columns, 1, "RGB", scanline);

#### Example

This example is contrived since there's no need to convert the `pixels` array into a string by calling `pack`, but it does demonstrate the use of a string pixels argument. Note that this example assumes that ×Magick is configured with QuantumDepth=8.

    hat = Magick::Image.read("Flower_Hat.jpg").first
    pixels = hat.export_pixels(0, 0, hat.columns, hat.rows, "RGB")
    char_buffer = pixels.pack("C*")
    img = Magick::Image.new(hat.columns, hat.rows)
    img.import_pixels(0, 0, hat.columns, hat.rows, "RGB", char_buffer, Magick::CharPixel)

#### See also

constitute, export_pixels, store_pixels

#### Magick API

ImportImagePixels

#### Note

This method replaces the `constitute` method.

### inspect

image.inspect -> aString

#### Description

Constructs a description of the image as a string. The string contains some or all of the following fields:

original_filename=>
  if different from the current filename.
filename
  the current filename
[scene]
  the scene number, if the image is part of an image sequence
format
  the image format (GIF or JPEG, for example)
original width x height
  if different from the current width x height
page width x height + x-offset + y-offset
  if any of these fields is non-zero
storage class
  DirectClass or PseudoClass
number of colors
  total number of colors used in the image
mean error per pixel/normalized mean error/normalized maximum error
  for PseudoClass images, if present
N-bit
  bit depth
blob size
  if present

#### Example

    f.inspect » "images/Flower_Hat.jpg JPEG 200x250 DirectClass 8-bit 9kb"

### level

image.level(black_point=`0.0`, mid_point=`1.0`, white_point=`MaxRGB`) -> anImage

#### Description

Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range. The parameters provided represent the black, mid, and white points. The black point specifies the darkest color in the image. Colors darker than the black point are set to zero. Mid point specifies a gamma correction to apply to the image. White point specifies the lightest color in the image. Colors brighter than the white point are set to the maximum quantum value.

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

`level(0,1.50)`

#### See also

level_channel

#### Magick API

LevelImage

### level_channel

image.level_channel(channel, black_point=`0.0`, mid_point=`1.0`, white_point=`MaxRGB`) -> anImage

#### Description

Same as `level` but operates only on the specified channel.

#### Arguments

channel
  A ChannelType value.
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

#### See also

level

#### Magick API

LevelImageChannel

### magnify

image.magnify -> anImage

#### Description

A convenience method that scales the receiver to twice its size.

#### Returns

A new image

#### See also

magnify!, minify, resize, scale, sample, thumbnail

#### Magick API

MagnifyImage

### magnify!

image.magnify! -> image

#### Description

In-place form of magnify

#### Returns

self

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

This image has been mapped to the Netscape 216-color cube.

#### See also

ImageList#map

#### Magick API

MapImage

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

In this example the border color is black. The fill starts in the center and makes all the pixels transparent until it reaches a black pixel. The resulting image has been composited over a plasma background, which shows through the transparent pixels.

#### See also

matte_floodfill, Draw#matte

#### Magick API

MatteFloodfillImage

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

In this example the fill starts at the center pixel and replaces all the yellow pixels - the color of the center pixel. The resulting image has been composited over a plasma background, which shows through the transparent pixels.

#### See also

matte_replace, Draw#matte

#### Magick API

MatteFloodfilImage

### matte_point

image.matte_point(x, y) -> anImage

#### Description

Makes the pixel at x, y transparent. This method makes a copy of the image, just to make one pixel transparent. I recommend using the `Draw#matte` method instead.

#### Arguments

The x- and y-coordinates of the target pixel.

#### Returns

A new image

#### See also

Draw#matte

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

In this example the target pixel is a black pixel in the center of the uppermost circle. The `matte_replace` method makes all the black pixels in the image transparent. The resulting image has been composited over a plasma background, which shows through the transparent pixels.

#### See also

transparent, Draw#matte

#### Magick API

TransparentImage

### matte_reset!

image.matte_reset! -> image

#### Description

Makes all the pixels in the image transparent.

#### Returns

self

#### See also

opacity=

#### Magick API

SetImageOpacity

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

#### See also

enhance, reduce_noise, unsharp_mask

#### Magick API

MedianFilterImage

### minify

image.minify -> anImage

#### Description

A convenience method that scales the receiver to half its size.

#### Returns

A new image

#### See also

minify! magnify, resize, sample, scale, thumbnail

#### Magick API

MinifyImage

### minify!

image.minify! -> image

#### Description

In-place form of minify.

#### Returns

self

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

`modulate(0.85)`

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

#### See also

gray?

#### Magick API

IsMonochromeImage

### 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 non-0.
angle
  The angle (in degrees) of the blurring motion.

#### Returns

A new image

#### Example

#### See also

blur_image, gaussian_blur

#### Magick API

MotionBlurImage

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

#### See also

negate_channel

#### Magick API

NegateImage

### negate_channel

image.negate_channel(grayscale=`false`, [channel...]) = anImage

#### Description

Negate a particular image channel or channels.

#### Arguments

grayscale
  if `true`, only negate grayscale pixels within the image
channel...
  0 or more ChannelType arguments. If no channels are specified, all the channels are negated. Specifying no channel arguments has the same effect as the `negate` method, above.

#### Returns

A new image

#### Example

`negate_channel(false, GreenChannel)`

#### See also

negate

.

#### Magick API

NegateImageChannel

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

#### Magick API

NormalizeImage

#### See also

normalize_channel

### normalize_channel

image.normalize_channel([channel...]) = anImage

#### Description

Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available. Only the specified channels are normalized.

#### Arguments

channel...
  0 or more ChannelType arguments. If no channels are specified, all the channels are normalized. Specifying no channel arguments has the same effect as the `normalize` method, above.

#### Returns

A new image

#### Magick API

NormalizeImageChannel (available in ImageMagick 6.1.0)

#### See also

normalize

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

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

This example replaces white pixels with red pixels. Set the `fuzz` attribute to specify how closely the target pixels must match.

#### See also

color_floodfill

#### Magick API

OpaqueImage

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

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

#### See also

posterize, quantize

#### Magick API

OrderedDitherImage

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

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

If `new_color` is specified, `pixel_color` changes the image type to `DirectClass` if necessary.

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

#### Magick API

AcquireImagePixels

### posterize

image.posterize(levels=4, dither=`false`) -> anImage

#### Description

Reduces the image to a limited number of colors for a "poster" effect.

#### Arguments

levels
  Number of color levels allowed in each channel. Very low values (2, 3, or 4) have the most visible effect. The default is 4.
dither
  If `true`, dither the image. The default is `false`.

#### Returns

A new image

#### Example

#### See also

ordered_dither, quantize

#### Magick API

PosterizeImage