image.enhance -> anImage
Applies a digital filter that improves the quality of a noisy image.
A new image
The left-hand side has had noise added by add_noise. The right-hand side is the
result after using enhance.
median_filter, reduce_noise, unsharp_mask
EnhanceImage
image.equalize -> anImage
Applies a histogram equalization to the image.
A new image
EqualizeImage
image.erase! -> image
image.export_pixels(x=0, y=0, columns=image.columns, rows=image.rows, map="RGB") -> anArray
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.
# Export the r'th scanline from an image in red-green-blue order scanline = img.export_pixels(0, r, img.columns, 1, "RGB");
dispatch, export_pixels_to_str, import_pixels, get_pixels
ExportImagePixels
This method replaces the dispatch method.
image.export_pixels_to_str(x=0, y=0, columns=image.columns,
rows=image.rows, map="RGB",
type=Magick::CharPixel)
-> aString
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.
CharPixel,
which means that the pixel values will be stored as C
unsigned chars.dispatch, export_pixels, import_pixels, get_pixels
ExportImagePixels
image.find_similar_region(target, x=0, y=0) -> [rx, ry]
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.
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.
IsImageSimilar (available in ImageMagick 6.2.8)
image.flip -> anImage
Create a vertical mirror image of the receiver.
A new image
affine_transform, flip!, flop, rotate, transpose, transverse
FlipImage
image.flip! -> image
image.flop -> anImage
Create a horizontal mirror image of the receiver.
A new image
affine_transform, flip, flop!, rotate, transpose, transverse
FlopImage
image.flop! -> image
image.frame(width=25, height=25,
x=25, y=25,
inner_bevel=6, outer_bevel=6, color=matte_color) ->
anImage
Adds a simulated 3D border.
A new image
FrameImage
image.freeze -> self
Prevent further modifications to the image.
self
image.gamma_channel(gamma, [channel...]) = anImage
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.
A new image
The older gamma_correct method
is implemented in terms of gamma_channel.
GammaImageChannel
image.gamma_correct(red_gamma[,green_gamma[, blue_gamma]]) -> anImage
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.
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.
A new image
GammaImage
image.gaussian_blur(radius=0.0, sigma=1.0) -> anImage
Blurs an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).
Float value representing the radius of the Gaussian, in pixels, not counting
the center pixel.Float value representing the standard
deviation of the Gaussian operator, in pixels. This argument
must be > 0.0.A new image
gaussian_blur(0.0, 3.0)
blur_image, motion_blur, radial_blur
GaussianBlurImage
image.gaussian_blur_channel(radius=0.0, sigma=1.0[, channel...]) -> anImage
Blurs the selected channel or channels using a Gaussian operator of the specified radius and standard deviation.
Float value representing the radius of the Gaussian, in pixels, not counting
the center pixel.Float value representing the standard
deviation of the Gaussian operator, in pixels. This argument
must be > 0.0.A new image
image.get_exif_by_entry([name]*) -> anArray
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.
Zero or more EXIF entry names.
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.
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"] ...]
image.get_exif_by_number([tag]*) -> aHash
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.
Zero or more EXIF tag numbers.
A hash. If there is no tag with the specified number the
value is set to nil.
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" ...}
image.get_iptc_dataset(ds) -> aString
Retrieves the data field for the specified DataSet, or
nil if the DataSet is not used or the data field
has length 0.
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 |
img.get_iptc_dataset(Magick::IPTC::Application::Keywords)
The data field or nil
image.get_pixels(x, y, columns, rows) -> anArray
Gets the pixels from the specified rectangle within the image.
An array of pixels. There
will be columns*rows elements in the array.
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.
AcquireImagePixels
image.gray? -> true
or false
Returns true if all the pixels in the image
have the same red, green, and blue intensities.
true or false
IsGrayImage
image.grayscale_pseudo_class(optimize=true) ->
anImage
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.
A new image
GrayscalePseudoClass
image.qrey? -> true
or false
Synonym for gray?
image.implode(amount=0.50) -> anImage
A funhouse mirror effect. See the example below.
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.
A new image
This example is an animated image. Mouse over the image to start the animation.
ImplodeImage
image.import_pixels(x, y, columns, rows, map, pixels, type=Magick::CharPixel) -> image
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.
:to_strimport_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.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.The image as transformed by the pixel data.
# 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);
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)
constitute, export_pixels, store_pixels
ImportImagePixels
This method replaces the constitute method.
image.inspect -> aString
Constructs a description of the image as a string. The string contains some or all of the following fields:
f.inspect » "images/Flower_Hat.jpg JPEG 200x250 DirectClass 8-bit 9kb"
image.level(black_point=0.0, white_point=MaxRGB, gamma=1.0) -> anImage
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
A new image
level(0,1.50)
Prior to version 1.11.0 RMagick defined the signature for
level incorrectly:
img.level(white_point, gamma, black_point) -> anImage # 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.
LevelImage
image.level_channel(channel, black_point=0, white_point=MaxRGB - black_point, gamma=1.0) -> anImage
A new image
LevelImageChannel
image.linear_stretch(black_point[, white_point]) -> anImage
Linear with saturation stretch.
all pixels - black_point
pixels.A new image
LinearStretchImage
image.magnify -> anImage
A convenience method that scales the receiver to twice its size.
A new image
magnify!, minify, resize, scale
MagnifyImage
image.magnify! -> image
image.map(img, dither=false) -> anImage
Replaces the colors of an image with the closest color from a reference image.
A new image
This image has been mapped to the Netscape 216-color cube.
MapImage
image.matte_fill_to_border(x, y) -> anImage
Makes transparent all the pixels that are neighbors of the pixel at x,y and are not the border color.
The x- and y- coordinates of the target pixel.
A new image
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.
MatteFloodfillImage
image.matte_floodfill(x, y) -> anImage
Makes transparent all the pixels that are the same color as the pixel at x, y, and are neighbors.
The x- and y-coordinates of the target pixel.
A new image
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.
MatteFloodfilImage
image.matte_point(x, y) -> anImage
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.
The x- and y-coordinates of the target pixel.
A new image
image.matte_replace(x, y) -> anImage
Makes transparent all the pixels that are the same color as the pixel at x, y.
A new image
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.
TransparentImage
image.matte_reset! -> image
Makes all the pixels in the image transparent.
self
image.median_filter(radius=1.0) -> anImage
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.
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.
A new image
The left side of the image has been modified by add_noise. The right side has been filtered by median_filter(0.05).
enhance, reduce_noise, unsharp_mask
MedianFilterImage
image.minify -> anImage
A convenience method that scales the receiver to half its size.
A new image
minify! magnify, resize, sample, scale, thumbnail
MinifyImage
image.minify! -> image
image.modulate(brightness=1.0, saturation=1.0, hue=1.0) -> anImage
Changes the brightness, saturation, and hue.
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%.
A new image
modulate(0.85)
ModulateImage
image.monochrome? -> true or false
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.
IsMonochromeImage
image.motion_blur(radius=0.0, sigma=1.0, angle=0.0) -> anImage
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.
A new image
MotionBlurImage
image.negate(grayscale=false) -> anImage
Negates the colors in the receiver.
A new image
NegateImage
image.negate_channel(grayscale=false, [channel...]) = anImage
Negate a particular image channel or channels.
A new image
negate_channel(false, GreenChannel)
NegateImageChannel
image.normalize -> anImage
Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available.
A new image
NormalizeImage
image.normalize_channel([channel...]) = anImage
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.
A new image
NormalizeImageChannel (available in ImageMagick 6.1.0)
image.oil_paint(radius=3.0) -> anImage
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.
A new image
OilPaintImage
image.opaque(target, fill) -> anImage
Changes all pixels having the target color to the fill color.
A new image
img.fuzz = 25
img = img.opaque('white', 'red')
OpaqueImage
image.opaque? -> true or false
Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.
true or false
IsOpaqueImage
image.ordered_dither(threshold_map='2x2') -> anImage
Dithers the image to a predefined pattern. The threshold_map argument defines the pattern to use.
The threshold_map argument can be any of the strings listed by this command:
convert -list Thresholds
GraphicsMagick and older releases of ImageMagick do not accept threshold map strings and will not respond to that command. In these cases threshold_map should be one of the numbers 2, 3, or 4. These numbers correspond to the threshold maps "o2x2", "o3x3", and "o4x4", respectively.
A new image
OrderedPosterizeImage
image.palette? -> true or false
Returns true if the image is PseudoClass and has 256 unique colors or less.
true or false
IsPaletteImage
image.pixel_color(x, y[, new_color]) -> aPixel
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.
old = image.pixel_color(20,40,"white")
AcquireImagePixels
image.polaroid(angle=-5.0) [ { optional arguments } ] -> anImage
Produce an image that looks like a Polaroid® instant picture. If the image has a "Caption" property, the value is used as a caption.
Optional arguments may be specified in a block associated
with the method. These arguments control the shadow color and
how the label is rendered. By default the shadow color is
gray75. To specify a different shadow color, use
self.shadow_color. The argument can be either a
color name or a Pixel.
The following annotate attributes control the label rendering: align, decorate, density, encoding, fill, font, font_family, font_stretch, font_style, font_weight, gravity, pointsize, stroke, stroke_width, text_antialias, undercolor.
img.polaroid do self.shadow_color = "gray40" self.pointsize = 12 end
Polaroid is a registered trademark of the Polaroid Corporation.
PolaroidImage (introduced in ImageMagick 6.3.1)
image.posterize(levels=4, dither=false) -> anImage
Reduces the image to a limited number of colors for a "poster" effect.
A new image
PosterizeImage