class Image < Object (instance methods e-o)
mixes in Comparable

Table of Contents

instance methods

instance methods

each_iptc_dataset

img.each_iptc_dataset { |dataset, data_field| block} -> nil

Description

Iterates over the IPTC DataSet constants in Magick::IPTC. If the image's IPTC profile has the DataSet and the data field has non-0 length, yields to the block. The IPTC DataSet constants are listed here.

Arguments

The block arguments are:

dataset
The DataSet name
data_field
The data field

See also

get_iptc_dataset

each_pixel

img.each_pixel {|pixel, c, r| block } -> self

Description

Calls block with 3 arguments, a pixel from img, its column number c, and its row number r, for all the pixels in the image. The pixels are enumerated from top-to-bottom and left-to-right.

Returns

self

See also

get_pixels

each_profile

img.each_profile {|name, value| block} -> ??? (see Returns)

Description

Calls block once for each profile in the image, passing the profile name and value as parameters.

Returns

the last value returned by the block

See also

The color_profile and iptc_profile attributes return the ICC and IPTC profiles, respectively.

Magick API

GetNextImageProfile

edge

img.edge(radius=0.0) -> image

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

edge example

Magick API

EdgeImage

emboss

img.emboss(radius=0.0, sigma=1.0) -> image

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 cannot be 0.0.

Returns

A new image

Example

emboss example

Magick API

EmbossImage

encipher

img.encipher(passphrase) -> image

Description

Encipher an image.

Arguments

The passphrase.

Returns

A new image

Example

enciphered_img = img.encipher("magic word")

Magick API

EncipherImage

See also

decipher

enhance

img.enhance -> image

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.

enhance example

See also

median_filter, reduce_noise, unsharp_mask

Magick API

EnhanceImage

equalize

img.equalize -> image

Description

Applies a histogram equalization to the image.

Returns

A new image

Example

equalize example

Magick API

EqualizeImage

See also

equalize_channel

equalize_chanel

img.equalize_channel([channel...]) -> image

Description

Applies a histogram equalization to the image. Only the specified channels are equalized.

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 equalize method, above.

Returns

A new image

Magick API

EqualizeImageChannel

See also

equalize

erase!

img.erase! -> self

Description

Sets the entire image to the background_color.

Returns

self

See also

color_reset!

Magick API

SetImage

excerpt

img.excerpt(x, y, width, height) -> image

Description

This method is very similar to crop. It extracts the rectangle specified by its arguments from the image and returns it as a new image. However, excerpt does not respect the virtual page offset and does not update the page offset and is more efficient than cropping.

It is the caller's responsibility to ensure that the rectangle lies entirely within the original image.

Arguments

x, y
The position of the upper-left corner of the excerpted rectangle.
width, height
The width and height of the excerpted rectangle. The resulting image will always be widthxheight in size.

Returns

A new image

See Also

crop, excerpt!

Magick API

ExcerptImage

excerpt!

img.excerpt!(x, y, width, height) -> img

Description

In-place form of excerpt.

export_pixels

img.export_pixels(x=0, y=0, columns=img.columns, rows=img.rows, map="RGB") -> array

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 that describes which pixel channel data is desired and the order in which it should be stored. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), or P = pad.

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, export_pixels_to_str, import_pixels, get_pixels

Magick API

ExportImagePixels

Note

This method replaces the dispatch method.

export_pixels_to_str

img.export_pixels_to_str(x=0, y=0, columns=img.columns, rows=img.rows, map="RGB", type=CharPixel) -> string

Description

Extracts the pixel data from the specified rectangle and returns it as a string. If you need to get the pixel data in a memory buffer (as input to another application, for example), this method is much, much faster than export_pixels or get_pixels.

The string returned by export_pixels_to_str is suitable for use as an argument to import_pixels.

Note: You can also use to_blob to convert an image into a string.

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 that describes which pixel channel data is desired and the order in which it should be stored. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), or P = pad.
type
A StorageType value that specifies the C datatype to which the pixel data will be converted. The default is CharPixel, which means that the pixel values will be stored as C unsigned chars.

Returns

a string

See also

dispatch, export_pixels, import_pixels, get_pixels

Magick API

ExportImagePixels

extent

img.extent(width, height, x=0, y=0) -> image

Description

If width or height is greater than the target image's width or height, extends the width and height of the target image to the specified values. The new pixels are set to the background color. If width or height is less than the target image's width or height, crops the target image.

Arguments

width
The width of the new image
height
The height of the new image
x, y
The upper-left corner of the new image is positioned at -x, -y.

Returns

A new image

Notes

The new image is composed over the background using the composite operator specified by target image's compose attribute.

Magick API

ExtentImage

find_similar_region

img.find_similar_region(target, x=0, y=0) -> [rx, ry]

Description

This interesting method searches for a rectangle in the image that is similar to the target. For the rectangle to be similar each pixel in the rectangle must match the corresponding pixel in the target image within the range specified by the fuzz attributes of the image and the target image.

Arguments

target
An image that forms the target of the search. This image can be any size.
x, y
The starting x- and y-offsets for the search. If omitted both x and y default to 0.

Returns

If the search succeeds, the return value is an array with 2 elements. These elements are the x- and y-offsets of the matching rectangle. If the search fails the return value is nil.

Magick API

IsImageSimilar

flip

img.flip -> image

Description

Create a vertical mirror image of the receiver.

Returns

A new image

Example

flip example

See also

affine_transform, flip!, flop, rotate, transpose, transverse

Magick API

FlipImage

flip!

img.flip! -> self

Description

In-place form of flip.

Returns

self

flop

img.flop -> image

Description

Create a horizontal mirror image of the receiver.

Returns

A new image

Example

flop example

See also

affine_transform, flip, flop!, rotate, transpose, transverse

Magick API

FlopImage

flop!

img.flop! -> self

Description

In-place form of flop.

Returns

self

frame

img.frame(width=25, height=25, x=25, y=25, inner_bevel=6, outer_bevel=6, color=matte_color) -> image

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

frame example

See also

border

Magick API

FrameImage

freeze

img.freeze -> self

Description

Prevent further modifications to the image.

Returns

self

function_channel

img.function_channel(function [, parameters...][, channel...]) -< image

Description

Apply a function to channel values. This method is equivalent to the convert -function option. See the ImageMagick documentation for more information.

Arguments

function
One of the following values.
  • PolynomialFunction
  • SinusoidFunction
  • ArcsinFunction
  • ArctanFunction
Some of these values are not available in earlier versions of ImageMagick. To find out which values are available, enter the following statement in irb:
Magick::MagickFunction.values {|value| p value}
parameters
One or more floating-point numbers. The number of parameters depends on the function. See the ImageMagick documentation for details.
channel...
0 or more ChannelType arguments. If no channels are specified, the red, green, and blue channels are used.

Returns

A new image

Example

img2 = img.function_channel(Magick::PolynomialFunction, -25, 53, -36, 8.3, 0.2)

See also

quantum_operator

gamma_channel

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

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

img.gamma_correct(red_gamma[,green_gamma[, blue_gamma]]) -> image

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

img.gaussian_blur(radius=0.0, sigma=1.0) -> image

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

img.gaussian_blur(0.0, 3.0)

gaussian_blur example

See also

blur_image, motion_blur, radial_blur, selective_blur_channel

Magick API

GaussianBlurImage

gaussian_blur_channel

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

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, motion_blur, radial_blur, selective_blur_channel

Magick API

GaussianBlurImageChannel

get_exif_by_entry

img.get_exif_by_entry([name]*) -> array

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

img.get_exif_by_number([tag]*) -> hash

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_iptc_dataset

img.get_iptc_dataset(ds) -> string

Description

Retrieves the data field for the specified DataSet, or nil if the DataSet is not used or the data field has length 0.

Arguments

RMagick defines the following constants for use as arguments to this method. All the constants are in the Magick::IPTC namespace. Notice that some DataSets have two names.

Constant Record:DataSet
Envelope::Model_Version 1:00
Envelope::Destination 1:05
Envelope::UNO 1:100
Envelope::Unique_Name_of_Object 1:100
Envelope::ARM_Identifier 1:120
Envelope::ARM_Version 1:122
Envelope::File_Format 1:20
Envelope::File_Format_Version 1:22
Envelope::Service_Identifier 1:30
Envelope::Envelope_Number 1:40
Envelope::Product_ID 1:50
Envelope::Envelope_Priority 1:60
Envelope::Date_Sent 1:70
Envelope::Time_Sent 1:80
Envelope::Coded_Character_Set 1:90
Application::Object_Type_Reference 2:03
Application::Object_Name 2:05
Application::Title 2:05
Application::Edit_Status 2:07
Application::Editorial_Update 2:08
Application::Urgency 2:10
Application::Country_Primary_Location_Code 2:100
Application::Country_Primary_Location_Name 2:101
Application::Original_Transmission_Reference 2:103
Application::Headline 2:105
Application::Credit 2:110
Application::Source 2:115
Application::Copyright_Notice 2:116
Application::Contact 2:118
Application::Subject_Reference 2:12
Application::Abstract 2:120
Application::Caption 2:120
Application::Caption_Writer 2:122
Application::Editor 2:122
Application::Rasterized_Caption 2:125
Application::Image_Type 2:130
Application::Image_Orientation 2:131
Application::Language_Identifier 2:135
Application::Category 2:15
Application::Audio_Type 2:150
Application::Audio_Sampling_Rate 2:151
Application::Audio_Sampling_Resolution 2:152
Application::Audio_Duration 2:153
Application::Audio_Outcue 2:154
Application::Supplemental_Category 2:20
Application::ObjectData_Preview_File_Format 2:200
Application::ObjectData_Preview_File_Format_Version 2:201
Application::ObjectData_Preview_Data 2:202
Application::Fixture_Identifier 2:22
Application::Keywords 2:25
Application::Content_Location_Code 2:26
Application::Content_Location_Name 2:27
Application::Release_Date 2:30
Application::Release_Time 2:35
Application::Expiration_Time 2:35
Application::Expiration_Date 2:37
Application::Special_Instructions 2:40
Application::Action_Advised 2:42
Application::Reference_Service 2:45
Application::Reference_Date 2:47
Application::Reference_Number 2:50
Application::Date_Created 2:55
Application::Time_Created 2:60
Application::Digital_Creation_Date 2:62
Application::Digital_Creation_Time 2:63
Application::Originating_Program 2:65
Application::Program_Version 2:70
Application::Object_Cycle 2:75
Application::Author 2:80
Application::By_Line 2:80
Application::Author_Position 2:85
Application::By_Line_Title 2:85
Application::City 2:90
Application::Sub_Location 2:92
Application::Province 2:95
Application::State 2:95
Pre_ObjectData_Descriptor::Size_Mode 7:10
Pre_ObjectData_Descriptor::Max_Subfile_Size 7:20
Pre_ObjectData_Descriptor::ObjectData_Size_Announced 7:90
Pre_ObjectData_Descriptor::Maximum_ObjectData_Size 7:95
ObjectData::Subfile 8:10
Post_ObjectData_Descriptor::Confirmed_ObjectData_Size 9:10

Example

img.get_iptc_dataset(Magick::IPTC::Application::Keywords)

Returns

The data field or nil

See also

each_iptc_dataset, iptc_profile

get_pixels

img.get_pixels(x, y, columns, rows) -> array

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.

get_pixels example

See also

store_pixels, view

Magick API

AcquireImagePixels

gray?

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

grey?

img.grey? -> true or false

Description

Synonym for gray?

histogram?

img.histogram? -> true or false

Description

Returns true if the image has 1024 unique colors or less.

Returns

true or false

Magick API

IsHistogramImage

implode

img.implode(amount=0.50) -> image

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.

implode example

Magick API

ImplodeImage

import_pixels

img.import_pixels(x, y, columns, rows, map, pixels, type=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..QuantumRange]. In either case, the pixel data must be stored in scanline order: left-to-right and top-to-bottom.
type
A StorageType value that specifies the type and range of the pixel data when pixels is a string.

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 ImageMagick 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, CharPixel)

See also

constitute, export_pixels, store_pixels

Magick API

ImportImagePixels

Note

This method replaces the constitute method.

inspect

img.inspect -> string

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

img.level(black_point=0.0, white_point=QuantumRange, gamma=1.0) -> image

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. Gamma 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
A black point level in the range 0-QuantumRange. The default is 0.0.
mid_point
A white point level in the range 0..QuantumRange. The default is QuantumRange - black_point.
gamma
A gamma correction in the range 0.0-10.0 The default is 1.0.

Returns

A new image

Example

img.level(0,1.50)

level example

Compatibility notes

Prior to version 1.11.0 RMagick defined the signature for level incorrectly:

img.level(white_point, gamma, black_point) -> image # wrong!

That is, the gamma and white_point arguments were swapped. In an effort to maintain compatibility with older scripts that expect that signature, level inspects its arguments and will interchange white_point and gamma if they "look" incorrect. That is, if gamma is > 10.0, or if white_point is < 10.0, or if gamma > white_point, then level will swap them.

If you want to avoid this behavior, use the level2 method instead. The level2 method is exactly the same as level except that it never swaps the arguments.

See also

level_channel

Magick API

LevelImage

level_channel

img.level_channel(channel, black_point=0, white_point=QuantumRange - black_point, gamma=1.0) -> image

Description

Same as level but operates only on the specified channel.

Arguments

channel
A ChannelType value.
black_point
A black point level in the range 0-QuantumRange. The default is 0.0.
white_point
A white point level in the range 0..QuantumRange. The default is QuantumRange - black_point.
gamma
A gamma correction in the range 0.0-10.0 The default is 1.0.

Returns

A new image

See also

level, levelize_channel

Magick API

LevelImageChannel

level_colors

img.level_colors(black_color="black", white_color="white", invert=true) -> image

Description

When invert is true, black and white will be mapped to the black_color and white_color colors, compressing all other colors linearly. When invert is false, black and white will be mapped to the black_color and white_color colors, stretching all other colors linearly. The default is true.

Arguments

black_color
The color to be mapped to black. The default is "black".
white_color
The color to be mapped to white. The default is "white".
invert
See the description above.

Returns

A new image

Example

level_colors example

See also

This method corresponds to the +level-colors option. See Examples of ImageMagick Usage for more information.

Magick API

LevelImageColors

levelize_channel

img.levelize_channel(black_point, white_point, gamma=1.0 [, channel...]) -> image

Description

Maps black and white to the specified points. The reverse of level_channel.

Arguments

black_point
A black point level in the range 0..QuantumRange. This argument is required.
white_point
A white point level in the range 0..QuantumRange. The default is QuantumRange - black_point.
gamma
A gamma correction in the range 0.0-10.0 The default is 1.0.
channel...
0 or more ChannelType arguments. If no channels are specified, the default channels are the red, green, and blue channels.

Returns

A new image

See also

level, level_channel

This method corresponds to the +level option. See Examples of ImageMagick Usage for more information.

Magick API

LevelizeImageChannel

linear_stretch

img.linear_stretch(black_point[, white_point]) -> image

Description

Linear with saturation stretch.

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.

Returns

A new image

Magick API

LinearStretchImage

liquid_rescale

img.liquid_rescale(new_width, new_height, delta_x=0.0, rigidity=0.0) -> image

Description

Rescale image with seam carving. To use this method, you must have installed and configured ImageMagick to use the Liquid Rescale Library.

Arguments

new_width, new_height

The desired width and height. Should not exceed 200% of the original dimension.

delta_x

Maximum seam transversal step (0 means straight seams).

rigidity

Introduce a bias for non-straight seams (typically 0).

Returns

A new image

Magick API

LiquidRescaleImage

magnify

img.magnify -> image

Description

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

Returns

A new image

See also

magnify!, minify, resize, scale

Magick API

MagnifyImage

magnify!

img.magnify! -> self

Description

In-place form of magnify

Returns

self

mask

img.mask([image or nil]) -> mask_image

Description

Sets an image clip mask created from the specified mask image. The mask image must have the same dimensions as the image being masked. If not, the mask image is resized to match. If the mask image has an alpha channel the opacity of each pixel is used to define the mask. Otherwise, the intensity (gray level) of each pixel is used.

In general, if the mask image does not have an alpha channel, a white pixel in the mask prevents changes to the corresponding pixel in the image being masked, while a black pixel allows changes. A pixel that is neither black nor white will allow partial changes depending on its intensity.

Use alpha to specify whether or not the mask image has an alpha channel.

Arguments

If the value is an imagelist, uses the current image as the mask image. To remove the mask, pass nil instead of an image.

To get a copy of the current mask, omit the argument entirely.

Example

mask example

Returns

A copy of the current mask, or nil if no mask is defined.

Notes

This method makes a copy of the image to use as the mask. This means that if you want to change the mask you must call this method to establish the changed image as the mask.

matte_fill_to_border

img.matte_fill_to_border(x, y) -> image

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.

matte_fill_to_border example

See also

matte_floodfill, Draw#matte

Magick API

MatteFloodfillImage

matte_floodfill

img.matte_floodfill(x, y) -> image

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.

matte_floodfill example

See also

matte_replace, Draw#matte

Magick API

MatteFloodfilImage

matte_point

img.matte_point(x, y) -> image

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

img.matte_replace(x, y) -> image

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.

matte_replace example

See also

transparent, Draw#matte

Magick API

TransparentImage

matte_reset!

img.matte_reset! -> self

Description

Makes all the pixels in the image transparent.

Returns

self

See also

alpha

Magick API

SetImageOpacity

median_filter

img.median_filter(radius=1.0) -> image

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

median_filter example

See also

enhance, reduce_noise, unsharp_mask

Magick API

MedianFilterImage

minify

img.minify -> image

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!

img.minify! -> self

Description

In-place form of minify.

Returns

self

modulate

img.modulate(brightness=1.0, saturation=1.0, hue=1.0) -> image

Description

Changes the brightness, saturation, and hue.

Arguments

The percent change in the brightness, saturation, and hue. Must be a number or a string in the form "NN%". 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

img.modulate(0.85)

modulate example

Magick API

ModulateImage

monochrome?

img.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 QuantumRange. That is, the image is black-and-white.

See also

gray?

Magick API

IsMonochromeImage

motion_blur

img.motion_blur(radius=0.0, sigma=1.0, angle=0.0) -> image

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

motion_blur example

See also

blur_image, gaussian_blur, radial_blur, selective_blur_channel

Magick API

MotionBlurImage

negate

img.negate(grayscale=false) -> image

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

negate example

See also

negate_channel

Magick API

NegateImage

negate_channel

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

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

img.negate_channel(false, Magick::GreenChannel)

negate_channel example

See also

negate

.

Magick API

NegateImageChannel

normalize

img.normalize -> image

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

normalize example

Magick API

NormalizeImage

See also

normalize_channel

normalize_channel

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

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

See also

normalize

oil_paint

img.oil_paint(radius=3.0) -> image

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

oil_paint example

Magick API

OilPaintImage

opaque

img.opaque(target, fill) -> image

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

img.fuzz = 25
img = img.opaque('white', 'red')

See also

color_floodfill, opaque_channel

Magick API

OpaquePaintImageChannel

opaque_channel

img.opaque_channel(target, fill, invert=false, fuzz=img.fuzz [, channel...]) -> image

Description

Changes all pixels having the target color to the fill color. If invert is true, changes all the pixels that are not 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
invert
If true, the target pixels are all the pixels that are not the target color. The default is the value of the target image's fuzz attribute
fuzz
Colors within this distance are considered equal to the target color.
channel...
0 or more ChannelType arguments. If no channels are specified, the default is DefaultChannels.

Returns

A new image

See also

opaque

Magick API

OpaquePaintImageChannel

opaque?

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

img.ordered_dither(threshold_map='2x2') -> image

Description

Dithers the image to a predefined pattern. The threshold_map argument defines the pattern to use.

Arguments

The threshold_map argument can be any of the strings listed by this command:

convert -list Thresholds

If you have a sufficiently new version of ImageMagick, you can add a a uniform color map with the number of levels per color channel immediately following the threshold_map, separated by a comma. See the documentation for ImageMagick's -ordered-dither option for more information.

Returns

A new image

Example

ordered_dither example

See also

posterize, quantize

Magick API

OrderedPosterizeImage