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
Magick API
EdgeImage
img.each_iptc_dataset { |dataset, data_field| block}
-> nil
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.
The block arguments are:
img.each_pixel {|pixel, c, r| block } -> self
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.
self
img.each_profile {|name, value| block} -> ??? (see Returns)
the last value returned by the block
The color_profile and iptc_profile attributes return the ICC and IPTC profiles, respectively.
GetNextImageProfile
img.edge(radius=0.0) -> image
edge selects a suitable default.
A new image
EdgeImage
img.emboss(radius=0.0, sigma=1.0) -> image
A new image
EmbossImage
img.encipher(passphrase) -> image
Encipher an image.
The passphrase.
A new image
enciphered_img = img.encipher("magic word")
EncipherImage
img.enhance -> image
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
img.equalize -> image
Applies a histogram equalization to the image.
A new image
EqualizeImage
img.equalize_channel([channel...]) -> image
Applies a histogram equalization to the image. Only the specified channels are equalized.
A new image
EqualizeImageChannel
img.erase! -> self
Sets the entire image to the background_color.
SetImage
img.excerpt(x, y, width, height) -> image
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.
A new image
ExcerptImage
img.excerpt!(x, y, width, height) -> img
In-place form of excerpt.
img.export_pixels(x=0, y=0, columns=img.columns, rows=img.rows, map="RGB") -> array
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.
img.export_pixels_to_str(x=0, y=0, columns=img.columns, rows=img.rows, map="RGB",
type=CharPixel) ->
string
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.
a string
dispatch, export_pixels, import_pixels, get_pixels
ExportImagePixels
img.extent(width, height, x=0, y=0) -> image
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.
A new image
The new image is composed over the background using the composite operator specified by target image's compose attribute.
ExtentImage
img.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
img.flip -> image
Create a vertical mirror image of the receiver.
A new image
affine_transform, flip!, flop, rotate, transpose, transverse
FlipImage
img.flip! -> self
img.flop -> image
Create a horizontal mirror image of the receiver.
A new image
affine_transform, flip, flop!, rotate, transpose, transverse
FlopImage
img.flop! -> self
img.frame(width=25, height=25, x=25,
y=25, inner_bevel=6, outer_bevel=6, color=matte_color) -> image
Adds a simulated 3D border.
A new image
FrameImage
img.freeze -> self
Prevent further modifications to the image.
self
img.function_channel(function [, parameters...][, channel...]) -< image
Apply a function to channel values. This method is equivalent to the convert -function option. See the ImageMagick documentation for more information.
PolynomialFunctionSinusoidFunctionArcsinFunctionArctanFunctionMagick::MagickFunction.values {|value| p value}
A new image
img2 = img.function_channel(Magick::PolynomialFunction, -25, 53, -36, 8.3, 0.2)
img.gamma_channel(gamma, [channel...]) = image
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
img.gamma_correct(red_gamma[,green_gamma[, blue_gamma]]) -> image
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
img.gaussian_blur(radius=0.0, sigma=1.0) -> image
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
img.gaussian_blur(0.0, 3.0)
blur_image, motion_blur, radial_blur, selective_blur_channel
GaussianBlurImage
img.gaussian_blur_channel(radius=0.0, sigma=1.0[, channel...]) -> image
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
blur_channel, motion_blur, radial_blur, selective_blur_channel
GaussianBlurImageChannel
img.get_exif_by_entry([name]*) -> array
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 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.
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"] ...]
img.get_exif_by_number([tag]*) -> hash
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" ...}
img.get_iptc_dataset(ds) -> string
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
img.get_pixels(x, y, columns, rows) -> array
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
img.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
img.grey? -> true or
false
Synonym for gray?
img.histogram? -> true or
false
Returns true if the image has 1024 unique colors or less.
true or false
IsHistogramImage
img.implode(amount=0.50) -> image
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
img.import_pixels(x, y, columns, rows, map, pixels, type=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_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.
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.
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 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)
constitute, export_pixels, store_pixels
ImportImagePixels
This method replaces the constitute method.
img.inspect -> string
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"
img.level(black_point=0.0,
white_point=QuantumRange, gamma=1.0) -> image
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
img.level(0,1.50)
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.
LevelImage
img.level_channel(channel, black_point=0, white_point=QuantumRange - black_point, gamma=1.0) -> image
A new image
LevelImageChannel
img.level_colors(black_color="black", white_color="white",
invert=true) -> image
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.
A new image
This method corresponds to the +level-colors option. See Examples of ImageMagick Usage for more information.
LevelImageColors
img.levelize_channel(black_point, white_point, gamma=1.0 [, channel...]) -> image
Maps black and white to the specified points. The reverse of level_channel.
A new image
This method corresponds to the +level option. See Examples of ImageMagick Usage for more information.
LevelizeImageChannel
img.linear_stretch(black_point[, white_point]) -> image
Linear with saturation stretch.
all pixels - black_point pixels.
A new image
LinearStretchImage
img.liquid_rescale(new_width, new_height, delta_x=0.0, rigidity=0.0) -> image
Rescale image with seam carving. To use this method, you must have installed and configured ImageMagick to use the Liquid Rescale Library.
The desired width and height. Should not exceed 200% of the original dimension.
Maximum seam transversal step (0 means straight seams).
Introduce a bias for non-straight seams (typically 0).
A new image
LiquidRescaleImage
img.magnify -> image
A convenience method that scales the receiver to twice its size.
A new image
magnify!, minify, resize, scale
MagnifyImage
img.magnify! -> self
img.mask([image or nil]) -> mask_image
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.
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.
A copy of the current mask, or nil if no mask is defined.
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.
img.matte_fill_to_border(x, y) -> image
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
img.matte_floodfill(x, y) -> image
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
img.matte_point(x, y) -> image
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
img.matte_replace(x, y) -> image
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
img.matte_reset! -> self
Makes all the pixels in the image transparent.
self
img.median_filter(radius=1.0) -> image
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
img.minify -> image
A convenience method that scales the receiver to half its size.
A new image
minify! magnify, resize, sample, scale, thumbnail
MinifyImage
img.minify! -> self
img.modulate(brightness=1.0, saturation=1.0, hue=1.0) -> image
Changes the brightness, saturation, and hue.
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%.
A new image
img.modulate(0.85)
ModulateImage
img.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 QuantumRange. That is, the image is black-and-white.
IsMonochromeImage
img.motion_blur(radius=0.0, sigma=1.0, angle=0.0) -> image
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
blur_image, gaussian_blur, radial_blur, selective_blur_channel
MotionBlurImage
img.negate(grayscale=false) -> image
Negates the colors in the receiver.
A new image
NegateImage
img.negate_channel(grayscale=false, [channel...]) = image
Negate a particular image channel or channels.
A new image
img.negate_channel(false, Magick::GreenChannel)
NegateImageChannel
img.normalize -> image
Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available.
A new image
NormalizeImage
img.normalize_channel([channel...]) = image
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
img.oil_paint(radius=3.0) -> image
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
img.opaque(target, fill) -> image
Changes all pixels having the target color to the fill color.
A new image
img.fuzz = 25
img = img.opaque('white', 'red')
color_floodfill, opaque_channel
OpaquePaintImageChannel
img.opaque_channel(target, fill, invert=false, fuzz=img.fuzz [, channel...]) -> image
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.
fuzz attribute
A new image
OpaquePaintImageChannel
img.opaque? -> true or false
Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.
true or false
IsOpaqueImage
img.ordered_dither(threshold_map='2x2') -> image
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
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.
A new image
OrderedPosterizeImage