Class: Magick::Image

Inherits:

Object

• Object
• Magick::Image

Includes:

Comparable

Defined in:

lib/rmagick_internal.rb,
ext/RMagick/rmmain.cpp

Overview

Ruby-level Magick::Image methods

Defined Under Namespace

Classes: DrawOptions, Info, PolaroidOptions, View

Class Method Summary

• ._load(str) ⇒ Magic::Image

  Implement marshalling.

• .capture(*args) ⇒ Magick::Image

  Reads an image from an X window.

• .constitute(width_arg, height_arg, map_arg, pixels_arg) ⇒ Magick::Image

  Creates an Image from the supplied pixel data.

• .from_blob(blob_arg) ⇒ Array<Magick::Image>

  Convert direct to memory image formats from string data.

• .ping(file_arg) {|info| ... } ⇒ Array<Magick::Image>

  Returns all the properties of an image or image sequence except for the pixels.

• .read(file_arg) {|info| ... } ⇒ Array<Magick::Image>

  Call ReadImage.

• .read_inline(content) {|info| ... } ⇒ Array<Magick::Image>

  Read a Base64-encoded image.

Instance Method Summary

• #<=>(other) ⇒ -1, ...

  Compare two images.

• #[](key_arg) ⇒ String^?

  Returns the value of the image property identified by key.

• #[]=(key_arg, attr_arg) ⇒ Magick::Image

  Sets the value of an image property.

• #_dump(depth) ⇒ String

  Implement marshalling.

• #adaptive_blur(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Adaptively blurs the image by blurring more intensely near image edges and less intensely far from edges.

• #adaptive_blur_channel(*args) ⇒ Magick::Image

  The same as #adaptive_blur except only the specified channels are blurred.

• #adaptive_resize(*args) ⇒ Magick::Image

  Resizes the image with data dependent triangulation.

• #adaptive_sharpen(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Adaptively sharpens the image by sharpening more intensely near image edges and less intensely far from edges.

• #adaptive_sharpen_channel(*args) ⇒ Magick::Image

  The same as #adaptive_sharpen except only the specified channels are sharpened.

• #adaptive_threshold(width = 3, height = 3, bias = 0) ⇒ Magick::Image

  Selects an individual threshold for each pixel based on the range of intensity values in its local neighborhood.

• #add_compose_mask(mask) ⇒ Object

  Associates a mask with an image that will be used as the destination image in a #composite operation.

• #add_noise(noise) ⇒ Magick::Image

  Adds random noise to the image.

• #add_noise_channel(*args) ⇒ Magick::Image

  Adds random noise to the specified channel or channels in the image.

• #add_profile(name) ⇒ Magick::Image

  Adds an ICC (a.k.a. ICM), IPTC, or generic profile.

• #affine_transform(affine) ⇒ Magick::Image

  Transform an image as dictated by the affine matrix argument.

• #alpha(*args) ⇒ Object

  Get/Set alpha channel.

• #alpha? ⇒ Boolean

  Determine whether the image's alpha channel is activated.

• #annotate(draw, width, height, x, y, text) ⇒ Object

  Provide an alternate version of Draw#annotate, for folks who want to find it in this class.

• #auto_gamma_channel(*args) ⇒ Magick::Image

  "Automagically" adjust the gamma level of an image.

• #auto_level_channel(*args) ⇒ Magick::Image

  "Automagically" adjust the color levels of an image.

• #auto_orient ⇒ Magick::Image

  Rotates or flips the image based on the image's EXIF orientation tag.

• #auto_orient! ⇒ Magick::Image^?

  Rotates or flips the image based on the image's EXIF orientation tag.

• #background_color ⇒ String

  Return the name of the background color as a String.

• #background_color=(color) ⇒ Magick::Pixel, String

  Set the the background color to the specified color spec.

• #base_columns ⇒ Integer

  Return the number of rows (before transformations).

• #base_filename ⇒ String

  Return the image filename (before transformations).

• #base_rows ⇒ Integer

  Return the number of rows (before transformations).

• #bias ⇒ Float

  Get image bias (used when convolving an image).

• #bias=(pct) ⇒ Numeric, String

  Set image bias (used when convolving an image).

• #bilevel_channel(*args) ⇒ Magick::Image

  Changes the value of individual pixels based on the intensity of each pixel channel.

• #black_point_compensation ⇒ Boolean

  Return current black point compensation attribute.

• #black_point_compensation=(arg) ⇒ Boolean

  Set black point compensation attribute.

• #black_threshold(*args) ⇒ Numeric

  Forces all pixels below the threshold into black while leaving all pixels above the threshold unchanged.

• #blend(overlay, src_percent, dst_percent, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

  Adds the overlay image to the target image according to src_percent and dst_percent.

• #blue_shift(factor = 1.5) ⇒ Magick::Image

  Simulate a scene at nighttime in the moonlight.

• #blur_channel(*args) ⇒ Magick::Image

  Blurs the specified channel.

• #blur_image(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Blur the image.

• #border(width, height, color) ⇒ Magick::Image

  Surrounds the image with a border of the specified width, height, and named color.

• #border!(width, height, color) ⇒ Object

  Surrounds the image with a border of the specified width, height, and named color.

• #border_color ⇒ String

  Return the name of the border color as a String.

• #border_color=(color) ⇒ Magick::Pixel, String

  Set the the border color.

• #bounding_box ⇒ Magick::Rectangle

  Returns the bounding box of an image canvas.

• #change_geometry(geom_arg) {|column, row, image| ... } ⇒ Object

  This method supports resizing a method by specifying constraints.

• #change_geometry!(geom_arg) {|column, row, image| ... } ⇒ Object

  This method supports resizing a method by specifying constraints.

• #changed? ⇒ Boolean

  Return true if any pixel in the image has been altered since the image was constituted.

• #channel(channel_arg) ⇒ Magick::Image

  Extract a channel from the image.

• #channel_compare(*args) ⇒ Array

  Compare one or more channels in two images and returns the specified distortion metric and a comparison image.

• #channel_depth(*args) ⇒ Integer

  Returns the maximum depth for the specified channel or channels.

• #channel_entropy(*args) ⇒ Array<Float>

  Return an array of the entropy for the channel.

• #channel_extrema(*args) ⇒ Array<Integer>

  Returns the minimum and maximum intensity values for the specified channel or channels.

• #channel_mean(*args) ⇒ Array<Float>

  Returns the mean and standard deviation values for the specified channel or channels.

• #charcoal(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Return a new image that is a copy of the input image with the edges highlighted.

• #check_destroyed ⇒ nil

  Raises DestroyedImageError if the image has been destroyed.

• #chop(x, y, width, height) ⇒ Magick::Image

  Remove a region of an image and collapses the image to occupy the removed portion.

• #chromaticity ⇒ Magick::Chromaticity

  Return the red, green, blue, and white-point chromaticity values as a Chromaticity.

• #chromaticity=(chroma) ⇒ Magick::Chromaticity

  Set the red, green, blue, and white-point chromaticity values from a Chromaticity.

• #class_type ⇒ Magick::ClassType

  Return the image's storage class (a.k.a. storage type, class type).

• #class_type=(new_class_type) ⇒ Magick::ClassType

  Change the image's storage class.

• #clone ⇒ Magick::Image

  Same as #dup except the frozen state of the original is propagated to the new copy.

• #clut_channel(*args) ⇒ Magick::Image

  Replace the channel values in the target image with a lookup of its replacement value in an LUT gradient image.

• #color_fill_to_border(x, y, fill) ⇒ Object

  Set all pixels that are neighbors of x,y and are not the border color to the fill color.

• #color_flood_fill(target_color, fill_color, xv, yv, method) ⇒ Magick::Image

  Change the color value of any pixel that matches target_color and is an immediate neighbor.

• #color_floodfill(x, y, fill) ⇒ Object

  Set all pixels that have the same color as the pixel at x,y and are neighbors to the fill color.

• #color_histogram ⇒ Hash<Magick::Pixel, Integer>

  Computes the number of times each unique color appears in the image.

• #color_point(x, y, fill) ⇒ Object

  Set the color at x,y.

• #color_profile ⇒ String^?

  Return the ICC color profile as a String.

• #color_profile=(profile) ⇒ String^?

  Set the ICC color profile.

• #color_reset!(fill) ⇒ Object

  Set all pixels to the fill color.

• #colorize(*args) ⇒ Magick::Image

  Blend the fill color specified by "target" with each pixel in the image.

• #colormap(*args) ⇒ String

  Return the color in the colormap at the specified index.

• #colors ⇒ Integer

  Get the number of colors in the colormap.

• #colorspace ⇒ Magick::ColorspaceType

  Return the Image pixel interpretation.

• #colorspace=(colorspace) ⇒ Magick::ColorspaceType

  Set the image's colorspace.

• #columns ⇒ Integer

  Get image columns.

• #compare_channel(*args) ⇒ Array

  Compare one or more channels in two images and returns the specified distortion metric and a comparison image.

• #compose ⇒ Magick::CompositeOperator

  Return the composite operator attribute.

• #compose=(compose_arg) ⇒ Magick::CompositeOperator

  Set the composite operator attribute.

• #composite(*args) ⇒ Magick::Image

  Composites src onto dest using the specified composite operator.

• #composite!(*args) ⇒ Magick::Image

  Composites src onto dest using the specified composite operator.

• #composite_affine(source, affine_matrix) ⇒ Magick::Image

  Composite the source over the destination image as dictated by the affine transform.

• #composite_channel(*args) ⇒ Magick::Image

  Composite the source over the destination image channel as dictated by the affine transform.

• #composite_channel!(*args) ⇒ Magick::Image

  Composite the source over the destination image channel as dictated by the affine transform.

• #composite_mathematics(*args) ⇒ Magick::Image

  Merge the source and destination images according to the formula aScDc + bSc + cDc + d where Sc is the source pixel and Dc is the destination pixel.

• #composite_tiled(*args) ⇒ Magick::Image

  Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile option.

• #composite_tiled!(*args) ⇒ Magick::Image

  Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile option.

• #compress_colormap! ⇒ Magick::Image

  Removes duplicate or unused entries in the colormap.

• #compression ⇒ Magick::CompressionType

  Get the compression attribute.

• #compression=(compression) ⇒ Magick::CompressionType

  Set the compression attribute.

• #contrast(sharpen = false) ⇒ Magick::Image

  Enhance the intensity differences between the lighter and darker elements of the image.

• #contrast_stretch_channel(*args) ⇒ Magick::Image

  This method is a simple image enhancement technique that attempts to improve the contrast in an image by `stretching' the range of intensity values it contains to span a desired range of values.

• #convolve(order_arg, kernel_arg) ⇒ Magick::Image

  Apply a custom convolution kernel to the image.

• #convolve_channel(*args) ⇒ Magick::Image

  Applies a custom convolution kernel to the specified channel or channels in the image.

• #copy ⇒ Magick::Image

  Alias for #dup.

• #crop(*args) ⇒ Magick::Image

  Extract a region of the image defined by width, height, x, y.

• #crop!(*args) ⇒ Magick::Image

  Extract a region of the image defined by width, height, x, y.

• #cur_image ⇒ Object

  Used by ImageList methods - see ImageList#cur_image.

• #cycle_colormap(amount) ⇒ Magick::Image

  Displaces the colormap by a given number of positions.

• #decipher(passphrase) ⇒ Magick::Image

  Decipher an enciphered image.

• #define(artifact, value) ⇒ String^?

  Associates makes a copy of the given string arguments and inserts it into the artifact tree.

• #delay ⇒ Integer

  Get the Number of ticks which must expire before displaying the next image in an animated sequence.

• #delay=(val) ⇒ Numeric

  Set the Number of ticks which must expire before displaying the next image in an animated sequence.

• #delete_compose_mask ⇒ Magick::Image

  Delete the image composite mask.

• #delete_profile(name) ⇒ Magick::Image

  Deletes the specified profile.

• #density ⇒ String

  Get the vertical and horizontal resolution in pixels of the image.

• #density=(density_arg) ⇒ Magick::Geometry, String

  Set the vertical and horizontal resolution in pixels of the image.

• #depth ⇒ Integer

  Return the image depth (8, 16 or 32).

• #deskew(threshold = 0.40, auto_crop_width = nil) ⇒ Magick::Image

  Straightens an image.

• #despeckle ⇒ Magick::Image

  Reduce the speckle noise in an image while preserving the edges of the original image.

• #destroy! ⇒ Magick::Image

  Free all the memory associated with an image.

• #destroyed? ⇒ Boolean

  Return true if the image has been destroyed, false otherwise.

• #difference(other) ⇒ Array<Float>

  Compares two images and computes statistics about their difference.

• #directory ⇒ String^?

  Get image directory.

• #dispatch(x, y, columns, rows, map, float = false) ⇒ Array<Numeric>

  Extract pixel data from the image and returns it as an array of pixels.

• #displace(displacement_map, x_amp, y_amp = x_amp, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

  Uses displacement_map to move color from img to the output image.

• #display {|info| ... } ⇒ Magick::Image (also: #__display__)

  Display the image to an X window screen.

• #dispose ⇒ Magick::DisposeType

  Return the dispose attribute as a DisposeType enum.

• #dispose=(dispose) ⇒ Magick::DisposeType

  Set the dispose attribute.

• #dissolve(overlay, src_percent, dst_percent = -1.0, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

  Composites the overlay image into the target image.

• #distort(*args) ⇒ Magick::Image

  Distort an image using the specified distortion type and its required arguments.

• #distortion_channel(*args) ⇒ Float

  Compares one or more image channels of an image to a reconstructed image and returns the specified distortion metric.

• #dup ⇒ Magick::Image

  Duplicates a image.

• #each_iptc_dataset ⇒ Object

  Iterate over IPTC record number:dataset tags, yield for each non-nil dataset.

• #each_pixel ⇒ Object

  Thanks to Russell Norris!.

• #each_profile {|name, val| ... } ⇒ Object

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

• #edge(radius = 0.0) ⇒ Magick::Image

  Find edges in an image.

• #emboss(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Adds a 3-dimensional effect.

• #encipher(passphrase) ⇒ Magick::Image

  Encipher an image.

• #endian ⇒ Magick::EndianType

  Return endian option for images that support it.

• #endian=(type) ⇒ Magick::EndianType

  Set endian option for images that support it.

• #enhance ⇒ Magick::Image

  Apply a digital filter that improves the quality of a noisy image.

• #equalize ⇒ Magick::Image

  Apply a histogram equalization to the image.

• #equalize_channel(*args) ⇒ Magick::Image

  Applies a histogram equalization to the image.

• #erase! ⇒ Magick::Image

  Reset the image to the background color.

• #excerpt(x, y, width, height) ⇒ Magick::Image

  This method is very similar to crop.

• #excerpt!(x, y, width, height) ⇒ Magick::Image

  In-place form of #excerpt.

• #export_pixels(x = 0, y = 0, cols = self.columns, rows = self.rows, map = "RGB") ⇒ Array<Numeric>

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

• #export_pixels_to_str(x = 0, y = 0, cols = self.columns, rows = self.rows, map = "RGB", type = Magick::CharPixel) ⇒ String

  Extracts the pixel data from the specified rectangle and returns it as a string.

• #extent(width, height, x = 0, y = 0) ⇒ Magick::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.

• #extract_info ⇒ Magick::Rectangle

  The extract_info attribute reader.

• #extract_info=(rect) ⇒ Magick::Rectangle

  Set the extract_info attribute.

• #filename ⇒ String

  Get image filename.

• #filesize ⇒ Integer

  Return the image file size.

• #filter ⇒ Magick::FilterType

  Get filter type.

• #filter=(filter) ⇒ Magick::FilterType

  Set filter type.

• #find_similar_region(target, x = 0, y = 0) ⇒ Array<Numeric>^?

  This interesting method searches for a rectangle in the image that is similar to the target.

• #flip ⇒ Magick::Image

  Create a vertical mirror image by reflecting the pixels around the central x-axis.

• #flip! ⇒ Magick::Image

  Create a vertical mirror image by reflecting the pixels around the central x-axis.

• #flop ⇒ Magick::Image

  Create a horizonal mirror image by reflecting the pixels around the central y-axis.

• #flop! ⇒ Magick::Image

  Create a horizonal mirror image by reflecting the pixels around the central y-axis.

• #format ⇒ String^?

  Return the image encoding format.

• #format=(magick) ⇒ String

  Set the image encoding format.

• #frame(width = self.columns+25*2, height = self.rows+25*2, x = 25, y = 25, inner_bevel = 6, outer_bevel = 6, color = self.matte_color) ⇒ Magick::Image

  Add a simulated three-dimensional border around the image.

• #function_channel(*args) ⇒ Magick::Image

  Set the function on a channel.

• #fuzz ⇒ Float

  Get the number of algorithms search for a target color.

• #fuzz=(fuzz) ⇒ String, Numeric

  Set the number of algorithms search for a target color.

• #fx(*args) ⇒ Magick::Image

  Apply fx on the image.

• #gamma ⇒ Float

  Get the gamma level of the image.

• #gamma=(val) ⇒ Numeric

  Set the gamma level of the image.

• #gamma_channel(*args) ⇒ Magick::Image

  Apply gamma to a channel.

• #gamma_correct(red_gamma, green_gamma = red_gamma, blue_gamma = green_gamma) ⇒ Magick::Image

  gamma-correct an image.

• #gaussian_blur(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Blur the image.

• #gaussian_blur_channel(*args) ⇒ Magick::Image

  Blur the image on a channel.

• #geometry ⇒ String

  Get the preferred size of the image when encoding.

• #geometry=(geometry) ⇒ Magick::Geometry, String

  Set the preferred size of the image when encoding.

• #get_exif_by_entry(*entry) ⇒ Object

  Retrieve EXIF data by entry or all.

• #get_exif_by_number(*tag) ⇒ Object

  Retrieve EXIF data by tag number or all tag/value pairs.

• #get_iptc_dataset(ds) ⇒ Object

  Retrieve IPTC information by record number:dataset tag constant defined in Magick::IPTC, above.

• #get_pixels(x_arg, y_arg, cols_arg, rows_arg) ⇒ Array<Magick::Pixel>

  Gets the pixels from the specified rectangle within the image.

• #gravity ⇒ Magick::GravityType

  Get the direction that the image gravitates within the composite.

• #gravity=(gravity) ⇒ Magick::GravityType

  Set the direction that the image gravitates within the composite.

• #gray? ⇒ Boolean

  Return true if all the pixels in the image have the same red, green, and blue intensities.

• #grey? ⇒ Boolean

  Return true if all the pixels in the image have the same red, green, and blue intensities.

• #histogram? ⇒ Boolean

  Return true if has 1024 unique colors or less.

• #image_type ⇒ Magick::ImageType

  Get the image type classification.

• #image_type=(image_type) ⇒ Magick::ImageType

  Set the image type classification.

• #implode(amount = 0.50) ⇒ Magick::Image

  Implode the image by the specified percentage.

• #store_pixels(x, y, columns, rows, map, pixels, type = Magick::CharPixel) ⇒ Magick::Image

  Store image pixel data from an array.

• #initialize(cols, rows, fill = nil) ⇒ Magick::Image constructor

  Initialize a new Image object If the fill argument is omitted, fill with background color.

• #initialize_copy(orig) ⇒ Magick::Image

  Initialize copy, clone, dup.

• #inspect ⇒ String

  Override Object#inspect - return a string description of the image.

• #interlace ⇒ Magick::InterlaceType

  Get the type of interlacing scheme (default NoInterlace).

• #interlace=(interlace) ⇒ Magick::InterlaceType

  Set the type of interlacing scheme.

• #iptc_profile ⇒ String^?

  Return the IPTC profile as a String.

• #iptc_profile=(profile) ⇒ String^?

  Set the IPTC profile.

• #iterations ⇒ Object

  These are undocumented methods.

• #iterations=(val) ⇒ Object

  do not document! Only used by Image#iterations=.

• #level(black_point = 0.0, white_point = nil, gamma = nil) ⇒ Object

  (Thanks to Al Evans for the suggestion.).

• #level2(black_point = 0.0, white_point = Magick::QuantumRange, gamma = 1.0) ⇒ Magick::Image

  Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range.

• #level_channel(aChannelType, black = 0.0, white = 1.0, gamma = Magick::QuantumRange) ⇒ Magick::Image

  Similar to #level2 but applies to a single channel only.

• #level_colors(*args) ⇒ Magick::Image

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

• #levelize_channel(*args) ⇒ Magick::Image

  Maps black and white to the specified points.

• #linear_stretch(black_point, white_point = pixels-black_point) ⇒ Magick::Image

  Linear with saturation stretch.

• #liquid_rescale(columns, rows, delta_x = 0.0, rigidity = 0.0) ⇒ Magick::Image

  Rescale image with seam carving.

• #magnify ⇒ Magick::Image

  Scale an image proportionally to twice its size.

• #magnify! ⇒ Magick::Image

  Scale an image proportionally to twice its size.

• #marshal_dump ⇒ Array<String>

  Support Marshal.dump.

• #marshal_load(ary) ⇒ Object

  Support Marshal.load.

• #mask(*args) ⇒ Magick::Image^?

  Get/Sets an image clip mask created from the specified mask image.

• #matte_color ⇒ String

  Return the matte color.

• #matte_color=(color) ⇒ Magick::Pixel, String

  Set the matte color.

• #matte_fill_to_border(x, y) ⇒ Object

  Make transparent any neighbor pixel that is not the border color.

• #Image ⇒ Magick::Image

  Makes transparent all the pixels that are the same color as the pixel at x, y, and are neighbors.

• #matte_floodfill(x, y) ⇒ Object

  Make transparent any pixel that matches the color of the pixel at (x,y) and is a neighbor.

• #matte_point(x, y) ⇒ Object

  Make the pixel at (x,y) transparent.

• #matte_replace(x, y) ⇒ Object

  Make transparent all pixels that are the same color as the pixel at (x, y).

• #matte_reset! ⇒ Object

  Make all pixels transparent.

• #mean_error_per_pixel ⇒ Float

  Get the mean error per pixel computed when a image is color reduced.

• #median_filter(radius = 0.0) ⇒ Magick::Image

  Apply a digital filter that improves the quality of a noisy image.

• #mime_type ⇒ String^?

  Return the officially registered (or de facto) MIME media-type corresponding to the image format.

• #minify ⇒ Magick::Image

  Scale an image proportionally to half its size.

• #minify! ⇒ Magick::Image

  Scale an image proportionally to half its size.

• #modulate(brightness = 1.0, saturation = 1.0, hue = 1.0) ⇒ Magick::Image

  Changes the brightness, saturation, and hue.

• #monochrome? ⇒ Boolean

  Return true if all the pixels in the image have the same red, green, and blue intensities and the intensity is either 0 or QuantumRange.

• #montage ⇒ String^?

  Tile size and offset within an image montage.

• #morphology(method_v, iterations, kernel_v) ⇒ Magick::Image

  Apply a user supplied kernel to the image according to the given mophology method.

• #morphology_channel(channel_v, method_v, iterations_v, kernel_v) ⇒ Magick::Image

  Apply a user supplied kernel to the image channel according to the given mophology method.

• #motion_blur(radius = 0.0, sigma = 1.0, angle = 0.0) ⇒ Magick::Image

  Simulate motion blur.

• #negate(grayscale = false) ⇒ Magick::Image

  Negate the colors in the reference image.

• #negate_channel(*args) ⇒ Magick::Image

  Negate the colors on a particular channel.

• #normalize ⇒ Magick::Image

  Enhance the contrast of a color image by adjusting the pixels color to span the entire range of colors available.

• #normalize_channel(*args) ⇒ Magick::Image

  Enhances the contrast of a color image by adjusting the pixel color to span the entire range of colors available.

• #normalized_maximum_error ⇒ Float

  Get The normalized maximum error per pixel computed when an image is color reduced.

• #normalized_mean_error ⇒ Float

  Get the normalized mean error per pixel computed when an image is color reduced.

• #number_colors ⇒ Integer

  Return the number of unique colors in the image.

• #offset ⇒ Integer

  Get the number of bytes to skip over when reading raw image.

• #offset=(val) ⇒ Numeric

  Set the number of bytes to skip over when reading raw image.

• #oil_paint(radius = 3.0) ⇒ Magick::Image

  Apply a special effect filter that simulates an oil painting.

• #opaque(target, fill) ⇒ Magick::Image

  Change any pixel that matches target with the color defined by fill.

• #opaque? ⇒ Boolean

  Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.

• #opaque_channel(*args) ⇒ Magick::Image

  Changes all pixels having the target color to the fill color.

• #ordered_dither(threshold_map = '2x2') ⇒ Magick::Image

  Dithers the image to a predefined pattern.

• #orientation ⇒ Magick::OrientationType

  Get the value of the Exif Orientation Tag.

• #orientation=(orientation) ⇒ Magick::OrientationType

  Set the orientation attribute.

• #page ⇒ Magick::Rectangle

  The page attribute getter.

• #page=(rect) ⇒ Magick::Rectangle

  The page attribute setter.

• #paint_transparent(color, invert, fuzz, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

  Changes the opacity value of all the pixels that match color to the value specified by opacity.

• #palette? ⇒ Boolean

  Return true if the image is PseudoClass and has 256 unique colors or less.

• #pixel_color(*args) ⇒ Object

  Get/set the color of the pixel at x, y.

• #pixel_interpolation_method ⇒ Magick::PixelInterpolateMethod

  Get the "interpolate" field.

• #pixel_interpolation_method=(method) ⇒ Magick::PixelInterpolateMethod

  Set the "interpolate" field.

• #polaroid(*args) ⇒ Magick::Image

  Produce an image that looks like a Polaroid instant picture.

• #posterize(levels = 4, dither = false) ⇒ Object

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

• #preview(preview) ⇒ Magick::Image

  Creates an image that contains 9 small versions of the receiver image.

• #profile!(name, profile) ⇒ Magick::Image

  Set the image profile.

• #properties ⇒ Object

  If called with an associated block, properties runs the block once for each property defined for the image.

• #quality ⇒ Integer

  Get image quality.

• #quantize(number_colors = 256, colorspace = Magick::RGBColorspace, dither = true, tree_depth = 0, measure_error = false) ⇒ Magick::Image

  Analyzes the colors within a reference image and chooses a fixed number of colors to represent the image.

• #quantum_depth ⇒ Integer

  Return the image depth to the nearest Quantum (8, 16, or 32).

• #quantum_operator(*args) ⇒ Magick::Image

  Performs the requested integer arithmetic operation on the selected channel of the image.

• #radial_blur(angle_obj) ⇒ Magick::Image

  Applies a radial blur to the image.

• #radial_blur_channel(*args) ⇒ Magick::Image

  Applies a radial blur to the selected image channels.

• #raise(width = 6, height = 6, raised = true) ⇒ Magick::Image

  Create a simulated three-dimensional button-like effect by lightening and darkening the edges of the image.

• #random_threshold_channel(*args) ⇒ Magick::Image

  Changes the value of individual pixels based on the intensity of each pixel compared to a random threshold.

• #recolor(color_matrix) ⇒ Magick::Image

  Use this method to translate, scale, shear, or rotate image colors.

• #reduce_noise(radius) ⇒ Magick::Image

  Smooth the contours of an image while still preserving edge information.

• #remap(remap_image, dither_method = Magick::RiemersmaDitherMethod) ⇒ Object (also: #affinity)

  Reduce the number of colors in img to the colors used by remap_image.

• #rendering_intent ⇒ Magick::RenderingIntent

  Get the type of rendering intent.

• #rendering_intent=(ri) ⇒ Magick::RenderingIntent

  Set the type of rendering intent..

• #resample(x_resolution = 72.0, y_resolution = 72.0, filter = self.filter, blur = self.blur) ⇒ Magick

  Resample image to specified horizontal resolution, vertical resolution, filter and blur factor.

• #resample!(x_resolution = 72.0, y_resolution = 72.0, filter = self.filter, blur = self.blur) ⇒ Magick

  Resample image to specified horizontal resolution, vertical resolution, filter and blur factor.

• #resize(*args) ⇒ Magick::Image

  Scale an image to the desired dimensions using the specified filter and blur factor.

• #resize!(*args) ⇒ Magick::Image

  Scale an image to the desired dimensions using the specified filter and blur factor.

• #resize_to_fill(ncols, nrows = nil, gravity = CenterGravity) ⇒ Object (also: #crop_resized)

  Force an image to exact dimensions without changing the aspect ratio.

• #resize_to_fill!(ncols, nrows = nil, gravity = CenterGravity) ⇒ Object (also: #crop_resized!)
• #resize_to_fit(cols, rows = nil) ⇒ Object

  Convenience method to resize retaining the aspect ratio.

• #resize_to_fit!(cols, rows = nil) ⇒ Object
• #roll(x_offset, y_offset) ⇒ Magick::Image

  Offset an image as defined by x_offset and y_offset.

• #rotate(*args) ⇒ Magick::Image

  Rotate the receiver by the specified angle.

• #rotate!(*args) ⇒ Magick::Image

  Rotate the image.

• #rows ⇒ Integer

  Return image rows.

• #sample(*args) ⇒ Magick::Image

  Scale an image to the desired dimensions with pixel sampling.

• #sample!(*args) ⇒ Magick::Image

  Scale an image to the desired dimensions with pixel sampling.

• #scale(*args) ⇒ Magick::Image

  Change the size of an image to the given dimensions.

• #scale!(*args) ⇒ Magick::Image

  Change the size of an image to the given dimensions.

• #scene ⇒ Integer

  Return the scene number assigned to the image the last time the image was written to a multi-image image file.

• #segment(colorspace = Magick::RGBColorspace, cluster_threshold = 1.0, smoothing_threshold = 1.5, verbose = false) ⇒ Magick::Image

  Segments an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique.

• #selective_blur_channel(*args) ⇒ Magick::Image

  Selectively blur pixels within a contrast threshold.

• #separate(*args) ⇒ Magick::ImageList

  Constructs a grayscale image for each channel specified.

• #sepiatone(threshold = Magick::QuantumRange) ⇒ Magick::Image

  Applies a special effect to the image, similar to the effect achieved in a photo darkroom by sepia toning.

• #set_channel_depth(channel_arg, depth) ⇒ Object

  Sets the depth of the image channel.

• #shade(shading = false, azimuth = 30.0, elevation = 30.0) ⇒ Magick::Image

  Shine a distant light on an image to create a three-dimensional effect.

• #Image ⇒ Magick::Image

  Call ShadowImage.

• #sharpen(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Sharpen an image.

• #sharpen_channel(*args) ⇒ Magick::Image

  Sharpen image on a channel.

• #shave(width, height) ⇒ Magick::Image

  Shave pixels from the image edges, leaving a rectangle of the specified width & height in the center.

• #shave!(width, height) ⇒ Magick::Image

  Shave pixels from the image edges, leaving a rectangle of the specified width & height in the center.

• #shear(x_shear, y_shear) ⇒ Magick::Image

  Shearing slides one edge of an image along the X or Y axis, creating a parallelogram.

• #sigmoidal_contrast_channel(*args) ⇒ Magick::Image

  Adjusts the contrast of an image channel with a non-linear sigmoidal contrast algorithm.

• #signature ⇒ String^?

  Compute a message digest from an image pixel stream with an implementation of the NIST SHA-256 Message Digest algorithm.

• #sketch(radius = 0.0, sigma = 1.0, angle = 0.0) ⇒ Magick::Image

  Simulates a pencil sketch.

• #solarize(threshold = 50.0) ⇒ Object

  Apply a special effect to the image, similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light.

• #sparse_color(*args) ⇒ Magick::Image

  Fills the image with the specified color or colors, starting at the x,y coordinates associated with the color and using the specified interpolation method.

• #splice(x, y, width, height, color = self.background_color) ⇒ Magick::Image

  Splice a solid color into the part of the image specified by the x, y, width, and height arguments.

• #spread(radius = 3.0) ⇒ Magick::Image

  Randomly displace each pixel in a block defined by "radius".

• #start_loop ⇒ Boolean

  Get the Boolean value that indicates the first image in an animation.

• #start_loop=(val) ⇒ Boolean

  Set the Boolean value that indicates the first image in an animation.

• #stegano(watermark_image, offset) ⇒ Magick::Image

  Hides a digital watermark in the receiver.

• #stereo(offset_image_arg) ⇒ Magick::Image

  Combine two images and produces a single image that is the composite of a left and right image of a stereo pair.

• #store_pixels(x_arg, y_arg, cols_arg, rows_arg, new_pixels) ⇒ Magick::Image

  Replace the pixels in the specified rectangle with the pixels in the pixels array.

• #strip! ⇒ Magick::Image

  Strips an image of all profiles and comments.

• #swirl(degrees_obj) ⇒ Magick::Image

  Swirl the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved.

• #texture_fill_to_border(x, y, texture) ⇒ Object

  Replace neighboring pixels to border color with texture pixels.

• #texture_flood_fill(color_obj, texture_obj, x_obj, y_obj, method_obj) ⇒ Magick::Image

  Emulates Magick++'s floodFillTexture.

• #texture_floodfill(x, y, texture) ⇒ Object

  Replace matching neighboring pixels with texture pixels.

• #threshold(threshold_obj) ⇒ Magick::Image

  Change the value of individual pixels based on the intensity of each pixel compared to threshold.

• #thumbnail(*args) ⇒ Magick::Image

  The thumbnail method is a fast resizing method suitable for use when the size of the resulting image is < 10% of the original.

• #thumbnail!(*args) ⇒ Magick::Image

  The thumbnail method is a fast resizing method suitable for use when the size of the resulting image is < 10% of the original.

• #ticks_per_second ⇒ Integer

  Get the number of ticks per second.

• #ticks_per_second=(tps) ⇒ Numeric

  Set the number of ticks per second.

• #tint(tint, red_alpha, green_alpha = red_alpha, blue_alpha = red_alpha, alpha_alpha = 1.0) ⇒ Object

  Applies a color vector to each pixel in the image.

• #to_blob {|info| ... } ⇒ String

  Return a "blob" (a String) from the image.

• #to_color(pixel_arg) ⇒ String

  Return a color name for the color intensity specified by the Magick::Pixel argument.

• #total_colors ⇒ Integer

  Alias for #number_colors.

• #total_ink_density ⇒ Float

  Return the total ink density for a CMYK image.

• #transparent(color, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

  Changes the opacity value of all the pixels that match color to the value specified by opacity.

• #transparent_chroma(low, high, invert, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

  Changes the opacity value associated with any pixel between low and high to the value defined by opacity.

• #transparent_color ⇒ String

  Return the name of the transparent color as a String.

• #transparent_color=(color) ⇒ Magick::Pixel, String

  Set the the transparent color to the specified color spec.

• #transpose ⇒ Magick::Image

  Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them by 90 degrees.

• #transpose! ⇒ Magick::Image

  Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them by 90 degrees.

• #transverse ⇒ Magick::Image

  Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them by 270 degrees.

• #transverse! ⇒ Magick::Image

  Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them by 270 degrees In-place form of #transverse.

• #trim(reset = false) ⇒ Magick::Image

  Removes the edges that are exactly the same color as the corner pixels.

• #trim!(reset = false) ⇒ Magick::Image

  Removes the edges that are exactly the same color as the corner pixels.

• #undefine(artifact) ⇒ Magick::Image

  Removes an artifact from the image and returns its value.

• #unique_colors ⇒ Magick::Image

  Constructs a new image with one pixel for each unique color in the image.

• #units ⇒ Magick::ResolutionType

  Get the units of image resolution.

• #units=(restype) ⇒ Magick::ResolutionType

  Set the units of image resolution.

• #unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05) ⇒ Magick::Image

  Sharpen an image.

• #unsharp_mask_channel(*args) ⇒ Magick::Image

  Sharpen an image.

• #view(x, y, width, height) ⇒ Object

  Construct a view.

• #vignette(horz_radius = self.columns*0.1+0.5, vert_radius = self.rows*0.1+0.5, radius = 0.0, sigma = 1.0) ⇒ Magick::Image

  Soften the edges of an image.

• #virtual_pixel_method ⇒ Magick::VirtualPixelMethod

  Get the "virtual pixels" behave.

• #virtual_pixel_method=(method) ⇒ Magick::VirtualPixelMethod

  Specify how "virtual pixels" behave.

• #watermark(*args) ⇒ Magick::Image

  Composites a watermark image on the target image using the Modulate composite operator.

• #wave(amplitude = 25.0, wavelength = 150.0) ⇒ Magick::Image

  Create a "ripple" effect in the image by shifting the pixels vertically along a sine wave whose amplitude and wavelength is specified by the given parameters.

• #wet_floor(initial = 0.5, rate = 1.0) ⇒ Magick::Image

  Creates a "wet floor" reflection.

• #white_threshold(red, green, blue, alpha: alpha) ⇒ Magick::Image

  Forces all pixels above the threshold into white while leaving all pixels below the threshold unchanged.

• #write(file) {|info| ... } ⇒ Magick::Image

  Write the image to the file.

• #x_resolution ⇒ Float

  Get the horizontal resolution of the image.

• #x_resolution=(val) ⇒ Numeric

  Set the horizontal resolution of the image.

• #y_resolution ⇒ Float

  Get the vertical resolution of the image.

• #y_resolution=(val) ⇒ Numeric

  Set the vertical resolution of the image.

Constructor Details

#initialize(cols, rows, fill = nil) ⇒ Magick::Image

Initialize a new Image object If the fill argument is omitted, fill with background color.

Returns self.

Parameters:

• cols (Numeric) —

  the image width

• rows (Numeric) —

  the image height

• fill (Magick::HatchFill, Magick::SolidFill) (defaults to: nil) —

  if object is given as fill argument, background color will be filled using it.

# File 'ext/RMagick/rmimage.cpp', line 9891

VALUE
Image_initialize(int argc, VALUE *argv, VALUE self)
{
    VALUE fill = Qnil;
    Info *info;
    VALUE info_obj;
    Image *image;
    unsigned long cols, rows;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    switch (argc)
    {
        case 3:
            fill = argv[2];
        case 2:
            rows = NUM2ULONG(argv[1]);
            cols = NUM2ULONG(argv[0]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or 3)", argc);
            break;
    }

    // Create a new Info object to use when creating this image.
    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

    image = rm_acquire_image(info);
    if (!image)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }

    rm_set_user_artifact(image, info);

    // NOW store a real image in the image object.
    UPDATE_DATA_PTR(self, image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageExtent) args = { image, cols, rows, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageExtent), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageExtent) args = { image, cols, rows };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageExtent), &args);
#endif

    rm_sync_image_options(image, info);

    // If the caller did not supply a fill argument, call SetImageBackgroundColor
    // to fill the image using the background color. The background color can
    // be set by specifying it when creating the Info parm block.
    if (NIL_P(fill))
    {
#if defined(IMAGEMAGICK_7)
        exception = AcquireExceptionInfo();
        GVL_STRUCT_TYPE(SetImageBackgroundColor) args = { image, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args);
        CHECK_EXCEPTION();
        DestroyExceptionInfo(exception);
#else
        GVL_STRUCT_TYPE(SetImageBackgroundColor) args = { image };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args);
#endif
    }
    // fillobj.fill(self)
    else
    {
        rb_funcall(fill, rm_ID_fill, 1, self);
    }

    RB_GC_GUARD(fill);
    RB_GC_GUARD(info_obj);

    return self;
}

Class Method Details

._load(str) ⇒ Magic::Image

Implement marshalling.

Parameters:

• str (String) —

  the marshalled string

Returns:

• (Magic::Image) —

  a new image

See Also:

• #_dump

# File 'ext/RMagick/rmimage.cpp', line 8905

VALUE
Image__load(VALUE klass ATTRIBUTE_UNUSED, VALUE str)
{
    Image *image;
    ImageInfo *info;
    DumpedImage mi;
    ExceptionInfo *exception;
    char *blob;
    size_t length;

    blob = rm_str2cstr(str, &length);

    // Must be as least as big as the 1st 4 fields in DumpedImage
    if (length <= (long)(sizeof(DumpedImage)-MaxTextExtent))
    {
        rb_raise(rb_eTypeError, "image is invalid or corrupted (too short)");
    }

    // Retrieve & validate the image format from the header portion
    mi.id = ((DumpedImage *)blob)->id;
    if (mi.id != DUMPED_IMAGE_ID)
    {
        rb_raise(rb_eTypeError, "image is invalid or corrupted (invalid header)");
    }

    mi.mj = ((DumpedImage *)blob)->mj;
    mi.mi = ((DumpedImage *)blob)->mi;
    if (   mi.mj != DUMPED_IMAGE_MAJOR_VERS
           || mi.mi > DUMPED_IMAGE_MINOR_VERS)
    {
        rb_raise(rb_eTypeError, "incompatible image format (can't be read)\n"
                 "\tformat version %d.%d required; %d.%d given",
                 DUMPED_IMAGE_MAJOR_VERS, DUMPED_IMAGE_MINOR_VERS,
                 mi.mj, mi.mi);
    }

    mi.len = ((DumpedImage *)blob)->len;

    // Must be bigger than the header
    if (length <= (mi.len + sizeof(DumpedImage) - MaxTextExtent))
    {
        rb_raise(rb_eTypeError, "image is invalid or corrupted (too short)");
    }

    info = CloneImageInfo(NULL);

    memcpy(info->magick, ((DumpedImage *)blob)->magick, mi.len);
    info->magick[mi.len] = '\0';

    exception = AcquireExceptionInfo();

    blob += offsetof(DumpedImage, magick) + mi.len;
    length -= offsetof(DumpedImage, magick) + mi.len;
    GVL_STRUCT_TYPE(BlobToImage) args = { info, blob, (size_t)length, exception };
    image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlobToImage), &args);
    DestroyImageInfo(info);

    rm_check_exception(exception, image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(image);
}

.capture(silent = false, frame = false, descend = false, screen = false, borders = false) ⇒ Magick::Image .capture(silent = false, frame = false, descend = false, screen = false, borders = false) {|info| ... } ⇒ Magick::Image

Reads an image from an X window. Unless you identify a window to capture via the optional arguments block, when capture is invoked the cursor will turn into a cross. Click the cursor on the window to be captured.

Examples:

img = Image.capture { |options|
  options.filename = "root"
}

Overloads:

• .capture(silent = false, frame = false, descend = false, screen = false, borders = false) ⇒ Magick::Image

  Parameters:

  • silent (Boolean) (defaults to: false) —

    If true, suppress the beeps that signal the start and finish of the capture process.

  • frame (Boolean) (defaults to: false) —

    If true, include the window frame.

  • descend (Boolean) (defaults to: false) —

    If true, obtain image by descending window hierarchy.

  • screen (Boolean) (defaults to: false) —

    If true, specifies that the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent windows but appear over the specified window.

  • borders (Boolean) (defaults to: false) —

    If true, include the border in the image.

• .capture(silent = false, frame = false, descend = false, screen = false, borders = false) {|info| ... } ⇒ Magick::Image

  This yields Info to block with its object's scope.

  Parameters:

  • silent (Boolean) (defaults to: false) —

    If true, suppress the beeps that signal the start and finish of the capture process.

  • frame (Boolean) (defaults to: false) —

    If true, include the window frame.

  • descend (Boolean) (defaults to: false) —

    If true, obtain image by descending window hierarchy.

  • screen (Boolean) (defaults to: false) —

    If true, specifies that the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent windows but appear over the specified window.

  • borders (Boolean) (defaults to: false) —

    If true, include the border in the image.

  Yields:

  • (info)

  Yield Parameters:

  • info (Magick::Image::Info)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2260

VALUE
Image_capture(int argc, VALUE *argv, VALUE self ATTRIBUTE_UNUSED)
{
    Image *new_image;
    ImageInfo *image_info;
    VALUE info_obj;
    XImportInfo ximage_info;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    XGetImportInfo(&ximage_info);
    switch (argc)
    {
        case 5:
            ximage_info.borders = (MagickBooleanType)RTEST(argv[4]);
        case 4:
            ximage_info.screen  = (MagickBooleanType)RTEST(argv[3]);
        case 3:
            ximage_info.descend = (MagickBooleanType)RTEST(argv[2]);
        case 2:
            ximage_info.frame   = (MagickBooleanType)RTEST(argv[1]);
        case 1:
            ximage_info.silent  = (MagickBooleanType)RTEST(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 5)", argc);
            break;
    }

    // Get optional parms.
    // Set info->filename = "root", window ID number or window name,
    //  or nothing to do an interactive capture
    // Set info->server_name to the server name
    // Also info->colorspace, depth, dither, interlace, type
    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, image_info);

    // If an error occurs, IM will call our error handler and we raise an exception.
#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    new_image = XImportImage(image_info, &ximage_info, exception);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    new_image = XImportImage(image_info, &ximage_info);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    rm_ensure_result(new_image);

    rm_set_user_artifact(new_image, image_info);
    rm_sync_image_options(new_image, image_info);

    RB_GC_GUARD(info_obj);

    return rm_image_new(new_image);
}

.constitute(width_arg, height_arg, map_arg, pixels_arg) ⇒ Magick::Image

Creates an Image from the supplied pixel data. The pixel data must be in scanline order, top-to-bottom. The pixel data is an array of either all Fixed or all Float elements. If Fixed, the elements must be in the range [0..QuantumRange]. If Float, the elements must be normalized [0..1]. The "map" argument reflects 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).

The pixel array must have width X height X strlen(map) elements.

Parameters:

• width_arg (Numeric) —

  The number of columns in the image

• height_arg (Numeric) —

  The number of rows in the image

• map_arg (String) —

  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_arg (Array<Magick::Pixel>) —

  The pixel data in the array must be stored in scanline order, left-to-right and top-to-bottom. The elements in the array must be either all Integers or all Floats. If the elements are Integers, the Integers must be in the range [0..QuantumRange]. If the elements are Floats, they must be in the range [0..1].

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4330

VALUE
Image_constitute(VALUE klass ATTRIBUTE_UNUSED, VALUE width_arg, VALUE height_arg,
                 VALUE map_arg, VALUE pixels_arg)
{
    Image *new_image;
    VALUE pixel, pixel0;
    long x, npixels;
    size_t width, height, map_l;
    char *map;
    volatile union
    {
        double *f;
        Quantum *i;
        void *v;
    } pixels;
    VALUE pixel_class;
    StorageType stg_type;
    ExceptionInfo *exception;

    // rb_Array converts objects that are not Arrays to Arrays if possible,
    // and raises TypeError if it can't.
    pixels_arg = rb_Array(pixels_arg);

    if (NUM2LONG(width_arg) <= 0 || NUM2LONG(height_arg) <= 0)
    {
        rb_raise(rb_eArgError, "width and height must be greater than zero");
    }

    width = NUM2LONG(width_arg);
    height = NUM2LONG(height_arg);
    map = rm_str2cstr(map_arg, &map_l);

    npixels = width * height * map_l;
    if (RARRAY_LEN(pixels_arg) != npixels)
    {
        rb_raise(rb_eArgError, "wrong number of array elements (%ld for %ld)",
                 RARRAY_LEN(pixels_arg), npixels);
    }

    // Inspect the first element in the pixels array to determine the expected
    // type of all the elements. Allocate the pixel buffer.
    pixel0 = rb_ary_entry(pixels_arg, 0);
    if (rb_obj_is_kind_of(pixel0, rb_cFloat) == Qtrue)
    {
        pixels.f = ALLOC_N(double, npixels);
        stg_type = DoublePixel;
        pixel_class = rb_cFloat;
    }
    else if (rb_obj_is_kind_of(pixel0, rb_cInteger) == Qtrue)
    {
        pixels.i = ALLOC_N(Quantum, npixels);
        stg_type = QuantumPixel;
        pixel_class = rb_cInteger;
    }
    else
    {
        rb_raise(rb_eTypeError, "element 0 in pixel array is %s, must be numeric",
                 rb_class2name(CLASS_OF(pixel0)));
    }



    // Convert the array elements to the appropriate C type, store in pixel
    // buffer.
    for (x = 0; x < npixels; x++)
    {
        pixel = rb_ary_entry(pixels_arg, x);
        if (rb_obj_is_kind_of(pixel, pixel_class) != Qtrue)
        {
            xfree(pixels.v);
            rb_raise(rb_eTypeError, "element %ld in pixel array is %s, expected %s",
                     x, rb_class2name(CLASS_OF(pixel)), rb_class2name(CLASS_OF(pixel0)));
        }
        if (pixel_class == rb_cFloat)
        {
            pixels.f[x] = (float) NUM2DBL(pixel);
            if (pixels.f[x] < 0.0 || pixels.f[x] > 1.0)
            {
                xfree(pixels.v);
                rb_raise(rb_eArgError, "element %ld is out of range [0..1]: %f", x, pixels.f[x]);
            }
        }
        else
        {
            pixels.i[x] = NUM2QUANTUM(pixel);
        }
    }

    // This is based on ConstituteImage in IM 5.5.7
    new_image = rm_acquire_image((ImageInfo *) NULL);
    if (!new_image)
    {
        xfree(pixels.v);
        rb_raise(rb_eNoMemError, "not enough memory to continue.");
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageExtent) args_SetImageExtent = { new_image, width, height, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageExtent), &args_SetImageExtent);
#else
    GVL_STRUCT_TYPE(SetImageExtent) args_SetImageExtent = { new_image, width, height };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageExtent), &args_SetImageExtent);
    exception = &new_image->exception;
#endif

    if (rm_should_raise_exception(exception, RetainExceptionRetention))
    {
        xfree(pixels.v);
#if defined(IMAGEMAGICK_7)
        DestroyImage(new_image);
        rm_raise_exception(exception);
#else
        rm_check_image_exception(new_image, DestroyOnError);
#endif
    }

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(SetImageBackgroundColor) args_SetImageBackgroundColor = { new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args_SetImageBackgroundColor);
#else
    GVL_STRUCT_TYPE(SetImageBackgroundColor) args_SetImageBackgroundColor = { new_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args_SetImageBackgroundColor);
    exception = &new_image->exception;
#endif

    if (rm_should_raise_exception(exception, RetainExceptionRetention))
    {
        xfree(pixels.v);
#if defined(IMAGEMAGICK_7)
        DestroyImage(new_image);
        rm_raise_exception(exception);
#else
        rm_check_image_exception(new_image, DestroyOnError);
#endif
    }

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(ImportImagePixels) args_ImportImagePixels = { new_image, 0, 0, width, height, map, stg_type, (const void *)pixels.v, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImportImagePixels), &args_ImportImagePixels);
    xfree(pixels.v);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ImportImagePixels) args_ImportImagePixels = { new_image, 0, 0, width, height, map, stg_type, (const void *)pixels.v };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImportImagePixels), &args_ImportImagePixels);
    xfree(pixels.v);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    RB_GC_GUARD(pixel);
    RB_GC_GUARD(pixel0);
    RB_GC_GUARD(pixel_class);

    return rm_image_new(new_image);
}

.from_blob(blob) ⇒ Array<Magick::Image> .from_blob(blob) {|info| ... } ⇒ Array<Magick::Image>

Convert direct to memory image formats from string data.

Overloads:

• .from_blob(blob) ⇒ Array<Magick::Image>

  Parameters:

  • blob (String) —

    the blob data

• .from_blob(blob) {|info| ... } ⇒ Array<Magick::Image>

  This yields Info to block with its object's scope.

  Parameters:

  • blob (String) —

    the blob data

  Yields:

  • (info)

  Yield Parameters:

  • info (Magick::Image::Info)

Returns:

• (Array<Magick::Image>) —

  an array of new images

See Also:

• #to_blob

# File 'ext/RMagick/rmimage.cpp', line 7303

VALUE
Image_from_blob(VALUE klass ATTRIBUTE_UNUSED, VALUE blob_arg)
{
    Image *images;
    Info *info;
    VALUE info_obj;
    ExceptionInfo *exception;
    void *blob;
    size_t length;

    blob = (void *) rm_str2cstr(blob_arg, &length);

    // Get a new Info object - run the parm block if supplied
    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(BlobToImage) args = { info,  blob, (size_t)length, exception };
    images = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlobToImage), &args);
    rm_check_exception(exception, images, DestroyOnError);

    DestroyExceptionInfo(exception);

    rm_ensure_result(images);
    rm_set_user_artifact(images, info);
    rm_sync_image_options(images, info);

    RB_GC_GUARD(info_obj);

    return array_from_images(images);
}

.ping(file_arg) {|info| ... } ⇒ Array<Magick::Image>

Returns all the properties of an image or image sequence except for the pixels.

Parameters:

• file_arg (File, String) —

  the file containing image data or file name

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (Array<Magick::Image>) —

  an array of 1 or more new image objects (without pixel data)

See Also:

• read

# File 'ext/RMagick/rmimage.cpp', line 10584

VALUE
Image_ping(VALUE klass, VALUE file_arg)
{
    return rd_image(klass, file_arg, GVL_FUNC(PingImage));
}

.read(file_arg) {|info| ... } ⇒ Array<Magick::Image>

Call ReadImage.

Parameters:

• file_arg (File, String) —

  the file containing image data or file name

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (Array<Magick::Image>) —

  an array of 1 or more new image objects

# File 'ext/RMagick/rmimage.cpp', line 11505

VALUE
Image_read(VALUE klass, VALUE file_arg)
{
    return rd_image(klass, file_arg, GVL_FUNC(ReadImage));
}

.read_inline(content) {|info| ... } ⇒ Array<Magick::Image>

Read a Base64-encoded image.

Parameters:

• content (String) —

  the content

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (Array<Magick::Image>) —

  an array of new images

# File 'ext/RMagick/rmimage.cpp', line 11718

VALUE
Image_read_inline(VALUE self ATTRIBUTE_UNUSED, VALUE content)
{
    VALUE info_obj;
    Image *images;
    ImageInfo *info;
    char *image_data;
    size_t x, image_data_l;
    unsigned char *blob;
    size_t blob_l;
    ExceptionInfo *exception;

    image_data = rm_str2cstr(content, &image_data_l);

    // Search for a comma. If found, we'll set the start of the
    // image data just following the comma. Otherwise we'll assume
    // the image data starts with the first byte.
    for (x = 0; x < image_data_l; x++)
    {
        if (image_data[x] == ',')
        {
            break;
        }
    }
    if (x < image_data_l)
    {
        image_data += x + 1;
    }

    GVL_STRUCT_TYPE(Base64Decode) args_Base64Decode = { image_data, &blob_l };
    blob = (unsigned char *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(Base64Decode), &args_Base64Decode);
    if (blob_l == 0)
    {
        rb_raise(rb_eArgError, "can't decode image");
    }

    exception = AcquireExceptionInfo();

    // Create a new Info structure for this read. About the
    // only useful attribute that can be set is `format'.
    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

    GVL_STRUCT_TYPE(BlobToImage) args_BlobToImage = { info, blob, blob_l, exception };
    images = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlobToImage), &args_BlobToImage);
    magick_free((void *)blob);

    rm_check_exception(exception, images, DestroyOnError);
    DestroyExceptionInfo(exception);

    rm_set_user_artifact(images, info);
    rm_sync_image_options(images, info);

    RB_GC_GUARD(info_obj);

    return array_from_images(images);
}

Instance Method Details

#<=>(other) ⇒ -1, ...

Compare two images.

Parameters:

• other (Object) —

  other image

Returns:

• (-1, 0, 1, nil) —

  the result of compare

# File 'ext/RMagick/rmimage.cpp', line 13389

VALUE
Image_spaceship(VALUE self, VALUE other)
{
    Image *imageA, *imageB;
    const char *sigA, *sigB;
    int res;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    imageA = rm_check_destroyed(self);

    // If the other object isn't a Image object, then they can't be equal.
    if (!rb_obj_is_kind_of(other, Class_Image))
    {
        return Qnil;
    }

    imageB = rm_check_destroyed(other);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SignatureImage) args1 = { imageA, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args1);
    CHECK_EXCEPTION();
    GVL_STRUCT_TYPE(SignatureImage) args2 = { imageB, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args2);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SignatureImage) args1 = { imageA };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args1);
    GVL_STRUCT_TYPE(SignatureImage) args2 = { imageB };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args2);
#endif
    sigA = rm_get_property(imageA, "signature");
    sigB = rm_get_property(imageB, "signature");
    if (!sigA || !sigB)
    {
        rb_raise(Class_ImageMagickError, "can't get image signature");
    }

    res = memcmp(sigA, sigB, 64);
    res = res > 0 ? 1 : (res < 0 ? -1 :  0);    // reduce to 1, -1, 0

    return INT2FIX(res);
}

#[](key_arg) ⇒ String^?

Returns the value of the image property identified by key. An image may have any number of properties.

Each property is identified by a string (or symbol) key. The property value is a string. ImageMagick predefines some properties, including "Label", "Comment", "Signature", and in some cases "EXIF".

Parameters:

• key_arg (String, Symbol) —

  the key to get

Returns:

• (String, nil) —

  property value or nil if key doesn't exist

See Also:

• #[]=
• #properties

# File 'ext/RMagick/rmimage.cpp', line 962

VALUE
 Image_aref(VALUE self, VALUE key_arg)
{
    Image *image;
    const char *key;
    const char *attr;

    image = rm_check_destroyed(self);

    switch (TYPE(key_arg))
    {
        case T_NIL:
            return Qnil;

        case T_SYMBOL:
            key = rb_id2name((ID)SYM2ID(key_arg));
            break;

        default:
            key = StringValueCStr(key_arg);
            if (*key == '\0')
            {
                return Qnil;
            }
            break;
    }


    if (rm_strcasecmp(key, "EXIF:*") == 0)
    {
        return rm_exif_by_entry(image);
    }
    else if (rm_strcasecmp(key, "EXIF:!") == 0)
    {
        return rm_exif_by_number(image);
    }

    attr = rm_get_property(image, key);
    return attr ? rb_str_new2(attr) : Qnil;
}

#[]=(key_arg, attr_arg) ⇒ Magick::Image

Sets the value of an image property. An image may have any number of properties.

• Specify attr=nil to remove the key from the list.
• SetImageProperty normally APPENDS the new value to any existing value. Since this usage is tremendously counter-intuitive, this function always deletes the existing value before setting the new value.
• There's no use checking the return value since SetImageProperty returns "False" for many reasons, some legitimate.

Parameters:

• key_arg (String, Symbol) —

  the key to set

• attr_arg (String) —

  the value to which to set it

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 1017

VALUE
Image_aset(VALUE self, VALUE key_arg, VALUE attr_arg)
{
    Image *image;
    const char *key;
    char *attr;
    unsigned int okay;

    image = rm_check_frozen(self);

    attr = attr_arg == Qnil ? NULL : StringValueCStr(attr_arg);

    switch (TYPE(key_arg))
    {
        case T_NIL:
            return self;

        case T_SYMBOL:
            key = rb_id2name((ID)SYM2ID(key_arg));
            break;

        default:
            key = StringValueCStr(key_arg);
            if (*key == '\0')
            {
                return self;
            }
            break;
    }


    // Delete existing value. SetImageProperty returns False if
    // the attribute doesn't exist - we don't care.
    rm_set_property(image, key, NULL);
    // Set new value
    if (attr)
    {
        okay = rm_set_property(image, key, attr);
        if (!okay)
        {
            rb_warning("SetImageProperty failed (probably out of memory)");
        }
    }
    return self;
}

#_dump(depth) ⇒ String

Implement marshalling.

Parameters:

• depth (Object) —

  unused

Returns:

• (String) —

  a string representing the dumped image

# File 'ext/RMagick/rmimage.cpp', line 6085

VALUE
Image__dump(VALUE self, VALUE depth ATTRIBUTE_UNUSED)
{
    Image *image;
    ImageInfo *info;
    void *blob;
    size_t length;
    DumpedImage mi;
    VALUE str;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    info = CloneImageInfo(NULL);
    if (!info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }
    strlcpy(info->magick, image->magick, sizeof(info->magick));

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ImageToBlob) args = { info, image, &length, exception };
    blob = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImageToBlob), &args);

    // Free ImageInfo first - error handling may raise an exception
    DestroyImageInfo(info);

    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    if (!blob)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }

    // Create a header for the blob: ID and version
    // numbers, followed by the length of the magick
    // string stored as a byte, followed by the
    // magick string itself.
    mi.id = DUMPED_IMAGE_ID;
    mi.mj = DUMPED_IMAGE_MAJOR_VERS;
    mi.mi = DUMPED_IMAGE_MINOR_VERS;
    strlcpy(mi.magick, image->magick, sizeof(mi.magick));
    mi.len = (unsigned char) min((size_t)UCHAR_MAX, rm_strnlen_s(mi.magick, sizeof(mi.magick)));

    // Concatenate the blob onto the header & return the result
    str = rb_str_new((char *)&mi, (long)(mi.len+offsetof(DumpedImage, magick)));
    str = rb_str_buf_cat(str, (char *)blob, (long)length);
    magick_free((void*)blob);

    RB_GC_GUARD(str);

    return str;
}

#adaptive_blur(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Adaptively blurs the image by blurring more intensely near image edges and less intensely far from edges. The #adaptive_blur method blurs the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and adaptive_blur selects a suitable radius for you.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian in pixels, not counting the center pixel.

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation of the Laplacian, in pixels.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 439

VALUE
Image_adaptive_blur(int argc, VALUE *argv, VALUE self)
{
    return adaptive_method(argc, argv, self, GVL_FUNC(AdaptiveBlurImage));
}

#adaptive_blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #adaptive_blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

The same as #adaptive_blur except only the specified channels are blurred.

Overloads:

• #adaptive_blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian in pixels, not counting the center pixel.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Laplacian, in pixels.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #adaptive_blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian in pixels, not counting the center pixel.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Laplacian, in pixels.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 461

VALUE
Image_adaptive_blur_channel(int argc, VALUE *argv, VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return adaptive_channel_method(argc, argv, self, GVL_FUNC(AdaptiveBlurImage));
#else
    return adaptive_channel_method(argc, argv, self, GVL_FUNC(AdaptiveBlurImageChannel));
#endif
}

#adaptive_resize(scale_val) ⇒ Magick::Image #adaptive_resize(cols, rows) ⇒ Magick::Image

Resizes the image with data dependent triangulation.

Overloads:

• #adaptive_resize(scale_val) ⇒ Magick::Image

  Parameters:

  • scale_val (Numeric) —

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

• #adaptive_resize(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired column size

  • rows (Numeric) —

    The desired row size.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 486

VALUE
Image_adaptive_resize(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    unsigned long rows, columns;
    double scale_val, drows, dcols;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 2:
            rows = NUM2ULONG(argv[1]);
            columns = NUM2ULONG(argv[0]);
            break;
        case 1:
            scale_val = NUM2DBL(argv[0]);
            if (scale_val < 0.0)
            {
                rb_raise(rb_eArgError, "invalid scale_val value (%g given)", scale_val);
            }
            drows = scale_val * image->rows + 0.5;
            dcols = scale_val * image->columns + 0.5;
            if (drows > (double)ULONG_MAX || dcols > (double)ULONG_MAX)
            {
                rb_raise(rb_eRangeError, "resized image too big");
            }
            rows = (unsigned long) drows;
            columns = (unsigned long) dcols;
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or 2)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(AdaptiveResizeImage) args = { image, columns, rows, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AdaptiveResizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#adaptive_sharpen(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Adaptively sharpens the image by sharpening more intensely near image edges and less intensely far from edges.

The #adaptive_sharpen method sharpens the image with a Gaussian operator of the given radius and standard deviation (sigma).

For reasonable results, radius should be larger than sigma. Use a radius of 0 and adaptive_sharpen selects a suitable radius for you.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian in pixels, not counting the center pixel.

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation of the Laplacian, in pixels.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 547

VALUE
Image_adaptive_sharpen(int argc, VALUE *argv, VALUE self)
{
    return adaptive_method(argc, argv, self, GVL_FUNC(AdaptiveSharpenImage));
}

#adaptive_sharpen_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #adaptive_sharpen_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

The same as #adaptive_sharpen except only the specified channels are sharpened.

Overloads:

• #adaptive_sharpen_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian in pixels, not counting the center pixel.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Laplacian, in pixels.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #adaptive_sharpen_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian in pixels, not counting the center pixel.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Laplacian, in pixels.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 569

VALUE
Image_adaptive_sharpen_channel(int argc, VALUE *argv, VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return adaptive_channel_method(argc, argv, self, GVL_FUNC(AdaptiveSharpenImage));
#else
    return adaptive_channel_method(argc, argv, self, GVL_FUNC(AdaptiveSharpenImageChannel));
#endif
}

#adaptive_threshold(width = 3, height = 3, bias = 0) ⇒ Magick::Image

Selects an individual threshold for each pixel based on the range of intensity values in its local neighborhood. This allows for thresholding of an image whose global intensity histogram doesn't contain distinctive peaks.

Returns a new image.

Parameters:

• width (Numeric) (defaults to: 3) —

  the width of the local neighborhood.

• height (Numeric) (defaults to: 3) —

  the height of the local neighborhood.

• bias (Numeric) (defaults to: 0) —

  the mean offset

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 591

VALUE
Image_adaptive_threshold(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    unsigned long width = 3, height = 3;
    double bias = 0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 3:
            bias = NUM2DBL(argv[2]);
        case 2:
            height = NUM2ULONG(argv[1]);
        case 1:
            width  = NUM2ULONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 3)", argc);
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(AdaptiveThresholdImage) args = { image, width, height, bias, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AdaptiveThresholdImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#add_compose_mask(mask) ⇒ Object

Associates a mask with an image that will be used as the destination image in a #composite operation.

The areas of the destination image that are masked by white pixels will be modified by the #composite method, while areas masked by black pixels are unchanged.

Parameters:

• mask (Magick::Image, Magick::ImageList) —

  the composite mask

See Also:

• #mask
• #delete_compose_mask

# File 'ext/RMagick/rmimage.cpp', line 636

VALUE
Image_add_compose_mask(VALUE self, VALUE mask)
{
    Image *image, *mask_image = NULL;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
    Image *clip_mask = NULL;
#endif

    image = rm_check_frozen(self);
    mask_image = rm_check_destroyed(rm_cur_image(mask));
    if (image->columns != mask_image->columns || image->rows != mask_image->rows)
    {
        rb_raise(rb_eArgError, "mask must be the same size as image");
    }

#if defined(IMAGEMAGICK_7)
    clip_mask = rm_clone_image(mask_image);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(NegateImage) args_NegateImage = { clip_mask, MagickFalse, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImage), &args_NegateImage);
    rm_check_exception(exception, clip_mask, DestroyOnError);
    GVL_STRUCT_TYPE(SetImageMask) args_SetImageMask = { image, CompositePixelMask, clip_mask, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageMask), &args_SetImageMask);
    DestroyImage(clip_mask);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    // Delete any previously-existing mask image.
    // Store a clone of the new mask image.
    GVL_STRUCT_TYPE(SetImageMask) args_SetImageMask = { image, mask_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageMask), &args_SetImageMask);
    GVL_STRUCT_TYPE(NegateImage) args_NegateImage = { image->mask, MagickFalse };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImage), &args_NegateImage);

    // Since both Set and GetImageMask clone the mask image I don't see any
    // way to negate the mask without referencing it directly. Sigh.
#endif

    return self;
}

#add_noise(noise) ⇒ Magick::Image

Adds random noise to the image.

Parameters:

• noise (Magick::NoiseType) —

  the noise

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 686

VALUE
Image_add_noise(VALUE self, VALUE noise)
{
    Image *image, *new_image;
    NoiseType noise_type;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    VALUE_TO_ENUM(noise, noise_type, NoiseType);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(AddNoiseImage) args = { image, noise_type, 1.0, exception };
#else
    GVL_STRUCT_TYPE(AddNoiseImage) args = { image, noise_type, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AddNoiseImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#add_noise_channel(noise_type, channel = Magick::AllChannels) ⇒ Magick::Image #add_noise_channel(noise_type, *channels) ⇒ Magick::Image

Adds random noise to the specified channel or channels in the image.

Overloads:

• #add_noise_channel(noise_type, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • noise (Magick::NoiseType) —

    the noise

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #add_noise_channel(noise_type, *channels) ⇒ Magick::Image

  Parameters:

  • noise (Magick::NoiseType) —

    the noise

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 723

VALUE
Image_add_noise_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    NoiseType noise_type;
    ExceptionInfo *exception;
    ChannelType channels;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There must be 1 remaining argument.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "missing noise type argument");
    }
    else if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    VALUE_TO_ENUM(argv[0], noise_type, NoiseType);
    channels = (ChannelType)(channels & ~OpacityChannel);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(AddNoiseImage) args = { image, noise_type, 1.0, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AddNoiseImage), &args);
    END_CHANNEL_MASK(new_image);
#else
    GVL_STRUCT_TYPE(AddNoiseImageChannel) args = { image, channels, noise_type, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AddNoiseImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#add_profile(name) ⇒ Magick::Image

Adds an ICC (a.k.a. ICM), IPTC, or generic profile. If the file contains more than one profile all the profiles are added.

Parameters:

• name (String) —

  The filename of a file containing the profile.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 771

VALUE
Image_add_profile(VALUE self, VALUE name)
{
    // ImageMagick code based on the code for the "-profile" option in mogrify.c
    Image *image, *profile_image;
    ImageInfo *info;
    ExceptionInfo *exception;
    char *profile_name;
    char *profile_filename = NULL;
    const StringInfo *profile;

    image = rm_check_frozen(self);

    // ProfileImage issues a warning if something goes wrong.
    profile_filename = StringValueCStr(name);

    info = CloneImageInfo(NULL);
    if (!info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }
    profile = GetImageProfile(image, "iptc");
    if (profile)
    {
        info->profile = (void *)CloneStringInfo(profile);
    }
    strlcpy(info->filename, profile_filename, sizeof(info->filename));

    exception = AcquireExceptionInfo();
    profile_image = ReadImage(info, exception);
    DestroyImageInfo(info);
    rm_check_exception(exception, profile_image, DestroyOnError);
    rm_ensure_result(profile_image);

    ResetImageProfileIterator(profile_image);
    profile_name = GetNextImageProfile(profile_image);
    while (profile_name)
    {
        profile = GetImageProfile(profile_image, profile_name);
        if (profile)
        {
#if defined(IMAGEMAGICK_7)
            GVL_STRUCT_TYPE(ProfileImage) args = { image, profile_name, GetStringInfoDatum(profile), GetStringInfoLength(profile), exception };
            CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ProfileImage), &args);
            if (rm_should_raise_exception(exception, RetainExceptionRetention))
#else
            GVL_STRUCT_TYPE(ProfileImage) args = { image, profile_name, GetStringInfoDatum(profile), GetStringInfoLength(profile), MagickFalse };
            CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ProfileImage), &args);
            if (rm_should_raise_exception(&image->exception, RetainExceptionRetention))
#endif
            {
                break;
            }
        }
        profile_name = GetNextImageProfile(profile_image);
    }

    DestroyImage(profile_image);
#if defined(IMAGEMAGICK_7)
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    DestroyExceptionInfo(exception);
    rm_check_image_exception(image, RetainOnError);
#endif

    return self;
}

#affine_transform(affine) ⇒ Magick::Image

Transform an image as dictated by the affine matrix argument.

Parameters:

• affine (Magick::AffineMatrix) —

  the affine matrix

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 927

VALUE
Image_affine_transform(VALUE self, VALUE affine)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    AffineMatrix matrix;

    image = rm_check_destroyed(self);

    // Convert Magick::AffineMatrix to AffineMatrix structure.
    Export_AffineMatrix(&matrix, affine);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(AffineTransformImage) args = { image, &matrix, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(AffineTransformImage), &args);
    new_image = reinterpret_cast<decltype(new_image)>(ret);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#alpha ⇒ Boolean #alpha(value) ⇒ Magick::AlphaChannelOption

Get/Set alpha channel.

• Replaces #matte=, #alpha=
• Originally there was an alpha attribute getter and setter. These are replaced with alpha? and alpha(type). We still define (but don't document) alpha=. For backward compatibility, if this method is called without an argument, make it act like the old alpha getter and return true if the matte channel is active, false otherwise.

Overloads:

• #alpha ⇒ Boolean

  Returns true if the alpha channel will be used, false otherwise. This calling is same as #alpha?.

  Returns:

  • (Boolean) —

    true or false

  See Also:

  • #alpha?
• #alpha(value) ⇒ Magick::AlphaChannelOption

  Activates, deactivates, resets, or sets the alpha channel.

  Parameters:

  • value (Magick::AlphaChannelOption) —

    An AlphaChannelOption value

  Returns:

  • (Magick::AlphaChannelOption) —

    the given value

# File 'ext/RMagick/rmimage.cpp', line 863

VALUE
Image_alpha(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    AlphaChannelOption alpha;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif


    // For backward compatibility, make alpha() act like alpha?
    if (argc == 0)
    {
        return Image_alpha_q(self);
    }
    else if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 1)", argc);
    }


    image = rm_check_frozen(self);
    VALUE_TO_ENUM(argv[0], alpha, AlphaChannelOption);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageAlphaChannel) args = { image, alpha, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageAlphaChannel), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageAlphaChannel) args = { image, alpha };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageAlphaChannel), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return argv[0];
}

#alpha? ⇒ Boolean

Determine whether the image's alpha channel is activated.

Returns:

• (Boolean) —

  true if the image's alpha channel is activated

# File 'ext/RMagick/rmimage.cpp', line 909

VALUE
Image_alpha_q(VALUE self)
{
    Image *image = rm_check_destroyed(self);
#if defined(IMAGEMAGICK_7)
    return image->alpha_trait == BlendPixelTrait ? Qtrue : Qfalse;
#else
    return GetImageAlphaChannel(image) ? Qtrue : Qfalse;
#endif
}

#annotate(draw, width, height, x, y, text) ⇒ Object

Provide an alternate version of Draw#annotate, for folks who want to find it in this class.

# File 'lib/rmagick_internal.rb', line 771

def annotate(draw, width, height, x, y, text, &)
  check_destroyed
  draw.annotate(self, width, height, x, y, text, &)
  self
end

#auto_gamma_channel(channel = Magick::AllChannels) ⇒ Magick::Image #auto_gamma_channel(*channels) ⇒ Magick::Image

"Automagically" adjust the gamma level of an image.

Overloads:

• #auto_gamma_channel(channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #auto_gamma_channel(*channels) ⇒ Magick::Image

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 1171

VALUE
Image_auto_gamma_channel(int argc, VALUE *argv, VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return auto_channel(argc, argv, self, GVL_FUNC(AutoGammaImage));
#else
    return auto_channel(argc, argv, self, GVL_FUNC(AutoGammaImageChannel));
#endif
}

#auto_level_channel(channel = Magick::AllChannels) ⇒ Magick::Image #auto_level_channel(*channels) ⇒ Magick::Image

"Automagically" adjust the color levels of an image.

Overloads:

• #auto_level_channel(channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #auto_level_channel(*channels) ⇒ Magick::Image

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 1193

VALUE
Image_auto_level_channel(int argc, VALUE *argv, VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return auto_channel(argc, argv, self, GVL_FUNC(AutoLevelImage));
#else
    return auto_channel(argc, argv, self, GVL_FUNC(AutoLevelImageChannel));
#endif
}

#auto_orient ⇒ Magick::Image

Rotates or flips the image based on the image's EXIF orientation tag.

Note that only some models of modern digital cameras can tag an image with the orientation. If the image does not have an orientation tag, or the image is already properly oriented, then #auto_orient returns an exact copy of the image.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #auto_orient!

# File 'ext/RMagick/rmimage.cpp', line 1282

VALUE
Image_auto_orient(VALUE self)
{
    rm_check_destroyed(self);
    return auto_orient(False, self);
}

#auto_orient! ⇒ Magick::Image^?

Rotates or flips the image based on the image's EXIF orientation tag. Note that only some models of modern digital cameras can tag an image with the orientation. If the image does not have an orientation tag, or the image is already properly oriented, then #auto_orient! returns nil.

Returns:

• (Magick::Image, nil) —

  nil if the image is already properly oriented, otherwise self

See Also:

• #auto_orient

# File 'ext/RMagick/rmimage.cpp', line 1299

VALUE
Image_auto_orient_bang(VALUE self)
{
    rm_check_frozen(self);
    return auto_orient(True, self);
}

#background_color ⇒ String

Return the name of the background color as a String.

Returns:

• (String) —

  the background color

# File 'ext/RMagick/rmimage.cpp', line 1312

VALUE
Image_background_color(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return rm_pixelcolor_to_color_name(image, &image->background_color);
}

#background_color=(color) ⇒ Magick::Pixel, String

Set the the background color to the specified color spec.

Parameters:

• color (Magick::Pixel, String) —

  the color

Returns:

• (Magick::Pixel, String) —

  the given color

# File 'ext/RMagick/rmimage.cpp', line 1326

VALUE
Image_background_color_eq(VALUE self, VALUE color)
{
    Image *image = rm_check_frozen(self);
    Color_to_PixelColor(&image->background_color, color);
    return color;
}

#base_columns ⇒ Integer

Return the number of rows (before transformations).

Returns:

• (Integer) —

  the number of rows

# File 'ext/RMagick/rmimage.cpp', line 1340

VALUE
Image_base_columns(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return INT2FIX(image->magick_columns);
}

#base_filename ⇒ String

Return the image filename (before transformations).

Returns:

• (String) —

  the base image filename (or the current filename if there is no base)

# File 'ext/RMagick/rmimage.cpp', line 1352

VALUE
Image_base_filename(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    if (*image->magick_filename)
    {
        return rb_str_new2(image->magick_filename);
    }
    else
    {
        return rb_str_new2(image->filename);
    }
}

#base_rows ⇒ Integer

Return the number of rows (before transformations).

Returns:

• (Integer) —

  the number of rows

# File 'ext/RMagick/rmimage.cpp', line 1371

VALUE
Image_base_rows(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return INT2FIX(image->magick_rows);
}

#bias ⇒ Float

Get image bias (used when convolving an image).

Returns:

• (Float) —

  the image bias

# File 'ext/RMagick/rmimage.cpp', line 1384

VALUE
Image_bias(VALUE self)
{
    Image *image;
    double bias = 0.0;

    image = rm_check_destroyed(self);
#if defined(IMAGEMAGICK_7)
    {
        const char *artifact = GetImageArtifact(image, "convolve:bias");
        if (artifact != (const char *) NULL)
        {
            char *q;

            bias = InterpretLocaleValue(artifact, &q);
            if (*q == '%')
            {
                bias *= ((double) QuantumRange + 1.0) / 100.0;
            }
        }
    }
#else
    bias = image->bias;
#endif
    return rb_float_new(bias);
}

#bias=(pct) ⇒ Numeric, String

Set image bias (used when convolving an image).

Parameters:

• pct (Numeric, String) —

  Either a number between 0.0 and 1.0 or a string in the form "NN%"

Returns:

• (Numeric, String) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 1418

VALUE
Image_bias_eq(VALUE self, VALUE pct)
{
    Image *image;
    double bias;

    image = rm_check_frozen(self);
    bias = rm_percentage(pct, 1.0) * QuantumRange;

#if defined(IMAGEMAGICK_7)
    {
        char artifact[21];

        snprintf(artifact, sizeof(artifact), "%.20g", bias);
        SetImageArtifact(image, "convolve:bias", artifact);
    }
#else
    image->bias = bias;
#endif

    return pct;
}

#bilevel_channel(threshold, channel = Magick::AllChannels) ⇒ Magick::Image #bilevel_channel(threshold, *channels) ⇒ Magick::Image

Changes the value of individual pixels based on the intensity of each pixel channel. The result is a high-contrast image.

Overloads:

• #bilevel_channel(threshold, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • threshold (Numeric) —

    The threshold value, a number between 0 and QuantumRange.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #bilevel_channel(threshold, *channels) ⇒ Magick::Image

  Parameters:

  • threshold (Numeric) —

    The threshold value, a number between 0 and QuantumRange.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 1455

VALUE
Image_bilevel_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    double threshold;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "no threshold specified");
    }

    threshold = NUM2DBL(argv[0]);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(BilevelImage) args = { new_image, threshold, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BilevelImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(BilevelImageChannel) args = { new_image, channels, threshold };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BilevelImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#black_point_compensation ⇒ Boolean

Return current black point compensation attribute.

Returns:

• (Boolean) —

  true or false

# File 'ext/RMagick/rmimage.cpp', line 1503

VALUE
Image_black_point_compensation(VALUE self)
{
    Image *image;
    const char *attr;
    VALUE value;

    image = rm_check_destroyed(self);

    attr = rm_get_property(image, BlackPointCompensationKey);
    if (attr && rm_strcasecmp(attr, "true") == 0)
    {
        value = Qtrue;
    }
    else
    {
        value = Qfalse;
    }

    RB_GC_GUARD(value);

    return value;
}

#black_point_compensation=(arg) ⇒ Boolean

Set black point compensation attribute.

Parameters:

• arg (Boolean) —

  true or false

Returns:

• (Boolean) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 1534

VALUE
Image_black_point_compensation_eq(VALUE self, VALUE arg)
{
    Image *image;
    const char *value;

    image = rm_check_frozen(self);
    rm_set_property(image, BlackPointCompensationKey, NULL);
    value = RTEST(arg) ? "true" : "false";
    rm_set_property(image, BlackPointCompensationKey, value);

    return arg;
}

#black_threshold(red) ⇒ Numeric #black_threshold(red, green) ⇒ Numeric #black_threshold(red, green, blue) ⇒ Numeric #black_threshold(red, green, blue, alpha:) ⇒ Numeric

Forces all pixels below the threshold into black while leaving all pixels above the threshold unchanged.

Overloads:

• #black_threshold(red) ⇒ Numeric

  Parameters:

  • red (Numeric) —

    the number for red channel

• #black_threshold(red, green) ⇒ Numeric

  Parameters:

  • red (Numeric) —

    the number for red channel

  • green (Numeric) —

    the number for green channel

• #black_threshold(red, green, blue) ⇒ Numeric

  Parameters:

  • red (Numeric) —

    the number for red channel

  • green (Numeric) —

    the number for green channel

  • blue (Numeric) —

    the number for blue channel

• #black_threshold(red, green, blue, alpha:) ⇒ Numeric

  Parameters:

  • red (Numeric) —

    the number for red channel

  • green (Numeric) —

    the number for green channel

  • blue (Numeric) —

    the number for blue channel

  • alpha (Numeric) —

    the number for alpha channel

Returns:

• (Numeric) —

  a new image

See Also:

• #white_threshold

# File 'ext/RMagick/rmimage.cpp', line 1574

VALUE
Image_black_threshold(int argc, VALUE *argv, VALUE self)
{
    return threshold_image(argc, argv, self, GVL_FUNC(BlackThresholdImage));
}

#blend(overlay, src_percent, dst_percent, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

Adds the overlay image to the target image according to src_percent and dst_percent.

• The default value for dst_percent is 100%-src_percent

Returns a new image.

Parameters:

• overlay (Magick::Image, Magick::ImageList) —

  The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.

• src_percent (Numeric, String) —

  Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.

• dst_percent (Numeric, String) —

  Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no other arguments follow it. In this case the default is 100%-src_percentage.

• gravity (Magick::GravityType) (defaults to: Magick::NorthWestGravity) —

  the gravity for offset. the offsets are measured from the NorthWest corner by default.

• x_offset (Numeric) (defaults to: 0) —

  The offset that measured from the left-hand side of the target image.

• y_offset (Numeric) (defaults to: 0) —

  The offset that measured from the top of the target image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 1922

VALUE
Image_blend(int argc, VALUE *argv, VALUE self)
{
    VALUE ovly;
    Image *image, *overlay;
    double src_percent, dst_percent;
    long x_offset = 0L, y_offset = 0L;

    image = rm_check_destroyed(self);

    if (argc < 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 6)", argc);
    }

    ovly = rm_cur_image(argv[0]);
    overlay = rm_check_destroyed(ovly);

    if (argc > 3)
    {
        get_composite_offsets(argc-3, &argv[3], image, overlay, &x_offset, &y_offset);
        // There must be 3 arguments left
        argc = 3;
    }

    switch (argc)
    {
        case 3:
            dst_percent = rm_percentage(argv[2], 1.0) * 100.0;
            src_percent = rm_percentage(argv[1], 1.0) * 100.0;
            break;
        case 2:
            src_percent = rm_percentage(argv[1], 1.0) * 100.0;
            dst_percent = FMAX(100.0 - src_percent, 0);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 6)", argc);
            break;
    }

    RB_GC_GUARD(ovly);

    return special_composite(image, overlay, src_percent, dst_percent,
                             x_offset, y_offset, BlendCompositeOp);

}

#blue_shift(factor = 1.5) ⇒ Magick::Image

Simulate a scene at nighttime in the moonlight.

Returns a new image.

Parameters:

• factor (Numeric) (defaults to: 1.5) —

  Larger values increase the effect.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 1978

VALUE
Image_blue_shift(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double factor = 1.5;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 1:
            factor = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }


    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(BlueShiftImage) args = { image, factor, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlueShiftImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

Blurs the specified channel. Convolves the image with a Gaussian operator of the given radius and standard deviation (sigma).

Overloads:

• #blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    the radius value

  • sigma (Numeric) (defaults to: 1.0) —

    the sigma value

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    the radius value

  • sigma (Numeric) (defaults to: 1.0) —

    the sigma value

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2025

VALUE
Image_blur_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    ChannelType channels;
    double radius = 0.0, sigma = 1.0;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // There can be 0, 1, or 2 remaining arguments.
    switch (argc)
    {
        case 2:
            sigma = NUM2DBL(argv[1]);
        case 1:
            radius = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(BlurImage) args = { image, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlurImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(BlurImageChannel) args = { image, channels, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlurImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#blur_image(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Blur the image.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  the radius value

• sigma (Numeric) (defaults to: 1.0) —

  the sigma value

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2076

VALUE
Image_blur_image(int argc, VALUE *argv, VALUE self)
{
    return effect_image(self, argc, argv, GVL_FUNC(BlurImage));
}

#border(width, height, color) ⇒ Magick::Image

Surrounds the image with a border of the specified width, height, and named color.

Parameters:

• width (Numeric) —

  the width of the border

• height (Numeric) —

  the height of the border

• color (Magick::Pixel, String) —

  the color of the border

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2163

VALUE
Image_border(VALUE self, VALUE width, VALUE height, VALUE color)
{
    rm_check_destroyed(self);
    return border(False, self, width, height, color);
}

#border!(width, height, color) ⇒ Object

Surrounds the image with a border of the specified width, height, and named color. In-place form of #border.

Parameters:

• width (Numeric) —

  the width of the border

• height (Numeric) —

  the height of the border

• color (Magick::Pixel, String) —

  the color of the border

# File 'ext/RMagick/rmimage.cpp', line 2147

VALUE
Image_border_bang(VALUE self, VALUE width, VALUE height, VALUE color)
{
    rm_check_frozen(self);
    return border(True, self, width, height, color);
}

#border_color ⇒ String

Return the name of the border color as a String.

Returns:

• (String) —

  the name of the border color

# File 'ext/RMagick/rmimage.cpp', line 2176

VALUE
Image_border_color(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return rm_pixelcolor_to_color_name(image, &image->border_color);
}

#border_color=(color) ⇒ Magick::Pixel, String

Set the the border color.

Parameters:

• color (Magick::Pixel, String) —

  the color

Returns:

• (Magick::Pixel, String) —

  the given color

# File 'ext/RMagick/rmimage.cpp', line 2190

VALUE
Image_border_color_eq(VALUE self, VALUE color)
{
    Image *image = rm_check_frozen(self);
    Color_to_PixelColor(&image->border_color, color);
    return color;
}

#bounding_box ⇒ Magick::Rectangle

Returns the bounding box of an image canvas.

Returns:

• (Magick::Rectangle) —

  the bounding box

# File 'ext/RMagick/rmimage.cpp', line 2204

VALUE
Image_bounding_box(VALUE self)
{
    Image *image;
    RectangleInfo box;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();
    box = GetImageBoundingBox(image, exception);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return Import_RectangleInfo(&box);
}

#change_geometry(geom_arg) {|column, row, image| ... } ⇒ Object

Note:

#change_geometry! is an alias for #change_geometry.

This method supports resizing a method by specifying constraints. For example, you can specify that the image should be resized such that the aspect ratio should be retained but the resulting image should be no larger than 640 pixels wide and 480 pixels tall.

Examples:

image.change_geometry!('320x240') { |cols, rows, img|
  img.resize!(cols, rows)
}

Parameters:

• geom_arg (Magick::Geometry, String) —

  the geometry

Yields:

• (column, row, image)

Yield Parameters:

• column (Integer) —

  The desired column size

• row (Integer) —

  The desired row size

• image (Magick::Image) —

  self

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 2338

VALUE
Image_change_geometry(VALUE self, VALUE geom_arg)
{
    Image *image;
    RectangleInfo rect;
    VALUE geom_str;
    char *geometry;
    unsigned int flags;
    VALUE ary;

    image = rm_check_destroyed(self);
    geom_str = rb_String(geom_arg);
    geometry = StringValueCStr(geom_str);

    memset(&rect, 0, sizeof(rect));

    SetGeometry(image, &rect);
    flags = ParseMetaGeometry(geometry, &rect.x, &rect.y, &rect.width, &rect.height);
    if (flags == NoValue)
    {
        rb_raise(rb_eArgError, "invalid geometry string `%s'", geometry);
    }

    ary = rb_ary_new2(3);
    rb_ary_store(ary, 0, ULONG2NUM(rect.width));
    rb_ary_store(ary, 1, ULONG2NUM(rect.height));
    rb_ary_store(ary, 2, self);

    RB_GC_GUARD(geom_str);
    RB_GC_GUARD(ary);

    return rb_yield(ary);
}

#change_geometry!(geom_arg) {|column, row, image| ... } ⇒ Object

Note:

#change_geometry! is an alias for #change_geometry.

This method supports resizing a method by specifying constraints. For example, you can specify that the image should be resized such that the aspect ratio should be retained but the resulting image should be no larger than 640 pixels wide and 480 pixels tall.

Examples:

image.change_geometry!('320x240') { |cols, rows, img|
  img.resize!(cols, rows)
}

Parameters:

• geom_arg (Magick::Geometry, String) —

  the geometry

Yields:

• (column, row, image)

Yield Parameters:

• column (Integer) —

  The desired column size

• row (Integer) —

  The desired row size

• image (Magick::Image) —

  self

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 2338

VALUE
Image_change_geometry(VALUE self, VALUE geom_arg)
{
    Image *image;
    RectangleInfo rect;
    VALUE geom_str;
    char *geometry;
    unsigned int flags;
    VALUE ary;

    image = rm_check_destroyed(self);
    geom_str = rb_String(geom_arg);
    geometry = StringValueCStr(geom_str);

    memset(&rect, 0, sizeof(rect));

    SetGeometry(image, &rect);
    flags = ParseMetaGeometry(geometry, &rect.x, &rect.y, &rect.width, &rect.height);
    if (flags == NoValue)
    {
        rb_raise(rb_eArgError, "invalid geometry string `%s'", geometry);
    }

    ary = rb_ary_new2(3);
    rb_ary_store(ary, 0, ULONG2NUM(rect.width));
    rb_ary_store(ary, 1, ULONG2NUM(rect.height));
    rb_ary_store(ary, 2, self);

    RB_GC_GUARD(geom_str);
    RB_GC_GUARD(ary);

    return rb_yield(ary);
}

#changed? ⇒ Boolean

Return true if any pixel in the image has been altered since the image was constituted.

Returns:

• (Boolean) —

  true if altered, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 2378

VALUE
Image_changed_q(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    VALUE okay = IsTaintImage(image) ? Qtrue : Qfalse;
    return okay;
}

#channel(channel_arg) ⇒ Magick::Image

Extract a channel from the image. A channel is a particular color component of each pixel in the image.

Parameters:

• channel_arg (Magick::ChannelType) —

  the type of the channel to extract

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2394

VALUE
Image_channel(VALUE self, VALUE channel_arg)
{
    Image *image, *new_image;
    ChannelType channel;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    VALUE_TO_ENUM(channel_arg, channel, ChannelType);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SeparateImage) args = { image, channel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SeparateImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    new_image = rm_clone_image(image);
    GVL_STRUCT_TYPE(SeparateImageChannel) args = { new_image, channel };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SeparateImageChannel), &args);

    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#compare_channel(image, metric, channel = Magick::AllChannels) ⇒ Array #compare_channel(image, metric, channel = Magick::AllChannels) {|opt_args| ... } ⇒ Array #compare_channel(image, metric, *channels) ⇒ Array #compare_channel(image, metric, *channels) {|opt_args| ... } ⇒ Array

Compare one or more channels in two images and returns the specified distortion metric and a comparison image.

Overloads:

• #compare_channel(image, metric, channel = Magick::AllChannels) ⇒ Array

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #compare_channel(image, metric, channel = Magick::AllChannels) {|opt_args| ... } ⇒ Array

  When a block is given, compare_channel yields with a block argument you can optionally use to set attributes.

  • options.highlight_color = color
    • Emphasize pixel differences with this color. The default is partially transparent red.
  • options.lowlight_color = color
    • Demphasize pixel differences with this color. The default is partially transparent white.

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

  Yields:

  • (opt_args)

  Yield Parameters:

  • opt_args (Magick::OptionalMethodArguments)
• #compare_channel(image, metric, *channels) ⇒ Array

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #compare_channel(image, metric, *channels) {|opt_args| ... } ⇒ Array

  When a block is given, compare_channel yields with a block argument you can optionally use to set attributes.

  • options.highlight_color = color
    • Emphasize pixel differences with this color. The default is partially transparent red.
  • options.lowlight_color = color
    • Demphasize pixel differences with this color. The default is partially transparent white.

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

  Yields:

  • (opt_args)

  Yield Parameters:

  • opt_args (Magick::OptionalMethodArguments)

Returns:

• (Array) —

  The first element is a difference image, the second is a the value of the computed distortion represented as a Float.

# File 'ext/RMagick/rmimage.cpp', line 3422

VALUE
Image_compare_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *r_image, *difference_image;
    double distortion;
    VALUE ary, ref;
    MetricType metric_type;
    ChannelType channels;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    if (argc > 2)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc != 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or more)", argc);
    }

    rm_get_optional_arguments(self);

    ref = rm_cur_image(argv[0]);
    r_image = rm_check_destroyed(ref);

    VALUE_TO_ENUM(argv[1], metric_type, MetricType);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(CompareImages) args = { image, r_image, metric_type, &distortion, exception };
    difference_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompareImages), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(CompareImageChannels) args = { image, r_image, channels, metric_type, &distortion, exception };
    difference_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompareImageChannels), &args);
#endif
    rm_check_exception(exception, difference_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(2);
    rb_ary_store(ary, 0, rm_image_new(difference_image));
    rb_ary_store(ary, 1, rb_float_new(distortion));

    RB_GC_GUARD(ary);
    RB_GC_GUARD(ref);

    return ary;
}

#channel_depth(channel = Magick::AllChannels) ⇒ Integer #channel_depth(*channels) ⇒ Integer

Returns the maximum depth for the specified channel or channels.

Overloads:

• #channel_depth(channel = Magick::AllChannels) ⇒ Integer

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #channel_depth(*channels) ⇒ Integer

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Integer) —

  the channel depth

# File 'ext/RMagick/rmimage.cpp', line 2436

VALUE
Image_channel_depth(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    ChannelType channels;
    size_t channel_depth;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // Ensure all arguments consumed.
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(GetImageDepth) args = { image, exception };
    channel_depth = (size_t)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageDepth), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(GetImageChannelDepth) args = { image, channels, exception };
    channel_depth = (size_t)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageChannelDepth), &args);
#endif
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return ULONG2NUM(channel_depth);
}

#channel_entropy(channel = Magick::AllChannels) ⇒ Array<Float> #channel_entropy(*channels) ⇒ Array<Float>

Return an array of the entropy for the channel.

Overloads:

• #channel_entropy(channel = Magick::AllChannels) ⇒ Array<Float>

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #channel_entropy(*channels) ⇒ Array<Float>

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Array<Float>) —

  The first element in the array is the average entropy of the selected channels.

# File 'ext/RMagick/rmimage.cpp', line 2592

VALUE
Image_channel_entropy(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    ChannelType channels;
    ExceptionInfo *exception;
    double entropy;
    VALUE ary;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // Ensure all arguments consumed.
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(GetImageEntropy) args = { image, &entropy, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageEntropy), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(GetImageChannelEntropy) args = { image, channels, &entropy, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageChannelEntropy), &args);
#endif
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(1);
    rb_ary_store(ary, 0, rb_float_new(entropy));

    RB_GC_GUARD(ary);

    return ary;
}

#channel_extrema(channel = Magick::AllChannels) ⇒ Array<Integer> #channel_extrema(*channels) ⇒ Array<Integer>

Returns the minimum and maximum intensity values for the specified channel or channels.

Overloads:

• #channel_extrema(channel = Magick::AllChannels) ⇒ Array<Integer>

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #channel_extrema(*channels) ⇒ Array<Integer>

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Array<Integer>) —

  The first element in the array is the minimum value. The second element is the maximum value.

# File 'ext/RMagick/rmimage.cpp', line 2484

VALUE
Image_channel_extrema(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    ChannelType channels;
    ExceptionInfo *exception;
    size_t min, max;
    VALUE ary;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // Ensure all arguments consumed.
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(GetImageExtrema) args = { image, &min, &max, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageExtrema), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(GetImageChannelExtrema) args = { image, channels, &min, &max, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageChannelExtrema), &args);
#endif
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(2);
    rb_ary_store(ary, 0, ULONG2NUM(min));
    rb_ary_store(ary, 1, ULONG2NUM(max));

    RB_GC_GUARD(ary);

    return ary;
}

#channel_mean(channel = Magick::AllChannels) ⇒ Array<Float> #channel_mean(*channels) ⇒ Array<Float>

Returns the mean and standard deviation values for the specified channel or channels.

Overloads:

• #channel_mean(channel = Magick::AllChannels) ⇒ Array<Float>

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #channel_mean(*channels) ⇒ Array<Float>

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Array<Float>) —

  The first element in the array is the mean value. The second element is the standard deviation.

# File 'ext/RMagick/rmimage.cpp', line 2539

VALUE
Image_channel_mean(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    ChannelType channels;
    ExceptionInfo *exception;
    double mean, stddev;
    VALUE ary;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // Ensure all arguments consumed.
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(GetImageMean) args = { image, &mean, &stddev, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageMean), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(GetImageChannelMean) args = { image, channels, &mean, &stddev, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageChannelMean), &args);
#endif
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(2);
    rb_ary_store(ary, 0, rb_float_new(mean));
    rb_ary_store(ary, 1, rb_float_new(stddev));

    RB_GC_GUARD(ary);

    return ary;
}

#charcoal(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Return a new image that is a copy of the input image with the edges highlighted.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the pixel neighborhood.

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation of the Gaussian, in pixels.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2642

VALUE
Image_charcoal(int argc, VALUE *argv, VALUE self)
{
    return effect_image(self, argc, argv, GVL_FUNC(CharcoalImage));
}

#check_destroyed ⇒ nil

Raises DestroyedImageError if the image has been destroyed. Returns nil otherwise.

Returns:

• (nil) —

  nil

Raises:

• (Magick::DestroyedImageError) —

  raise if the image has been destroyed

# File 'ext/RMagick/rmimage.cpp', line 2655

VALUE
Image_check_destroyed(VALUE self)
{
    rm_check_destroyed(self);
    return Qnil;
}

#chop(x, y, width, height) ⇒ Magick::Image

Remove a region of an image and collapses the image to occupy the removed portion.

Parameters:

• x (Numeric) —

  x position of start of region

• y (Numeric) —

  y position of start of region

• width (Numeric) —

  width of region

• height (Numeric) —

  height of region

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 2672

VALUE
Image_chop(VALUE self, VALUE x, VALUE y, VALUE width, VALUE height)
{
    rm_check_destroyed(self);
    return xform_image(False, self, x, y, width, height, GVL_FUNC(ChopImage));
}

#chromaticity ⇒ Magick::Chromaticity

Return the red, green, blue, and white-point chromaticity values as a Chromaticity.

Returns:

• (Magick::Chromaticity) —

  the chromaticity values

# File 'ext/RMagick/rmimage.cpp', line 2685

VALUE
Image_chromaticity(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return ChromaticityInfo_new(&image->chromaticity);
}

#chromaticity=(chroma) ⇒ Magick::Chromaticity

Set the red, green, blue, and white-point chromaticity values from a Chromaticity.

Parameters:

• chroma (Magick::Chromaticity) —

  the chromaticity

Returns:

• (Magick::Chromaticity) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 2699

VALUE
Image_chromaticity_eq(VALUE self, VALUE chroma)
{
    Image *image = rm_check_frozen(self);
    Export_ChromaticityInfo(&image->chromaticity, chroma);
    return chroma;
}

#class_type ⇒ Magick::ClassType

Return the image's storage class (a.k.a. storage type, class type). If DirectClass then the pixels contain valid RGB or CMYK colors. If PseudoClass then the image has a colormap referenced by the pixel's index member.

Returns:

• (Magick::ClassType) —

  the storage class

# File 'ext/RMagick/rmimage.cpp', line 13819

VALUE
Image_class_type(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return ClassType_find(image->storage_class);
}

#class_type=(new_class_type) ⇒ Magick::ClassType

Change the image's storage class.

Parameters:

• new_class_type (Magick::ClassType) —

  the storage class

Returns:

• (Magick::ClassType) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 13833

VALUE
Image_class_type_eq(VALUE self, VALUE new_class_type)
{
    Image *image;
    ClassType class_type;
    QuantizeInfo qinfo;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

    VALUE_TO_ENUM(new_class_type, class_type, ClassType);

    if (class_type == UndefinedClass)
    {
        rb_raise(rb_eArgError, "Invalid class type specified.");
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
#endif

    if (image->storage_class == PseudoClass && class_type == DirectClass)
    {
#if defined(IMAGEMAGICK_7)
        GVL_STRUCT_TYPE(SyncImage) args = { image, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SyncImage), &args);
        CHECK_EXCEPTION();
#else
        GVL_STRUCT_TYPE(SyncImage) args = { image };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SyncImage), &args);
#endif
        magick_free(image->colormap);
        image->colormap = NULL;
    }
    else if (image->storage_class == DirectClass && class_type == PseudoClass)
    {
        GetQuantizeInfo(&qinfo);
        qinfo.number_colors = QuantumRange+1;
#if defined(IMAGEMAGICK_7)
        GVL_STRUCT_TYPE(QuantizeImage) args = { &qinfo, image, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(QuantizeImage), &args);
        CHECK_EXCEPTION();
#else
        GVL_STRUCT_TYPE(QuantizeImage) args = { &qinfo, image };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(QuantizeImage), &args);
#endif
    }

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, class_type, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, class_type };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
#endif
    return new_class_type;
}

#clone ⇒ Magick::Image

Same as #dup except the frozen state of the original is propagated to the new copy.

Returns:

• (Magick::Image) —

  a clone of this object

# File 'ext/RMagick/rmimage.cpp', line 2714

VALUE
Image_clone(VALUE self)
{
    VALUE clone;

    clone = Image_dup(self);
    if (OBJ_FROZEN(self))
    {
        OBJ_FREEZE(clone);
    }

    RB_GC_GUARD(clone);

    return clone;
}

#clut_channel(clut_image, channel = Magick::AllChannels) ⇒ Magick::Image #clut_channel(clut_image, *channels) ⇒ Magick::Image

Replace the channel values in the target image with a lookup of its replacement value in an LUT gradient image.

The LUT image should be either a single row or column image of replacement colors. The lookup is controlled by the -interpolate setting, especially for an LUT which is not the full length needed by the IM installed Quality (Q) level. Good settings for this is the default 'bilinear' or 'bicubic' interpolation setting for a smooth color gradient, or 'integer' for a direct unsmoothed lookup of color values.

This method is especially suited to replacing a grayscale image with specific color gradient from the CLUT image.

Overloads:

• #clut_channel(clut_image, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • clut_image (Magick::Image, Magick::ImageList) —

    The LUT gradient image.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #clut_channel(clut_image, *channels) ⇒ Magick::Image

  Parameters:

  • clut_image (Magick::Image, Magick::ImageList) —

    The LUT gradient image.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 2754

VALUE
Image_clut_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *clut;
    ChannelType channels;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

    // check_destroyed before confirming the arguments
    if (argc >= 1)
    {
        clut = rm_check_destroyed(rm_cur_image(argv[0]));
        channels = extract_channels(&argc, argv);
        if (argc != 1)
        {
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or more)", argc);
        }
    }
    else
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or more)", argc);
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(ClutImage) args = { image, clut, image->interpolate, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ClutImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    END_CHANNEL_MASK(image);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ClutImageChannel) args = { image, channels, clut };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ClutImageChannel), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(image, RetainOnError);
    rm_check_image_exception(clut, RetainOnError);
#endif
    if (!okay)
    {
        rb_raise(rb_eRuntimeError, "ClutImageChannel failed.");
    }

    return self;
}

#color_fill_to_border(x, y, fill) ⇒ Object

Set all pixels that are neighbors of x,y and are not the border color to the fill color

# File 'lib/rmagick_internal.rb', line 793

def color_fill_to_border(x, y, fill)
  color_flood_fill(border_color, fill, x, y, Magick::FillToBorderMethod)
end

#color_flood_fill(target_color, fill_color, xv, yv, method) ⇒ Magick::Image

Change the color value of any pixel that matches target_color and is an immediate neighbor.

Parameters:

• target_color (Magick::Pixel, String) —

  the target color

• fill_color (Magick::Pixel, String) —

  the color to fill

• xv (Numeric) —

  the x position

• yv (Numeric) —

  the y position

• method (Magick::PaintMethod) —

  the method to call

Returns:

• (Magick::Image) —

  a new image

See Also:

• #opaque

# File 'ext/RMagick/rmimage.cpp', line 3059

VALUE
Image_color_flood_fill(VALUE self, VALUE target_color, VALUE fill_color,
                       VALUE xv, VALUE yv, VALUE method)
{
    Image *image, *new_image;
    PixelColor target;
    DrawInfo *draw_info;
    PixelColor fill;
    long x, y;
    int fill_method;
    MagickPixel target_mpp;
    MagickBooleanType invert;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    // The target and fill args can be either a color name or
    // a Magick::Pixel.
    Color_to_PixelColor(&target, target_color);
    Color_to_PixelColor(&fill, fill_color);

    x = NUM2LONG(xv);
    y = NUM2LONG(yv);
    if ((unsigned long)x > image->columns || (unsigned long)y > image->rows)
    {
        rb_raise(rb_eArgError, "target out of range. %lux%lu given, image is %" RMIuSIZE "x%" RMIuSIZE "",
                 x, y, image->columns, image->rows);
    }

    VALUE_TO_ENUM(method, fill_method, PaintMethod);
    if (!(fill_method == FloodfillMethod || fill_method == FillToBorderMethod))
    {
        rb_raise(rb_eArgError, "paint method must be FloodfillMethod or "
                 "FillToBorderMethod (%d given)", fill_method);
    }

    draw_info = CloneDrawInfo(NULL, NULL);
    if (!draw_info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }
    draw_info->fill = fill;

    new_image = rm_clone_image(image);

    rm_init_magickpixel(new_image, &target_mpp);
    if (fill_method == FillToBorderMethod)
    {
        invert = MagickTrue;
        target_mpp.red   = (MagickRealType) image->border_color.red;
        target_mpp.green = (MagickRealType) image->border_color.green;
        target_mpp.blue  = (MagickRealType) image->border_color.blue;
    }
    else
    {
        invert = MagickFalse;
        target_mpp.red   = (MagickRealType) target.red;
        target_mpp.green = (MagickRealType) target.green;
        target_mpp.blue  = (MagickRealType) target.blue;
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, draw_info, &target_mpp, x, y, invert, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);
    DestroyDrawInfo(draw_info);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, DefaultChannels, draw_info, &target_mpp, x, y, invert };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);

    DestroyDrawInfo(draw_info);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#color_floodfill(x, y, fill) ⇒ Object

Set all pixels that have the same color as the pixel at x,y and are neighbors to the fill color

# File 'lib/rmagick_internal.rb', line 786

def color_floodfill(x, y, fill)
  target = pixel_color(x, y)
  color_flood_fill(target, fill, x, y, Magick::FloodfillMethod)
end

#color_histogram ⇒ Hash<Magick::Pixel, Integer>

Computes the number of times each unique color appears in the image.

Returns:

• (Hash<Magick::Pixel, Integer>) —

  Each key in the hash is a pixel representing a color that appears in the image. The value associated with the key is the number of times that color appears in the image.

# File 'ext/RMagick/rmimage.cpp', line 2812

VALUE
Image_color_histogram(VALUE self)
{
    Image *image, *dc_copy = NULL;
    VALUE hash, pixel;
    size_t x, colors;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    PixelInfo *histogram;
#else
    ColorPacket *histogram;
#endif

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();

    // If image not DirectClass make a DirectClass copy.
    if (image->storage_class != DirectClass)
    {
        dc_copy = rm_clone_image(image);
#if defined(IMAGEMAGICK_7)
        GVL_STRUCT_TYPE(SetImageStorageClass) args = { dc_copy, DirectClass, exception };
#else
        GVL_STRUCT_TYPE(SetImageStorageClass) args = { dc_copy, DirectClass };
#endif
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
        image = dc_copy;
    }

    GVL_STRUCT_TYPE(GetImageHistogram) args = { image, &colors, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageHistogram), &args);
    histogram = reinterpret_cast<decltype(histogram)>(ret);

    if (histogram == NULL)
    {
        if (dc_copy)
        {
            DestroyImage(dc_copy);
        }
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }
    if (rm_should_raise_exception(exception, DestroyExceptionRetention))
    {
        RelinquishMagickMemory(histogram);
        if (dc_copy)
        {
            DestroyImage(dc_copy);
        }

        rm_raise_exception(exception);
    }

    hash = rb_hash_new();
    for (x = 0; x < colors; x++)
    {
#if defined(IMAGEMAGICK_7)
        pixel = Pixel_from_PixelColor(&histogram[x]);
#else
        pixel = Pixel_from_PixelColor(&histogram[x].pixel);
#endif
        rb_hash_aset(hash, pixel, ULONG2NUM((unsigned long)histogram[x].count));
    }

    /*
        Christy evidently didn't agree with Bob's memory management.
    */
    RelinquishMagickMemory(histogram);

    if (dc_copy)
    {
        // Do not trace destruction
        DestroyImage(dc_copy);
    }

    RB_GC_GUARD(hash);
    RB_GC_GUARD(pixel);

    return hash;
}

#color_point(x, y, fill) ⇒ Object

Set the color at x,y

# File 'lib/rmagick_internal.rb', line 778

def color_point(x, y, fill)
  f = copy
  f.pixel_color(x, y, fill)
  f
end

#color_profile ⇒ String^?

Return the ICC color profile as a String.

• If there is no profile, returns ""
• This method has no real use but is retained for compatibility with earlier releases of RMagick, where it had no real use either.

Returns:

• (String, nil) —

  the ICC color profile

# File 'ext/RMagick/rmimage.cpp', line 3009

VALUE
Image_color_profile(VALUE self)
{
    Image *image;
    const StringInfo *profile;

    image = rm_check_destroyed(self);
    profile = GetImageProfile(image, "icc");
    if (!profile)
    {
        return Qnil;
    }

    return rb_str_new((char *)profile->datum, (long)profile->length);

}

#color_profile=(profile) ⇒ String^?

Set the ICC color profile.

• Pass nil to remove any existing profile.
• Removes any existing profile before adding the new one.

Parameters:

• profile (String, nil) —

  the profile to set

Returns:

• (String, nil) —

  the given profile

# File 'ext/RMagick/rmimage.cpp', line 3036

VALUE
Image_color_profile_eq(VALUE self, VALUE profile)
{
    Image_delete_profile(self, rb_str_new2("ICC"));
    if (profile != Qnil)
    {
        set_profile(self, "ICC", profile);
    }
    return profile;
}

#color_reset!(fill) ⇒ Object

Set all pixels to the fill color. Very similar to Image#erase! Accepts either String or Pixel arguments

# File 'lib/rmagick_internal.rb', line 799

def color_reset!(fill)
  save = background_color
  # Change the background color _outside_ the begin block
  # so that if this object is frozen the exeception will be
  # raised before we have to handle it explicitly.
  self.background_color = fill
  begin
    erase!
  ensure
    self.background_color = save
  end
  self
end

#colorize(red, green, blue, target) ⇒ Magick::Image #colorize(red, green, blue, matte, target) ⇒ Magick::Image

Blend the fill color specified by "target" with each pixel in the image. Specify the percentage blend for each r, g, b component.

Overloads:

• #colorize(red, green, blue, target) ⇒ Magick::Image

  Parameters:

  • red (Numeric) —

    The percentage of the fill color red

  • green (Numeric) —

    The percentage of the fill color green

  • blue (Numeric) —

    The percentage of the fill color blue

  • target (Magick::Pixel, String) —

    the color name

• #colorize(red, green, blue, matte, target) ⇒ Magick::Image

  Parameters:

  • red (Numeric) —

    The percentage of the fill color red

  • green (Numeric) —

    The percentage of the fill color green

  • blue (Numeric) —

    The percentage of the fill color blue

  • matte (Numeric) —

    The percentage of the fill color transparency

  • target (Magick::Pixel, String) —

    the color name

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 3160

VALUE
Image_colorize(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double red, green, blue, matte;
    char opacity[50];
    PixelColor target;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    if (argc == 4)
    {
        red   = floor(100*NUM2DBL(argv[0])+0.5);
        green = floor(100*NUM2DBL(argv[1])+0.5);
        blue  = floor(100*NUM2DBL(argv[2])+0.5);
        Color_to_PixelColor(&target, argv[3]);
        snprintf(opacity, sizeof(opacity), "%f/%f/%f", red, green, blue);
    }
    else if (argc == 5)
    {
        red   = floor(100*NUM2DBL(argv[0])+0.5);
        green = floor(100*NUM2DBL(argv[1])+0.5);
        blue  = floor(100*NUM2DBL(argv[2])+0.5);
        matte = floor(100*NUM2DBL(argv[3])+0.5);
        Color_to_PixelColor(&target, argv[4]);
        snprintf(opacity, sizeof(opacity), "%f/%f/%f/%f", red, green, blue, matte);
    }
    else
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 4 or 5)", argc);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(ColorizeImage) args = { image, opacity, &target, exception };
#else
    GVL_STRUCT_TYPE(ColorizeImage) args = { image, opacity, target, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ColorizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#colormap(index) ⇒ String #colormap(index, new_color) ⇒ String

Return the color in the colormap at the specified index. If a new color is specified, replaces the color at the index with the new color.

Overloads:

• #colormap(index) ⇒ String

  Parameters:

  • index (Numeric) —

    A number between 0 and the number of colors in the color map. If the value is out of range, colormap raises an IndexError. You can get the number of colors in the color map from the colors attribute.

• #colormap(index, new_color) ⇒ String

  Parameters:

  • index (Numeric) —

    A number between 0 and the number of colors in the color map. If the value is out of range, colormap raises an IndexError. You can get the number of colors in the color map from the colors attribute.

  • new_color (Magick::Pixel, String) —

    the color name

Returns:

• (String) —

  the name of the color at the specified location in the color map

# File 'ext/RMagick/rmimage.cpp', line 3224

VALUE
Image_colormap(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    unsigned long idx;
    PixelColor color, new_color;

    image = rm_check_destroyed(self);

    // We can handle either 1 or 2 arguments. Nothing else.
    if (argc == 0 || argc > 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or 2)", argc);
    }

    idx = NUM2ULONG(argv[0]);
    if (idx > QuantumRange)
    {
        rb_raise(rb_eIndexError, "index out of range");
    }

    // If this is a simple "get" operation, ensure the image has a colormap.
    if (argc == 1)
    {
        if (!image->colormap)
        {
            rb_raise(rb_eIndexError, "image does not contain a colormap");
        }
        // Validate the index

        if (idx > image->colors-1)
        {
            rb_raise(rb_eIndexError, "index out of range");
        }
        return rm_pixelcolor_to_color_name(image, &image->colormap[idx]);
    }

    // This is a "set" operation. Things are different.

    rb_check_frozen(self);

    // Replace with new color? The arg can be either a color name or
    // a Magick::Pixel.
    Color_to_PixelColor(&new_color, argv[1]);

    // Handle no colormap or current colormap too small.
    if (!image->colormap || idx > image->colors-1)
    {
        PixelColor black;
        unsigned long i;

        memset(&black, 0, sizeof(black));

        if (!image->colormap)
        {
            image->colormap = (PixelColor *)magick_safe_malloc((idx+1), sizeof(PixelColor));
            image->colors = 0;
        }
        else
        {
            image->colormap = (PixelColor *)magick_safe_realloc(image->colormap, (idx+1), sizeof(PixelColor));
        }

        for (i = image->colors; i < idx; i++)
        {
            image->colormap[i] = black;
        }
        image->colors = idx+1;
    }

    // Save the current color so we can return it. Set the new color.
    color = image->colormap[idx];
    image->colormap[idx] = new_color;

    return rm_pixelcolor_to_color_name(image, &color);
}

#colors ⇒ Integer

Get the number of colors in the colormap.

Returns:

• (Integer) —

  the number of colors

# File 'ext/RMagick/rmimage.cpp', line 3306

VALUE
Image_colors(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, colors, ulong, &rm_image_data_type);
}

#colorspace ⇒ Magick::ColorspaceType

Return the Image pixel interpretation. If the colorspace is RGB the pixels are red, green, blue. If matte is true, then red, green, blue, and index. If it is CMYK, the pixels are cyan, yellow, magenta, black. Otherwise the colorspace is ignored.

Returns:

• (Magick::ColorspaceType) —

  the colorspace

# File 'ext/RMagick/rmimage.cpp', line 3319

VALUE
Image_colorspace(VALUE self)
{
    Image *image;

    image = rm_check_destroyed(self);
    return ColorspaceType_find(image->colorspace);
}

#colorspace=(colorspace) ⇒ Magick::ColorspaceType

Set the image's colorspace.

Parameters:

• colorspace (Magick::ColorspaceType) —

  the colorspace

Returns:

• (Magick::ColorspaceType) —

  the given colorspace

# File 'ext/RMagick/rmimage.cpp', line 3335

VALUE
Image_colorspace_eq(VALUE self, VALUE colorspace)
{
    Image *image;
    ColorspaceType new_cs;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);
    VALUE_TO_ENUM(colorspace, new_cs, ColorspaceType);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(TransformImageColorspace) args = { image, new_cs, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransformImageColorspace), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(TransformImageColorspace) args = { image, new_cs };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransformImageColorspace), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return colorspace;
}

#columns ⇒ Integer

Get image columns.

Returns:

• (Integer) —

  the columns

# File 'ext/RMagick/rmimage.cpp', line 3368

VALUE
Image_columns(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, columns, int, &rm_image_data_type);
}

#compare_channel(image, metric, channel = Magick::AllChannels) ⇒ Array #compare_channel(image, metric, channel = Magick::AllChannels) {|opt_args| ... } ⇒ Array #compare_channel(image, metric, *channels) ⇒ Array #compare_channel(image, metric, *channels) {|opt_args| ... } ⇒ Array

Compare one or more channels in two images and returns the specified distortion metric and a comparison image.

Overloads:

• #compare_channel(image, metric, channel = Magick::AllChannels) ⇒ Array

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #compare_channel(image, metric, channel = Magick::AllChannels) {|opt_args| ... } ⇒ Array

  When a block is given, compare_channel yields with a block argument you can optionally use to set attributes.

  • options.highlight_color = color
    • Emphasize pixel differences with this color. The default is partially transparent red.
  • options.lowlight_color = color
    • Demphasize pixel differences with this color. The default is partially transparent white.

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

  Yields:

  • (opt_args)

  Yield Parameters:

  • opt_args (Magick::OptionalMethodArguments)
• #compare_channel(image, metric, *channels) ⇒ Array

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #compare_channel(image, metric, *channels) {|opt_args| ... } ⇒ Array

  When a block is given, compare_channel yields with a block argument you can optionally use to set attributes.

  • options.highlight_color = color
    • Emphasize pixel differences with this color. The default is partially transparent red.
  • options.lowlight_color = color
    • Demphasize pixel differences with this color. The default is partially transparent white.

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

  Yields:

  • (opt_args)

  Yield Parameters:

  • opt_args (Magick::OptionalMethodArguments)

Returns:

• (Array) —

  The first element is a difference image, the second is a the value of the computed distortion represented as a Float.

# File 'ext/RMagick/rmimage.cpp', line 3422

VALUE
Image_compare_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *r_image, *difference_image;
    double distortion;
    VALUE ary, ref;
    MetricType metric_type;
    ChannelType channels;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    if (argc > 2)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc != 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or more)", argc);
    }

    rm_get_optional_arguments(self);

    ref = rm_cur_image(argv[0]);
    r_image = rm_check_destroyed(ref);

    VALUE_TO_ENUM(argv[1], metric_type, MetricType);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(CompareImages) args = { image, r_image, metric_type, &distortion, exception };
    difference_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompareImages), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(CompareImageChannels) args = { image, r_image, channels, metric_type, &distortion, exception };
    difference_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompareImageChannels), &args);
#endif
    rm_check_exception(exception, difference_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(2);
    rb_ary_store(ary, 0, rm_image_new(difference_image));
    rb_ary_store(ary, 1, rb_float_new(distortion));

    RB_GC_GUARD(ary);
    RB_GC_GUARD(ref);

    return ary;
}

#compose ⇒ Magick::CompositeOperator

Return the composite operator attribute.

Returns:

• (Magick::CompositeOperator) —

  the composite operator

# File 'ext/RMagick/rmimage.cpp', line 3481

VALUE
Image_compose(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return CompositeOperator_find(image->compose);
}

#compose=(compose_arg) ⇒ Magick::CompositeOperator

Set the composite operator attribute.

Parameters:

• compose_arg (Magick::CompositeOperator) —

  the composite operator

Returns:

• (Magick::CompositeOperator) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 3495

VALUE
Image_compose_eq(VALUE self, VALUE compose_arg)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(compose_arg, image->compose, CompositeOperator);
    return compose_arg;
}

#composite(image, x_off, y_off, composite_op) ⇒ Magick::Image #composite(image, gravity, composite_op) ⇒ Magick::Image #composite(image, gravity, x_off, y_off, composite_op) ⇒ Magick::Image

Composites src onto dest using the specified composite operator.

Overloads:

• #composite(image, x_off, y_off, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

• #composite(image, gravity, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

• #composite(image, gravity, x_off, y_off, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite!

# File 'ext/RMagick/rmimage.cpp', line 3768

VALUE
Image_composite(int argc, VALUE *argv, VALUE self)
{
    return composite(False, argc, argv, self, DefaultChannels);
}

#composite!(image, x_off, y_off, composite_op) ⇒ Magick::Image #composite!(image, gravity, composite_op) ⇒ Magick::Image #composite!(image, gravity, x_off, y_off, composite_op) ⇒ Magick::Image

Composites src onto dest using the specified composite operator. In-place form of #composite.

Overloads:

• #composite!(image, x_off, y_off, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

• #composite!(image, gravity, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

• #composite!(image, gravity, x_off, y_off, composite_op) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite

# File 'ext/RMagick/rmimage.cpp', line 3728

VALUE
Image_composite_bang(int argc, VALUE *argv, VALUE self)
{
    return composite(True, argc, argv, self, DefaultChannels);
}

#composite_affine(source, affine_matrix) ⇒ Magick::Image

Composite the source over the destination image as dictated by the affine transform.

Parameters:

• source (Magick::Image, Magick::ImageList) —

  the source image

• affine_matrix (Magick::AffineMatrix) —

  affine transform matrix

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 3782

VALUE
Image_composite_affine(VALUE self, VALUE source, VALUE affine_matrix)
{
    Image *image, *composite_image, *new_image;
    AffineMatrix affine;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    composite_image = rm_check_destroyed(rm_cur_image(source));

    Export_AffineMatrix(&affine, affine_matrix);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(DrawAffineImage) args = { new_image, composite_image, &affine, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DrawAffineImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(DrawAffineImage) args = { new_image, composite_image, &affine };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DrawAffineImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#composite_channel(image, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel(image, x_off, y_off, composite_op, *channels) ⇒ Magick::Image #composite_channel(image, gravity, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel(image, gravity, composite_op, *channels) ⇒ Magick::Image #composite_channel(image, gravity, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel(image, gravity, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

Composite the source over the destination image channel as dictated by the affine transform.

Overloads:

• #composite_channel(image, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel(image, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #composite_channel(image, gravity, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel(image, gravity, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #composite_channel(image, gravity, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel(image, gravity, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite

# File 'ext/RMagick/rmimage.cpp', line 3918

VALUE
Image_composite_channel(int argc, VALUE *argv, VALUE self)
{
    return composite_channel(False, argc, argv, self);
}

#composite_channel!(image, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel!(image, x_off, y_off, composite_op, *channels) ⇒ Magick::Image #composite_channel!(image, gravity, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel!(image, gravity, composite_op, *channels) ⇒ Magick::Image #composite_channel!(image, gravity, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image #composite_channel!(image, gravity, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

Composite the source over the destination image channel as dictated by the affine transform. In-place form of #composite_channel.

Overloads:

• #composite_channel!(image, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel!(image, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #composite_channel!(image, gravity, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel!(image, gravity, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

• #composite_channel!(image, gravity, x_off, y_off, composite_op, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_channel!(image, gravity, x_off, y_off, composite_op, *channels) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • gravity (Magick::GravityType) —

    A GravityType value that specifies the location of img on image.

  • x_off (Numeric) —

    the x-offset of the composited image, measured from the upper-left corner of the image.

  • y_off (Numeric) —

    the y-offset of the composited image, measured from the upper-left corner of the image.

  • composite_op (Magick::CompositeOperator) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite_channel
• #composite!

# File 'ext/RMagick/rmimage.cpp', line 3993

VALUE
Image_composite_channel_bang(int argc, VALUE *argv, VALUE self)
{
    return composite_channel(True, argc, argv, self);
}

#composite_mathematics(image, a, b, c, d, gravity) ⇒ Magick::Image #composite_mathematics(image, a, b, c, d, x_off, y_off) ⇒ Magick::Image #composite_mathematics(image, a, b, c, d, gravity, x_off, y_off) ⇒ Magick::Image

Merge the source and destination images according to the formula aScDc + bSc + cDc + d where Sc is the source pixel and Dc is the destination pixel.

Overloads:

• #composite_mathematics(image, a, b, c, d, gravity) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • a (Numeric) —

    See the description.

  • b (Numeric) —

    See the description.

  • c (Numeric) —

    See the description.

  • d (Numeric) —

    See the description.

  • gravity (Magick::GravityType) —

    the gravity type

• #composite_mathematics(image, a, b, c, d, x_off, y_off) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • a (Numeric) —

    See the description.

  • b (Numeric) —

    See the description.

  • c (Numeric) —

    See the description.

  • d (Numeric) —

    See the description.

  • x_off (Numeric) —

    The x-offset of the composited image, measured relative to the gravity argument.

  • y_off (Numeric) —

    The y-offset of the composited image, measured relative to the gravity argument.

• #composite_mathematics(image, a, b, c, d, gravity, x_off, y_off) ⇒ Magick::Image

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • a (Numeric) —

    See the description.

  • b (Numeric) —

    See the description.

  • c (Numeric) —

    See the description.

  • d (Numeric) —

    See the description.

  • gravity (Magick::GravityType) —

    the gravity type

  • x_off (Numeric) —

    The x-offset of the composited image, measured relative to the gravity argument.

  • y_off (Numeric) —

    The y-offset of the composited image, measured relative to the gravity argument.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4041

VALUE
Image_composite_mathematics(int argc, VALUE *argv, VALUE self)
{
    Image *composite_image;
    VALUE args[5];
    signed long x_off = 0L;
    signed long y_off = 0L;
    GravityType gravity = NorthWestGravity;
    char compose_args[200];

    rm_check_destroyed(self);

    switch (argc)
    {
        case 8:
            VALUE_TO_ENUM(argv[5], gravity, GravityType);
            x_off = NUM2LONG(argv[6]);
            y_off = NUM2LONG(argv[7]);
            break;
        case 7:
            x_off = NUM2LONG(argv[5]);
            y_off = NUM2LONG(argv[6]);
            break;
        case 6:
            VALUE_TO_ENUM(argv[5], gravity, GravityType);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (got %d, expected 6 to 8)", argc);
            break;
    }

    composite_image = rm_check_destroyed(rm_cur_image(argv[0]));

    snprintf(compose_args, sizeof(compose_args), "%-.16g,%-.16g,%-.16g,%-.16g", NUM2DBL(argv[1]), NUM2DBL(argv[2]), NUM2DBL(argv[3]), NUM2DBL(argv[4]));
    SetImageArtifact(composite_image, "compose:args", compose_args);

    // Call composite(False, gravity, x_off, y_off, MathematicsCompositeOp, DefaultChannels)
    args[0] = argv[0];
    args[1] = GravityType_find(gravity);
    args[2] = LONG2FIX(x_off);
    args[3] = LONG2FIX(y_off);
    args[4] = CompositeOperator_find(MathematicsCompositeOp);

    return composite(False, 5, args, self, DefaultChannels);
}

#composite_tiled(src, composite_op = Magick::OverCompositeOp, channel = Magick::AllChannels) ⇒ Magick::Image #composite_tiled(src, composite_op = Magick::OverCompositeOp, *channels) ⇒ Magick::Image

Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile option.

Overloads:

• #composite_tiled(src, composite_op = Magick::OverCompositeOp, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • src (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • composite_op (Magick::CompositeOperator) (defaults to: Magick::OverCompositeOp) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_tiled(src, composite_op = Magick::OverCompositeOp, *channels) ⇒ Magick::Image

  Parameters:

  • src (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • composite_op (Magick::CompositeOperator) (defaults to: Magick::OverCompositeOp) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite_tiled!

# File 'ext/RMagick/rmimage.cpp', line 4210

VALUE
Image_composite_tiled(int argc, VALUE *argv, VALUE self)
{
    return composite_tiled(False, argc, argv, self);
}

#composite_tiled!(src, composite_op = Magick::OverCompositeOp, channel = Magick::AllChannels) ⇒ Magick::Image #composite_tiled!(src, composite_op = Magick::OverCompositeOp, *channels) ⇒ Magick::Image

Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile option. In-place form of #composite_tiled.

Overloads:

• #composite_tiled!(src, composite_op = Magick::OverCompositeOp, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • src (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • composite_op (Magick::CompositeOperator) (defaults to: Magick::OverCompositeOp) —

    the composite operator

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #composite_tiled!(src, composite_op = Magick::OverCompositeOp, *channels) ⇒ Magick::Image

  Parameters:

  • src (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • composite_op (Magick::CompositeOperator) (defaults to: Magick::OverCompositeOp) —

    the composite operator

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #composite_tiled

# File 'ext/RMagick/rmimage.cpp', line 4237

VALUE
Image_composite_tiled_bang(int argc, VALUE *argv, VALUE self)
{
    return composite_tiled(True, argc, argv, self);
}

#compress_colormap! ⇒ Magick::Image

Removes duplicate or unused entries in the colormap. Only PseudoClass images have a colormap. If the image is DirectClass then compress_colormap! converts it to PseudoClass.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 4277

VALUE
Image_compress_colormap_bang(VALUE self)
{
    Image *image;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(CompressImageColormap) args = { image, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompressImageColormap), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(CompressImageColormap) args = { image };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompressImageColormap), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(image, RetainOnError);
#endif
    if (!okay)
    {
        rb_warning("CompressImageColormap failed (probably DirectClass image)");
    }

    return self;
}

#compression ⇒ Magick::CompressionType

Get the compression attribute.

Returns:

• (Magick::CompressionType) —

  the compression

# File 'ext/RMagick/rmimage.cpp', line 4249

VALUE
Image_compression(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return CompressionType_find(image->compression);
}

#compression=(compression) ⇒ Magick::CompressionType

Set the compression attribute.

Parameters:

• compression (Magick::CompressionType) —

  the compression

Returns:

• (Magick::CompressionType) —

  the given compression

# File 'ext/RMagick/rmimage.cpp', line 4262

VALUE
Image_compression_eq(VALUE self, VALUE compression)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(compression, image->compression, CompressionType);
    return compression;
}

#contrast(sharpen = false) ⇒ Magick::Image

Enhance the intensity differences between the lighter and darker elements of the image.

Returns a new image.

Parameters:

• sharpen (Boolean) (defaults to: false) —

  If sharpen is true, the contrast is increased, otherwise it is reduced.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4495

VALUE
Image_contrast(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickBooleanType sharpen = MagickFalse;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
    }
    else if (argc == 1)
    {
        sharpen = (MagickBooleanType)RTEST(argv[0]);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ContrastImage) args = { new_image, sharpen, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ContrastImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ContrastImage) args = { new_image, sharpen };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ContrastImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#contrast_stretch_channel(black_point, white_point = pixels-black_point, channel = Magick::AllChannels) ⇒ Magick::Image #contrast_stretch_channel(black_point, white_point = pixels-black_point, *channels) ⇒ Magick::Image

This method is a simple image enhancement technique that attempts to improve the contrast in an image by `stretching' the range of intensity values it contains to span a desired range of values. It differs from the more sophisticated histogram equalization in that it can only apply a linear scaling function to the image pixel values.

Overloads:

• #contrast_stretch_channel(black_point, white_point = pixels-black_point, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • black_point (Numeric, String) —

    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 (Numeric, String) (defaults to: pixels-black_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 (columns * rows) - black_point.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #contrast_stretch_channel(black_point, white_point = pixels-black_point, *channels) ⇒ Magick::Image

  Parameters:

  • black_point (Numeric, String) —

    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 (Numeric, String) (defaults to: pixels-black_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.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4620

VALUE
Image_contrast_stretch_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    double black_point, white_point;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 2)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    get_black_white_point(image, argc, argv, &black_point, &white_point);

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(ContrastStretchImage) args = { new_image, black_point, white_point, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ContrastStretchImage), &args);
    END_CHANNEL_MASK(new_image);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ContrastStretchImageChannel) args = { new_image, channels, black_point, white_point };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ContrastStretchImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#convolve(order_arg, kernel_arg) ⇒ Magick::Image

Apply a custom convolution kernel to the image.

Parameters:

• order_arg (Numeric) —

  the number of rows and columns in the kernel

• kernel_arg (Array<Float>) —

  An order*order matrix of Float values.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4795

VALUE
Image_convolve(VALUE self, VALUE order_arg, VALUE kernel_arg)
{
    Image *image, *new_image;
    size_t order;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    KernelInfo *kernel;
#else
    double *kernel;
    unsigned int x;
#endif

    image = rm_check_destroyed(self);

    if (NUM2INT(order_arg) <= 0)
    {
        rb_raise(rb_eArgError, "order must be non-zero and positive");
    }

    order = NUM2INT(order_arg);
    kernel_arg = rb_Array(kernel_arg);
    rm_check_ary_len(kernel_arg, (long)(order*order));

#if defined(IMAGEMAGICK_7)
    kernel = convolve_create_kernel_info(order, kernel_arg);
#else
    // Convert the kernel array argument to an array of doubles

    kernel = (double *)ALLOC_N(double, order*order);
    for (x = 0; x < (unsigned)(order * order); x++)
    {
        VALUE element = rb_ary_entry(kernel_arg, (long)x);
        if (rm_check_num2dbl(element))
        {
            kernel[x] = NUM2DBL(element);
        }
        else
        {
            xfree((void *)kernel);
            rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
        }
    }
#endif

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(ConvolveImage) args = { image, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ConvolveImage), &args);
    DestroyKernelInfo(kernel);
#else
    GVL_STRUCT_TYPE(ConvolveImage) args = { image, order, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ConvolveImage), &args);
    xfree((void *)kernel);
#endif

    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#convolve_channel(order, kernel, channel = Magick::AllChannels) ⇒ Magick::Image #convolve_channel(order, kernel, *channels) ⇒ Magick::Image

Applies a custom convolution kernel to the specified channel or channels in the image.

Overloads:

• #convolve_channel(order, kernel, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • order_arg (Numeric) —

    the number of rows and columns in the kernel

  • kernel_arg (Array<Float>) —

    An order*order matrix of Float values.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #convolve_channel(order, kernel, *channels) ⇒ Magick::Image

  Parameters:

  • order_arg (Numeric) —

    the number of rows and columns in the kernel

  • kernel_arg (Array<Float>) —

    An order*order matrix of Float values.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4874

VALUE
Image_convolve_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    VALUE ary;
    size_t order;
    ChannelType channels;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    KernelInfo *kernel;
#else
    double *kernel;
    unsigned int x;
#endif

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // There are 2 required arguments.
    if (argc > 2)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc != 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or more)", argc);
    }

    if (NUM2INT(argv[0]) <= 0)
    {
        rb_raise(rb_eArgError, "order must be non-zero and positive");
    }

    order = NUM2INT(argv[0]);
    ary = rb_Array(argv[1]);
    rm_check_ary_len(ary, (long)(order*order));

#if defined(IMAGEMAGICK_7)
    kernel = convolve_create_kernel_info(order, ary);
#else
    kernel = ALLOC_N(double, (long)(order*order));

    // Convert the kernel array argument to an array of doubles
    for (x = 0; x < (unsigned)(order * order); x++)
    {
        VALUE element = rb_ary_entry(ary, (long)x);
        if (rm_check_num2dbl(element))
        {
            kernel[x] = NUM2DBL(element);
        }
        else
        {
            xfree((void *)kernel);
            rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
        }
    }
#endif

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(ConvolveImage) args = { image, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ConvolveImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
    DestroyKernelInfo(kernel);
#else
    GVL_STRUCT_TYPE(ConvolveImageChannel) args = { image, channels, order, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ConvolveImageChannel), &args);
    xfree((void *)kernel);
#endif

    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    RB_GC_GUARD(ary);

    return rm_image_new(new_image);
}

#copy ⇒ Magick::Image

Alias for #dup.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4963

VALUE
Image_copy(VALUE self)
{
    return rb_funcall(self, rm_ID_dup, 0);
}

#crop(x, y, width, height, reset = false) ⇒ Magick::Image #crop(gravity, width, height, reset = false) ⇒ Magick::Image #crop(gravity, x, y, width, height, reset = false) ⇒ Magick::Image

Extract a region of the image defined by width, height, x, y.

Overloads:

• #crop(x, y, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • x (Numeric) —

    x position of start of region

  • y (Numeric) —

    y position of start of region

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

• #crop(gravity, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • gravity (Magick::GravityType) —

    the gravity type

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

• #crop(gravity, x, y, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • gravity (Magick::GravityType) —

    the gravity type

  • x (Numeric) —

    x position of start of region

  • y (Numeric) —

    y position of start of region

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

Returns:

• (Magick::Image) —

  a new image

See Also:

• #crop!

# File 'ext/RMagick/rmimage.cpp', line 5018

VALUE
Image_crop(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return cropper(False, argc, argv, self);
}

#crop!(x, y, width, height, reset = false) ⇒ Magick::Image #crop!(gravity, width, height, reset = false) ⇒ Magick::Image #crop!(gravity, x, y, width, height, reset = false) ⇒ Magick::Image

Extract a region of the image defined by width, height, x, y. In-place form of #crop.

Overloads:

• #crop!(x, y, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • x (Numeric) —

    x position of start of region

  • y (Numeric) —

    y position of start of region

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

• #crop!(gravity, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • gravity (Magick::GravityType) —

    the gravity type

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

• #crop!(gravity, x, y, width, height, reset = false) ⇒ Magick::Image

  Parameters:

  • gravity (Magick::GravityType) —

    the gravity type

  • x (Numeric) —

    x position of start of region

  • y (Numeric) —

    y position of start of region

  • width (Numeric) —

    width of region

  • height (Numeric) —

    height of region

  • reset (Boolean) (defaults to: false) —

    true if reset the cropped image page canvas and position

Returns:

• (Magick::Image) —

  a new image

See Also:

• #crop!

# File 'ext/RMagick/rmimage.cpp', line 5054

VALUE
Image_crop_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return cropper(True, argc, argv, self);
}

#cur_image ⇒ Object

Used by ImageList methods - see ImageList#cur_image

# File 'lib/rmagick_internal.rb', line 814

def cur_image
  self
end

#cycle_colormap(amount) ⇒ Magick::Image

Displaces the colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.

The returned image is always a PseudoClass image, regardless of the type of the original image.

Parameters:

• amount (Numeric) —

  amount to cycle the colormap

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5071

VALUE
Image_cycle_colormap(VALUE self, VALUE amount)
{
    Image *image, *new_image;
    int amt;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    amt = NUM2INT(amount);

    image = rm_check_destroyed(self);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(CycleColormapImage) args = { new_image, amt, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CycleColormapImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(CycleColormapImage) args = { new_image, amt };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CycleColormapImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#decipher(passphrase) ⇒ Magick::Image

Decipher an enciphered image.

Parameters:

• passphrase (String) —

  The passphrase used to encipher the image.

Returns:

• (Magick::Image) —

  a new deciphered image

# File 'ext/RMagick/rmimage.cpp', line 5214

VALUE
Image_decipher(VALUE self, VALUE passphrase)
{
    Image *image, *new_image;
    char *pf;
    ExceptionInfo *exception;
    MagickBooleanType okay;

    image = rm_check_destroyed(self);
    pf = StringValueCStr(passphrase);      // ensure passphrase is a string
    exception = AcquireExceptionInfo();

    new_image = rm_clone_image(image);

    GVL_STRUCT_TYPE(DecipherImage) args = { new_image, pf, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DecipherImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_exception(exception, new_image, DestroyOnError);
    if (!okay)
    {
        DestroyImage(new_image);
        rb_raise(rb_eRuntimeError, "DecipherImage failed for unknown reason.");
    }

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#define(artifact, value) ⇒ String^?

Associates makes a copy of the given string arguments and inserts it into the artifact tree.

• Normally a script should never call this method. Any calls to SetImageArtifact will be part of the methods in which they're needed, or be called via the OptionalMethodArguments class.
• If value is nil, the artifact will be removed

Parameters:

• artifact (String) —

  the artifact to set

• value (String, nil) —

  the value to which to set the artifact

Returns:

• (String, nil) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 5257

VALUE
Image_define(VALUE self, VALUE artifact, VALUE value)
{
    Image *image;
    char *key, *val;
    MagickBooleanType status;

    image = rm_check_frozen(self);
    artifact = rb_String(artifact);
    key = StringValueCStr(artifact);

    if (value == Qnil)
    {
        DeleteImageArtifact(image, key);
    }
    else
    {
        value = rb_String(value);
        val = StringValueCStr(value);
        status = SetImageArtifact(image, key, val);
        if (!status)
        {
            rb_raise(rb_eNoMemError, "not enough memory to continue");
        }
    }

    return value;
}

#delay ⇒ Integer

Get the Number of ticks which must expire before displaying the next image in an animated sequence. The default number of ticks is 0. By default there are 100 ticks per second but this number can be changed via the ticks_per_second attribute.

Returns:

• (Integer) —

  The current delay value.

# File 'ext/RMagick/rmimage.cpp', line 5294

VALUE
Image_delay(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, delay, ulong, &rm_image_data_type);
}

#delay=(val) ⇒ Numeric

Set the Number of ticks which must expire before displaying the next image in an animated sequence.

Parameters:

• val (Numeric) —

  the delay value

Returns:

• (Numeric) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 5307

VALUE
Image_delay_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, delay, ulong, &rm_image_data_type);
}

#delete_compose_mask ⇒ Magick::Image

Delete the image composite mask.

Returns:

• (Magick::Image) —

  self

See Also:

• #add_compose_mask

# File 'ext/RMagick/rmimage.cpp', line 5320

VALUE
Image_delete_compose_mask(VALUE self)
{
    Image *image;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageMask) args = { image, CompositePixelMask, NULL, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageMask), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageMask) args = { image, NULL };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageMask), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return self;
}

#delete_profile(name) ⇒ Magick::Image

Deletes the specified profile.

Parameters:

• name (String) —

  The profile name, "IPTC" or "ICC" for example. Specify "*" to delete all the profiles in the image.

Returns:

• (Magick::Image) —

  self

See Also:

• #add_profile

# File 'ext/RMagick/rmimage.cpp', line 5354

VALUE
Image_delete_profile(VALUE self, VALUE name)
{
    Image *image = rm_check_frozen(self);
    char *profile_name = StringValueCStr(name);

#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(ProfileImage) args = { image, profile_name, NULL, 0, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ProfileImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ProfileImage) args = { image, profile_name, NULL, 0, MagickTrue };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ProfileImage), &args);
#endif
    return self;
}

#density ⇒ String

Get the vertical and horizontal resolution in pixels of the image. The default is "72x72".

Returns:

• (String) —

  a string of geometry in the form "XresxYres"

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 5108

VALUE
Image_density(VALUE self)
{
    Image *image;
    char density[128];

    image = rm_check_destroyed(self);

#if defined(IMAGEMAGICK_7)
    snprintf(density, sizeof(density), "%gx%g", image->resolution.x, image->resolution.y);
#else
    snprintf(density, sizeof(density), "%gx%g", image->x_resolution, image->y_resolution);
#endif
    return rb_str_new2(density);
}

#density=(density_arg) ⇒ Magick::Geometry, String

Set the vertical and horizontal resolution in pixels of the image.

• The density is a string of the form "XresxYres" or simply "Xres".
• If the y resolution is not specified, set it equal to the x resolution.
• This is equivalent to PerlMagick's handling of density.
• The density can also be a Geometry object. The width attribute is used for the x resolution. The height attribute is used for the y resolution. If the height attribute is missing, the width attribute is used for both.

Parameters:

• density_arg (Magick::Geometry, String) —

  The density String or Geometry

Returns:

• (Magick::Geometry, String) —

  the given value

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 5139

VALUE
Image_density_eq(VALUE self, VALUE density_arg)
{
    Image *image;
    char *density;
    VALUE x_val, y_val;
    int count;
    double x_res, y_res;

    image = rm_check_frozen(self);

    // Get the Class ID for the Geometry class.
    if (!Class_Geometry)
    {
        Class_Geometry = rb_const_get(Module_Magick, rm_ID_Geometry);
    }

    // Geometry object. Width and height attributes are always positive.
    if (CLASS_OF(density_arg) == Class_Geometry)
    {
        x_val = rb_funcall(density_arg, rm_ID_width, 0);
        x_res = NUM2DBL(x_val);
        y_val = rb_funcall(density_arg, rm_ID_height, 0);
        y_res = NUM2DBL(y_val);
        if (x_res == 0.0)
        {
            rb_raise(rb_eArgError, "invalid x resolution: %f", x_res);
        }
#if defined(IMAGEMAGICK_7)
        image->resolution.y = y_res != 0.0 ? y_res : x_res;
        image->resolution.x = x_res;
#else
        image->y_resolution = y_res != 0.0 ? y_res : x_res;
        image->x_resolution = x_res;
#endif
    }

    // Convert the argument to a string
    else
    {
        density = StringValueCStr(density_arg);
        if (!IsGeometry(density))
        {
            rb_raise(rb_eArgError, "invalid density geometry %s", density);
        }

#if defined(IMAGEMAGICK_7)
        count = sscanf(density, "%lfx%lf", &image->resolution.x, &image->resolution.y);
#else
        count = sscanf(density, "%lfx%lf", &image->x_resolution, &image->y_resolution);
#endif
        if (count < 2)
        {
#if defined(IMAGEMAGICK_7)
            image->resolution.y = image->resolution.x;
#else
            image->y_resolution = image->x_resolution;
#endif
        }

    }

    RB_GC_GUARD(x_val);
    RB_GC_GUARD(y_val);

    return density_arg;
}

#depth ⇒ Integer

Return the image depth (8, 16 or 32).

• If all pixels have lower-order bytes equal to higher-order bytes, the depth will be reported as 8 even if the depth field in the Image structure says 16.

Returns:

• (Integer) —

  the depth

# File 'ext/RMagick/rmimage.cpp', line 5383

VALUE
Image_depth(VALUE self)
{
    Image *image;
    size_t depth = 0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(GetImageDepth) args = { image, exception };
    depth = (size_t)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageDepth), &args);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return INT2FIX(depth);
}

#deskew(threshold = 0.40, auto_crop_width = nil) ⇒ Magick::Image

Straightens an image. A threshold of 40% works for most images.

Returns a new image.

Parameters:

• threshold (Numeric, String) (defaults to: 0.40) —

  A percentage of QuantumRange. Either a Float between 0 and 1.0, inclusive, or a string in the form "NN%" where NN is between 0 and 100.

• auto_crop_width (Numeric) (defaults to: nil) —

  Specify a value for this argument to cause the deskewed image to be auto-cropped. The argument is the pixel width of the image background (e.g. 40).

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5413

VALUE
Image_deskew(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double threshold = 40.0 * QuantumRange / 100.0;
    unsigned long width;
    char auto_crop_width[20];
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 2:
            width = NUM2ULONG(argv[1]);
            memset(auto_crop_width, 0, sizeof(auto_crop_width));
            snprintf(auto_crop_width, sizeof(auto_crop_width), "%lu", width);
            SetImageArtifact(image, "deskew:auto-crop", auto_crop_width);
        case 1:
            threshold = rm_percentage(argv[0], 1.0) * QuantumRange;
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 2)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(DeskewImage) args = { image, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DeskewImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#despeckle ⇒ Magick::Image

Reduce the speckle noise in an image while preserving the edges of the original image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5455

VALUE
Image_despeckle(VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(DespeckleImage) args = { image, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DespeckleImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#destroy! ⇒ Magick::Image

Free all the memory associated with an image.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 5478

VALUE
Image_destroy_bang(VALUE self)
{
    Image *image;

    rb_check_frozen(self);
    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);
    rm_image_destroy(image);
    DATA_PTR(self) = NULL;
    return self;
}

#destroyed? ⇒ Boolean

Return true if the image has been destroyed, false otherwise.

Returns:

• (Boolean) —

  true if destroyed, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 5496

VALUE
Image_destroyed_q(VALUE self)
{
    Image *image;

    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);
    return image ? Qfalse : Qtrue;
}

#difference(other) ⇒ Array<Float>

Compares two images and computes statistics about their difference.

Parameters:

• other (Magick::Image, Magick::ImageList) —

  Either an imagelist or an image. If an imagelist, uses the current image.

Returns:

• (Array<Float>) —

  An array of three Float values:

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

# File 'ext/RMagick/rmimage.cpp', line 5523

VALUE
Image_difference(VALUE self, VALUE other)
{
    Image *image;
    Image *image2;
    VALUE mean, nmean, nmax;
#if defined(IMAGEMAGICK_7)
    double distortion;
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    other = rm_cur_image(other);
    image2 = rm_check_destroyed(other);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(GetImageDistortion) args = { image, image2, MeanErrorPerPixelErrorMetric, &distortion, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageDistortion), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(IsImagesEqual) args = { image, image2 };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(IsImagesEqual), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    mean  = rb_float_new(image->error.mean_error_per_pixel);
    nmean = rb_float_new(image->error.normalized_mean_error);
    nmax  = rb_float_new(image->error.normalized_maximum_error);

    RB_GC_GUARD(mean);
    RB_GC_GUARD(nmean);
    RB_GC_GUARD(nmax);

    return rb_ary_new3(3, mean, nmean, nmax);
}

#directory ⇒ String^?

Get image directory.

Returns:

• (String, nil) —

  the directory

# File 'ext/RMagick/rmimage.cpp', line 5567

VALUE
Image_directory(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, directory, str, &rm_image_data_type);
}

#dispatch(x, y, columns, rows, map, float = false) ⇒ Array<Numeric>

Extract pixel data from the image and returns it as an array of pixels. The "x", "y", "width" and "height" parameters specify the rectangle to be extracted. The "map" parameter reflects 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). If the "float" parameter is specified and true, the pixel data is returned as floating-point numbers in the range [0..1]. By default the pixel data is returned as integers in the range [0..QuantumRange].

Returns an Array of pixel data.

Parameters:

• x (Numeric) —

  The offset of the rectangle from the upper-left corner of the image.

• y (Numeric) —

  The offset of the rectangle from the upper-left corner of the image.

• columns (Numeric) —

  The width of the rectangle.

• rows (Numeric) —

  The height of the rectangle.

• map (String)
• float (Boolean) (defaults to: false)

Returns:

• (Array<Numeric>) —

  an Array of pixel data

# File 'ext/RMagick/rmimage.cpp', line 5686

VALUE
Image_dispatch(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    long x, y;
    unsigned long columns, rows, n, npixels;
    VALUE pixels_ary;
    StorageType stg_type = QuantumPixel;
    char *map;
    size_t mapL;
    MagickBooleanType okay;
    ExceptionInfo *exception;
    volatile union
    {
        Quantum *i;
        double *f;
        void *v;
    } pixels;

    rm_check_destroyed(self);

    if (argc < 5 || argc > 6)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 5 or 6)", argc);
    }

    x       = NUM2LONG(argv[0]);
    y       = NUM2LONG(argv[1]);
    columns = NUM2ULONG(argv[2]);
    rows    = NUM2ULONG(argv[3]);
    map     = rm_str2cstr(argv[4], &mapL);
    if (argc == 6)
    {
        stg_type = RTEST(argv[5]) ? DoublePixel : QuantumPixel;
    }

    // Compute the size of the pixel array and allocate the memory.
    npixels = pixel_buffer_count(columns, rows, mapL);
    pixels.v = stg_type == QuantumPixel ? (void *) ALLOC_N(Quantum, npixels)
               : (void *) ALLOC_N(double, npixels);

    // Create the Ruby array for the pixels. Return this even if ExportImagePixels fails.
    pixels_ary = rb_ary_new();

    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ExportImagePixels) args = { image, x, y, columns, rows, map, stg_type, (void *)pixels.v, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ExportImagePixels), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));

    if (!okay)
    {
        goto exit;
    }

    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    // Convert the pixel data to the appropriate Ruby type
    if (stg_type == QuantumPixel)
    {
        for (n = 0; n < npixels; n++)
        {
            rb_ary_push(pixels_ary, QUANTUM2NUM(pixels.i[n]));
        }
    }
    else
    {
        for (n = 0; n < npixels; n++)
        {
            rb_ary_push(pixels_ary, rb_float_new(pixels.f[n]));
        }
    }

    exit:
    xfree((void *)pixels.v);

    RB_GC_GUARD(pixels_ary);

    return pixels_ary;
}

#displace(displacement_map, x_amp, y_amp = x_amp, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

Uses displacement_map to move color from img to the output image. This method corresponds to the -displace option of ImageMagick's composite command.

NorthWest corner by default.

Parameters:

• displacement_map (Magick::Image, Magick::ImageList) —

  The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.

• x_amp (Numeric) —

  The maximum displacement on the x-axis.

• y_amp (Numeric) (defaults to: x_amp) —

  The maximum displacement on the y-axis.

• gravity (Magick::GravityType) (defaults to: Magick::NorthWestGravity) —

  the gravity for offset. the offsets are measured from the

• x_offset (Numeric) (defaults to: 0) —

  The offset that measured from the left-hand side of the target image.

• y_offset (Numeric) (defaults to: 0) —

  The offset that measured from the top of the target image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5589

VALUE
Image_displace(int argc, VALUE *argv, VALUE self)
{
    Image *image, *displacement_map;
    VALUE dmap;
    double x_amplitude = 0.0, y_amplitude = 0.0;
    long x_offset = 0L, y_offset = 0L;

    image = rm_check_destroyed(self);

    if (argc < 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 6)", argc);
    }

    dmap = rm_cur_image(argv[0]);
    displacement_map = rm_check_destroyed(dmap);

    if (argc > 3)
    {
        get_composite_offsets(argc-3, &argv[3], image, displacement_map, &x_offset, &y_offset);
        // There must be 3 arguments left
        argc = 3;
    }

    switch (argc)
    {
        case 3:
            y_amplitude = NUM2DBL(argv[2]);
            x_amplitude = NUM2DBL(argv[1]);
            break;
        case 2:
            x_amplitude = NUM2DBL(argv[1]);
            y_amplitude = x_amplitude;
            break;
    }

    RB_GC_GUARD(dmap);

    return special_composite(image, displacement_map, x_amplitude, y_amplitude,
                             x_offset, y_offset, DisplaceCompositeOp);
}

#display {|info| ... } ⇒ Magick::Image Also known as: __display__

Display the image to an X window screen.

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 5778

VALUE
Image_display(VALUE self)
{
    Image *image;
    Info *info;
    VALUE info_obj;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    if (image->rows == 0 || image->columns == 0)
    {
        rb_raise(rb_eArgError, "invalid image geometry (%" RMIuSIZE "x%" RMIuSIZE ")", image->rows, image->columns);
    }

    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    DisplayImages(info, image, exception);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    DisplayImages(info, image);
    rm_check_image_exception(image, RetainOnError);
#endif

    RB_GC_GUARD(info_obj);

    return self;
}

#dispose ⇒ Magick::DisposeType

Return the dispose attribute as a DisposeType enum.

Returns:

• (Magick::DisposeType) —

  the dispose

# File 'ext/RMagick/rmimage.cpp', line 5819

VALUE
Image_dispose(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return DisposeType_find(image->dispose);
}

#dispose=(dispose) ⇒ Magick::DisposeType

Set the dispose attribute.

Parameters:

• dispose (Magick::DisposeType) —

  the dispose

Returns:

• (Magick::DisposeType) —

  the given dispose

# File 'ext/RMagick/rmimage.cpp', line 5833

VALUE
Image_dispose_eq(VALUE self, VALUE dispose)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(dispose, image->dispose, DisposeType);
    return dispose;
}

#dissolve(overlay, src_percent, dst_percent = -1.0, gravity = Magick::NorthWestGravity, x_offset = 0, y_offset = 0) ⇒ Magick::Image

Composites the overlay image into the target image. The opacity of img is multiplied by dst_percentage and opacity of overlay is multiplied by src_percentage.

This method corresponds to the -dissolve option of ImageMagick's composite command.

Returns a new image.

Parameters:

• overlay (Magick::Image, Magick::ImageList) —

  The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.

• src_percent (Numeric, String) —

  Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.

• dst_percent (Numeric, String) (defaults to: -1.0) —

  Either a non-negative number a string in the form "NN%". If src_percentage is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no other arguments follow it. In this case the default is 100%-src_percentage.

• gravity (Magick::GravityType) (defaults to: Magick::NorthWestGravity) —

  the gravity for offset. the offsets are measured from the NorthWest corner by default.

• x_offset (Numeric) (defaults to: 0) —

  The offset that measured from the left-hand side of the target image.

• y_offset (Numeric) (defaults to: 0) —

  The offset that measured from the top of the target image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5865

VALUE
Image_dissolve(int argc, VALUE *argv, VALUE self)
{
    Image *image, *overlay;
    double src_percent, dst_percent = -1.0;
    long x_offset = 0L, y_offset = 0L;
    VALUE composite_image, ovly;

    image = rm_check_destroyed(self);

    if (argc < 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 6)", argc);
    }

    ovly = rm_cur_image(argv[0]);
    overlay = rm_check_destroyed(ovly);

    if (argc > 3)
    {
        get_composite_offsets(argc-3, &argv[3], image, overlay, &x_offset, &y_offset);
        // There must be 3 arguments left
        argc = 3;
    }

    switch (argc)
    {
        case 3:
            dst_percent = rm_percentage(argv[2], 1.0) * 100.0;
        case 2:
            src_percent = rm_percentage(argv[1], 1.0) * 100.0;
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 6)", argc);
            break;
    }

    composite_image =  special_composite(image, overlay, src_percent, dst_percent,
                                         x_offset, y_offset, DissolveCompositeOp);

    RB_GC_GUARD(composite_image);
    RB_GC_GUARD(ovly);

    return composite_image;
}

#distort(type, points, bestfit = false) ⇒ Magick::Image #distort(type, points, bestfit = false) {|opt_args| ... } ⇒ Magick::Image

Distort an image using the specified distortion type and its required arguments. This method is equivalent to ImageMagick's -distort option.

Examples:

img.distort(Magick::ScaleRotateTranslateDistortion, [0]) do |options|
  options.define "distort:viewport", "44x44+15+0"
  options.define "distort:scale", 2
end

Overloads:

• #distort(type, points, bestfit = false) ⇒ Magick::Image

  Parameters:

  • type (Magick::DistortMethod) —

    a DistortMethod value

  • points (Array<Numeric>) —

    an Array of Numeric values. The size of the array depends on the distortion type.

  • bestfit (Boolean) (defaults to: false) —

    If bestfit is enabled, and the distortion allows it, the destination image is adjusted to ensure the whole source image will just fit within the final destination image, which will be sized and offset accordingly. Also in many cases the virtual offset of the source image will be taken into account in the mapping.

• #distort(type, points, bestfit = false) {|opt_args| ... } ⇒ Magick::Image

  When a block is given, distort yields with a block argument you can optionally use to set attributes.

  • options.define("distort:viewport", "WxH+X+Y")
    • Specify the size and offset of the generated viewport image of the distorted image space. W and H are the width and height, and X and Y are the offset.
  • options.define("distort:scale", N)
    • N is an integer factor. Scale the output image (viewport or otherwise) by that factor without changing the viewed contents of the distorted image. This can be used either for 'super-sampling' the image for a higher quality result, or for panning and zooming around the image (with appropriate viewport changes, or post-distort cropping and resizing).
  • options.verbose(true)
    • Attempt to output the internal coefficients, and the -fx equivalent to the distortion, for expert study, and debugging purposes. This many not be available for all distorts.

  Parameters:

  • type (Magick::DistortMethod) —

    a DistortMethod value

  • points (Array<Numeric>) —

    an Array of Numeric values. The size of the array depends on the distortion type.

  • bestfit (Boolean) (defaults to: false) —

    If bestfit is enabled, and the distortion allows it, the destination image is adjusted to ensure the whole source image will just fit within the final destination image, which will be sized and offset accordingly. Also in many cases the virtual offset of the source image will be taken into account in the mapping.

  Yields:

  • (opt_args)

  Yield Parameters:

  • opt_args (Magick::OptionalMethodArguments)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 5954

VALUE
Image_distort(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    VALUE pts;
    unsigned long n, npoints;
    DistortMethod distortion_method;
    double *points;
    MagickBooleanType bestfit = MagickFalse;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    rm_get_optional_arguments(self);

    switch (argc)
    {
        case 3:
            bestfit = (MagickBooleanType)RTEST(argv[2]);
        case 2:
            // Ensure pts is an array
            pts = rb_Array(argv[1]);
            VALUE_TO_ENUM(argv[0], distortion_method, DistortMethod);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (expected 2 or 3, got %d)", argc);
            break;
    }

    npoints = RARRAY_LEN(pts);
    points = ALLOC_N(double, npoints);

    for (n = 0; n < npoints; n++)
    {
        VALUE element = rb_ary_entry(pts, n);
        if (rm_check_num2dbl(element))
        {
            points[n] = NUM2DBL(element);
        }
        else
        {
            xfree(points);
            rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
        }
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(DistortImage) args = { image, distortion_method, npoints, points, bestfit, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(DistortImage), &args);
    xfree(points);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    RB_GC_GUARD(pts);

    return rm_image_new(new_image);
}

#distortion_channel(reconstructed_image, metric, channel = Magick::AllChannels) ⇒ Float #distortion_channel(reconstructed_image, metric, *channels) ⇒ Float

Compares one or more image channels of an image to a reconstructed image and returns the specified distortion metric.

Overloads:

• #distortion_channel(reconstructed_image, metric, channel = Magick::AllChannels) ⇒ Float

  Parameters:

  • reconstructed_image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #distortion_channel(reconstructed_image, metric, *channels) ⇒ Float

  Parameters:

  • reconstructed_image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • metric (Magick::MetricType) —

    The desired distortion metric.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Float) —

  the image channel distortion

# File 'ext/RMagick/rmimage.cpp', line 6030

VALUE
Image_distortion_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *reconstruct;
    ChannelType channels;
    ExceptionInfo *exception;
    MetricType metric;
    VALUE rec;
    double distortion;
#if defined(IMAGEMAGICK_7)
    Image *difference_image;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 2)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc < 2)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or more)", argc);
    }

    rec = rm_cur_image(argv[0]);
    reconstruct = rm_check_destroyed(rec);
    VALUE_TO_ENUM(argv[1], metric, MetricType);
    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(CompareImages) args = { image, reconstruct, metric, &distortion, exception };
    difference_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompareImages), &args);
    END_CHANNEL_MASK(image);
    DestroyImage(difference_image);
#else
    GVL_STRUCT_TYPE(GetImageChannelDistortion) args = { image, reconstruct, channels, metric, &distortion, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetImageChannelDistortion), &args);
#endif

    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    RB_GC_GUARD(rec);

    return rb_float_new(distortion);
}

#dup ⇒ Magick::Image

Duplicates a image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6147

VALUE
Image_dup(VALUE self)
{
    VALUE dup;

    rm_check_destroyed(self);
    dup = TypedData_Wrap_Struct(CLASS_OF(self), &rm_image_data_type, NULL);
    RB_GC_GUARD(dup);

    return rb_funcall(dup, rm_ID_initialize_copy, 1, self);
}

#each_iptc_dataset ⇒ Object

Iterate over IPTC record number:dataset tags, yield for each non-nil dataset

# File 'lib/rmagick_internal.rb', line 872

def each_iptc_dataset
  Magick::IPTC.constants.each do |record|
    rec = Magick::IPTC.const_get(record)
    rec.constants.each do |dataset|
      data_field = get_iptc_dataset(rec.const_get(dataset))
      yield(dataset, data_field) unless data_field.nil?
    end
  end
  nil
end

#each_pixel ⇒ Object

Thanks to Russell Norris!

# File 'lib/rmagick_internal.rb', line 819

def each_pixel
  get_pixels(0, 0, columns, rows).each_with_index do |p, n|
    yield(p, n % columns, n / columns)
  end
  self
end

#each_profile {|name, val| ... } ⇒ Object

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

Yields:

• (name, val)

Yield Parameters:

• name (String) —

  the profile name

• val (String) —

  the profile value

Returns:

• (Object) —

  the last value returned by the block

# File 'ext/RMagick/rmimage.cpp', line 6168

VALUE
Image_each_profile(VALUE self)
{
    Image *image;
    VALUE ary;
    VALUE val = Qnil;
    char *name;
    const StringInfo *profile;

    image = rm_check_destroyed(self);
    ResetImageProfileIterator(image);

    ary = rb_ary_new2(2);

    name = GetNextImageProfile(image);
    while (name)
    {
        rb_ary_store(ary, 0, rb_str_new2(name));

        profile = GetImageProfile(image, name);
        if (!profile)
        {
            rb_ary_store(ary, 1, Qnil);
        }
        else
        {
            rb_ary_store(ary, 1, rb_str_new((char *)profile->datum, (long)profile->length));
        }
        val = rb_yield(ary);
        name = GetNextImageProfile(image);
    }

    RB_GC_GUARD(ary);
    RB_GC_GUARD(val);

    return val;
}

#edge(radius = 0.0) ⇒ Magick::Image

Find edges in an image. "radius" defines the radius of the convolution filter.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the convolution filter.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6214

VALUE
Image_edge(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius = 0.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            radius = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(EdgeImage) args = { image, radius, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EdgeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#emboss(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Adds a 3-dimensional effect.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian operator.

• sigma (Numeric) (defaults to: 1.0) —

  The sigma (standard deviation) of the Gaussian operator.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6303

VALUE
Image_emboss(int argc, VALUE *argv, VALUE self)
{
    return effect_image(self, argc, argv, GVL_FUNC(EmbossImage));
}

#encipher(passphrase) ⇒ Magick::Image

Encipher an image.

Examples:

enciphered_img = img.encipher("magic word")

Parameters:

• passphrase (String) —

  the passphrase with which to encipher

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6318

VALUE
Image_encipher(VALUE self, VALUE passphrase)
{
    Image *image, *new_image;
    char *pf;
    ExceptionInfo *exception;
    MagickBooleanType okay;

    image = rm_check_destroyed(self);
    pf = StringValueCStr(passphrase);      // ensure passphrase is a string
    exception = AcquireExceptionInfo();

    new_image = rm_clone_image(image);

    GVL_STRUCT_TYPE(EncipherImage) args = { new_image, pf, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EncipherImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_exception(exception, new_image, DestroyOnError);
    if (!okay)
    {
        DestroyImage(new_image);
        rb_raise(rb_eRuntimeError, "EncipherImage failed for unknown reason.");
    }

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#endian ⇒ Magick::EndianType

Return endian option for images that support it.

Returns:

• (Magick::EndianType) —

  the endian option

# File 'ext/RMagick/rmimage.cpp', line 6354

VALUE
Image_endian(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return EndianType_find(image->endian);
}

#endian=(type) ⇒ Magick::EndianType

Set endian option for images that support it.

Parameters:

• type (Magick::EndianType) —

  the endian type

Returns:

• (Magick::EndianType) —

  the given type

# File 'ext/RMagick/rmimage.cpp', line 6368

VALUE
Image_endian_eq(VALUE self, VALUE type)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(type, image->endian, EndianType);
    return type;
}

#enhance ⇒ Magick::Image

Apply a digital filter that improves the quality of a noisy image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6381

VALUE
Image_enhance(VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(EnhanceImage) args = { image, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EnhanceImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#equalize ⇒ Magick::Image

Apply a histogram equalization to the image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6404

VALUE
Image_equalize(VALUE self)
{
    Image *image, *new_image;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(EqualizeImage) args = { new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EqualizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(EqualizeImage) args = { new_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EqualizeImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#equalize_channel(channel = Magick::AllChannels) ⇒ Magick::Image #equalize_channel(*channels) ⇒ Magick::Image

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

Overloads:

• #equalize_channel(channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #equalize_channel(*channels) ⇒ Magick::Image

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6442

VALUE
Image_equalize_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif
    ChannelType channels;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(EqualizeImage) args = { new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EqualizeImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(EqualizeImageChannel) args = { new_image, channels };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EqualizeImageChannel), &args);

    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#erase! ⇒ Magick::Image

Reset the image to the background color.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 6484

VALUE
Image_erase_bang(VALUE self)
{
    Image *image;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageBackgroundColor) args = { image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageBackgroundColor) args = { image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageBackgroundColor), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return self;
}

#excerpt(x, y, width, height) ⇒ Magick::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.

Parameters:

• x (Numeric) —

  the x position for the start of the rectangle

• y (Numeric) —

  the y position for the start of the rectangle

• width (Numeric) —

  the width of the rectancle

• height (Numeric) —

  the height of the rectangle

Returns:

• (Magick::Image) —

  a new image

See Also:

• #excerpt!
• #crop
• #crop!

# File 'ext/RMagick/rmimage.cpp', line 6579

VALUE
Image_excerpt(VALUE self, VALUE x, VALUE y, VALUE width, VALUE height)
{
    rm_check_destroyed(self);
    return excerpt(False, self, x, y, width, height);
}

#excerpt!(x, y, width, height) ⇒ Magick::Image

In-place form of #excerpt.

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.

Parameters:

• x (Numeric) —

  the x position for the start of the rectangle

• y (Numeric) —

  the y position for the start of the rectangle

• width (Numeric) —

  the width of the rectancle

• height (Numeric) —

  the height of the rectangle

Returns:

• (Magick::Image) —

  self

See Also:

• #excerpt
• #crop
• #crop!

# File 'ext/RMagick/rmimage.cpp', line 6604

VALUE
Image_excerpt_bang(VALUE self, VALUE x, VALUE y, VALUE width, VALUE height)
{
    rm_check_frozen(self);
    return excerpt(True, self, x, y, width, height);
}

#export_pixels(x = 0, y = 0, cols = self.columns, rows = self.rows, map = "RGB") ⇒ Array<Numeric>

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.

Returns array of pixels.

Parameters:

• x (Numeric) (defaults to: 0) —

  The offset of the rectangle from the upper-left corner of the image.

• y (Numeric) (defaults to: 0) —

  The offset of the rectangle from the upper-left corner of the image.

• cols (Numeric) (defaults to: self.columns) —

  The width of the rectangle.

• rows (Numeric) (defaults to: self.rows) —

  The height of the rectangle.

• map (String) (defaults to: "RGB") —

  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:

• (Array<Numeric>) —

  array of pixels

# File 'ext/RMagick/rmimage.cpp', line 6629

VALUE
Image_export_pixels(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    long x_off = 0L, y_off = 0L;
    unsigned long cols, rows;
    long n, npixels;
    MagickBooleanType okay;
    const char *map = "RGB";
    Quantum *pixels;
    VALUE ary;
    ExceptionInfo *exception;


    image = rm_check_destroyed(self);
    cols = image->columns;
    rows = image->rows;

    switch (argc)
    {
        case 5:
            map   = StringValueCStr(argv[4]);
        case 4:
            rows  = NUM2ULONG(argv[3]);
        case 3:
            cols  = NUM2ULONG(argv[2]);
        case 2:
            y_off = NUM2LONG(argv[1]);
        case 1:
            x_off = NUM2LONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 5)", argc);
            break;
    }

    if (   x_off < 0 || (unsigned long)x_off > image->columns
           || y_off < 0 || (unsigned long)y_off > image->rows
           || cols == 0 || rows == 0)
    {
        rb_raise(rb_eArgError, "invalid extract geometry");
    }


    npixels = (long)pixel_buffer_count(cols, rows, strlen(map));
    pixels = ALLOC_N(Quantum, npixels);
    if (!pixels)    // app recovered from exception
    {
        return rb_ary_new2(0L);
    }

    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(ExportImagePixels) args = { image, x_off, y_off, cols, rows, map, QuantumPixel, (void *)pixels, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ExportImagePixels), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    if (!okay)
    {
        xfree((void *)pixels);
        CHECK_EXCEPTION();

        // Should never get here...
        rm_magick_error("ExportImagePixels failed with no explanation.");
    }

    DestroyExceptionInfo(exception);

    ary = rb_ary_new2(npixels);
    for (n = 0; n < npixels; n++)
    {
        rb_ary_push(ary, QUANTUM2NUM(pixels[n]));
    }

    xfree((void *)pixels);

    RB_GC_GUARD(ary);

    return ary;
}

#export_pixels_to_str(x = 0, y = 0, cols = self.columns, rows = self.rows, map = "RGB", type = Magick::CharPixel) ⇒ String

Extracts the pixel data from the specified rectangle and returns it as a string.

Returns the pixel data.

Parameters:

• x (Numeric) (defaults to: 0) —

  The offset of the rectangle from the upper-left corner of the image.

• y (Numeric) (defaults to: 0) —

  The offset of the rectangle from the upper-left corner of the image.

• cols (Numeric) (defaults to: self.columns) —

  The width of the rectangle.

• rows (Numeric) (defaults to: self.rows) —

  The height of the rectangle.

• map (String) (defaults to: "RGB") —

  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 (Magick::StorageType) (defaults to: Magick::CharPixel) —

  A StorageType value that specifies the C datatype to which the pixel data will be converted.

Returns:

• (String) —

  the pixel data

# File 'ext/RMagick/rmimage.cpp', line 6795

VALUE
Image_export_pixels_to_str(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    long x_off = 0L, y_off = 0L;
    unsigned long cols, rows;
    unsigned long npixels;
    size_t sz;
    MagickBooleanType okay;
    const char *map = "RGB";
    StorageType type = CharPixel;
    VALUE string;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    cols = image->columns;
    rows = image->rows;

    switch (argc)
    {
        case 6:
            VALUE_TO_ENUM(argv[5], type, StorageType);
        case 5:
            map   = StringValueCStr(argv[4]);
        case 4:
            rows  = NUM2ULONG(argv[3]);
        case 3:
            cols  = NUM2ULONG(argv[2]);
        case 2:
            y_off = NUM2LONG(argv[1]);
        case 1:
            x_off = NUM2LONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 6)", argc);
            break;
    }

    if (   x_off < 0 || (unsigned long)x_off > image->columns
           || y_off < 0 || (unsigned long)y_off > image->rows
           || cols == 0 || rows == 0)
    {
        rb_raise(rb_eArgError, "invalid extract geometry");
    }


    npixels = pixel_buffer_count(cols, rows, strlen(map));
    switch (type)
    {
        case CharPixel:
            sz = sizeof(unsigned char);
            break;
        case ShortPixel:
            sz = sizeof(unsigned short);
            break;
        case DoublePixel:
            sz = sizeof(double);
            break;
        case FloatPixel:
            sz = sizeof(float);
            break;
        case LongPixel:
            sz = sizeof(unsigned long);
            break;
        case QuantumPixel:
            sz = sizeof(Quantum);
            break;
        case UndefinedPixel:
        default:
            rb_raise(rb_eArgError, "undefined storage type");
            break;
    }

    // Allocate a string long enough to hold the exported pixel data.
    // Get a pointer to the buffer.
    if (npixels != 0 && sz > (size_t)LONG_MAX / npixels)
    {
        rb_raise(rb_eRangeError, "pixel buffer dimensions too large");
    }
    string = rb_str_new2("");
    rb_str_resize(string, (long)(sz * npixels));

    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(ExportImagePixels) args = { image, x_off, y_off, cols, rows, map, type, (void *)RSTRING_PTR(string), exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ExportImagePixels), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    if (!okay)
    {
        // Let GC have the string buffer.
        rb_str_resize(string, 0);
        CHECK_EXCEPTION();

        // Should never get here...
        rm_magick_error("ExportImagePixels failed with no explanation.");
    }

    DestroyExceptionInfo(exception);

    RB_GC_GUARD(string);

    return string;
}

#extent(width, height, x = 0, y = 0) ⇒ Magick::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.

Returns a new image.

Parameters:

• width (Numeric) —

  The width of the new image

• height (Numeric) —

  The height of the new image

• x (Numeric) (defaults to: 0) —

  The upper-left corner of the new image is positioned

• y (Numeric) (defaults to: 0) —

  The upper-left corner of the new image is positioned

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 6724

VALUE
Image_extent(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    RectangleInfo geometry;
    long height, width;
    ExceptionInfo *exception;

    rm_check_destroyed(self);

    if (argc < 2 || argc > 4)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (expected 2 to 4, got %d)", argc);
    }

    geometry.y = geometry.x = 0L;
    switch (argc)
    {
        case 4:
            geometry.y = NUM2LONG(argv[3]);
        case 3:
            geometry.x = NUM2LONG(argv[2]);
        default:
            geometry.height = height = NUM2LONG(argv[1]);
            geometry.width = width = NUM2LONG(argv[0]);
            break;
    }

    // Use the signed versions of these two values to test for < 0
    if (height <= 0L || width <= 0L)
    {
        if (geometry.x == 0 && geometry.y == 0)
        {
            rb_raise(rb_eArgError, "invalid extent geometry %ldx%ld", width, height);
        }
        else
        {
            rb_raise(rb_eArgError, "invalid extent geometry %ldx%ld+%" RMIdSIZE "+%" RMIdSIZE "",
                     width, height, geometry.x, geometry.y);
        }
    }


    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(ExtentImage) args = { image, &geometry, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ExtentImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#extract_info ⇒ Magick::Rectangle

The extract_info attribute reader.

Returns:

• (Magick::Rectangle) —

  the Rectangle object

# File 'ext/RMagick/rmimage.cpp', line 6906

VALUE
Image_extract_info(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return Import_RectangleInfo(&image->extract_info);
}

#extract_info=(rect) ⇒ Magick::Rectangle

Set the extract_info attribute.

Parameters:

• rect (Magick::Rectangle) —

  the Rectangle object

Returns:

• (Magick::Rectangle) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 6920

VALUE
Image_extract_info_eq(VALUE self, VALUE rect)
{
    Image *image = rm_check_frozen(self);
    Export_RectangleInfo(&image->extract_info, rect);
    return rect;
}

#filename ⇒ String

Get image filename.

Returns:

• (String) —

  the filename

# File 'ext/RMagick/rmimage.cpp', line 6934

VALUE
Image_filename(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, filename, str, &rm_image_data_type);
}

#filesize ⇒ Integer

Return the image file size.

Returns:

• (Integer) —

  the file size

# File 'ext/RMagick/rmimage.cpp', line 6946

VALUE Image_filesize(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return INT2FIX(GetBlobSize(image));
}

#filter ⇒ Magick::FilterType

Get filter type.

Returns:

• (Magick::FilterType) —

  the filter

# File 'ext/RMagick/rmimage.cpp', line 6958

VALUE
Image_filter(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return FilterType_find(image->filter);
}

#filter=(filter) ⇒ Magick::FilterType

Set filter type.

Parameters:

• filter (Magick::FilterType) —

  the filter

Returns:

• (Magick::FilterType) —

  the given filter

# File 'ext/RMagick/rmimage.cpp', line 6972

VALUE
Image_filter_eq(VALUE self, VALUE filter)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(filter, image->filter, FilterType);
    return filter;
}

#find_similar_region(target, x = 0, y = 0) ⇒ Array<Numeric>^?

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.

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.

Parameters:

• target (Magick::Image, Magick::ImageList) —

  An image that forms the target of the search. This image can be any size. Either an imagelist or an image. If an imagelist, uses the current image.

• x (Numeric) (defaults to: 0) —

  The starting x-offsets for the search.

• y (Numeric) (defaults to: 0) —

  The starting y-offsets for the search.

Returns:

• (Array<Numeric>, nil) —

  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.

# File 'ext/RMagick/rmimage.cpp', line 6997

VALUE
Image_find_similar_region(int argc, VALUE *argv, VALUE self)
{
    Image *image, *target;
    VALUE region, targ;
    ssize_t x = 0L, y = 0L;
    ExceptionInfo *exception;
    MagickBooleanType okay;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 3:
            y = NUM2LONG(argv[2]);
        case 2:
            x = NUM2LONG(argv[1]);
        case 1:
            targ = rm_cur_image(argv[0]);
            target = rm_check_destroyed(targ);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 3)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(IsEquivalentImage) args = { image, target, &x, &y, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(IsEquivalentImage), &args);
#else
    GVL_STRUCT_TYPE(IsImageSimilar) args = { image, target, &x, &y, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(IsImageSimilar), &args);
#endif
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);

    if (!okay)
    {
        return Qnil;
    }

    region = rb_ary_new2(2);
    rb_ary_store(region, 0L, LONG2NUM(x));
    rb_ary_store(region, 1L, LONG2NUM(y));

    RB_GC_GUARD(region);
    RB_GC_GUARD(targ);

    return region;
}

#flip ⇒ Magick::Image

Create a vertical mirror image by reflecting the pixels around the central x-axis.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #flip!
• #flop
• #flop!

# File 'ext/RMagick/rmimage.cpp', line 7102

VALUE
Image_flip(VALUE self)
{
    rm_check_destroyed(self);
    return flipflop(False, self, GVL_FUNC(FlipImage));
}

#flip! ⇒ Magick::Image

Create a vertical mirror image by reflecting the pixels around the central x-axis. In-place form of #flip.

Returns:

• (Magick::Image) —

  self

See Also:

• #flip
• #flop
• #flop!

# File 'ext/RMagick/rmimage.cpp', line 7119

VALUE
Image_flip_bang(VALUE self)
{
    rm_check_frozen(self);
    return flipflop(True, self, GVL_FUNC(FlipImage));
}

#flop ⇒ Magick::Image

Create a horizonal mirror image by reflecting the pixels around the central y-axis.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #flop!
• #flip
• #flip!

# File 'ext/RMagick/rmimage.cpp', line 7135

VALUE
Image_flop(VALUE self)
{
    rm_check_destroyed(self);
    return flipflop(False, self, GVL_FUNC(FlopImage));
}

#flop! ⇒ Magick::Image

Create a horizonal mirror image by reflecting the pixels around the central y-axis. In-place form of #flop.

Returns:

• (Magick::Image) —

  self

See Also:

• #flop
• #flip
• #flip!

# File 'ext/RMagick/rmimage.cpp', line 7152

VALUE
Image_flop_bang(VALUE self)
{
    rm_check_frozen(self);
    return flipflop(True, self, GVL_FUNC(FlopImage));
}

#format ⇒ String^?

Return the image encoding format. For example, "GIF" or "PNG".

Returns:

• (String, nil) —

  the encoding format

# File 'ext/RMagick/rmimage.cpp', line 7165

VALUE
Image_format(VALUE self)
{
    Image *image;
    const MagickInfo *magick_info;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    if (*image->magick)
    {
        // Deliberately ignore the exception info!
        exception = AcquireExceptionInfo();
        magick_info = GetMagickInfo(image->magick, exception);
        DestroyExceptionInfo(exception);
        return magick_info ? rb_str_new2(magick_info->name) : Qnil;
    }

    return Qnil;
}

#format=(magick) ⇒ String

Set the image encoding format. For example, "GIF" or "PNG".

Parameters:

• magick (String) —

  the encoding format

Returns:

• (String) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 7193

VALUE
Image_format_eq(VALUE self, VALUE magick)
{
    Image *image;
    const MagickInfo *m;
    char *mgk;
    ExceptionInfo *exception;

    image = rm_check_frozen(self);

    mgk = StringValueCStr(magick);

    exception = AcquireExceptionInfo();
    m = GetMagickInfo(mgk, exception);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    if (!m)
    {
        rb_raise(rb_eArgError, "unknown format: %s", mgk);
    }


    strlcpy(image->magick, m->name, sizeof(image->magick));
    return magick;
}

#frame(width = self.columns+25*2, height = self.rows+25*2, x = 25, y = 25, inner_bevel = 6, outer_bevel = 6, color = self.matte_color) ⇒ Magick::Image

Add a simulated three-dimensional border around the image.

Returns a new image.

Parameters:

• width (Numeric) (defaults to: self.columns+25*2) —

  The width of the left and right sides.

• height (Numeric) (defaults to: self.rows+25*2) —

  The height of the top and bottom sides.

• x (Numeric) (defaults to: 25) —

  The offset of the image from the upper-left outside corner of the border.

• y (Numeric) (defaults to: 25) —

  The offset of the image from the upper-left outside corner of the border.

• inner_bevel (Numeric) (defaults to: 6) —

  The width of the inner shadows of the border.

• outer_bevel (Numeric) (defaults to: 6) —

  The width of the outer shadows of the border.

• color (Magick::Pixel, String) (defaults to: self.matte_color) —

  The border color.

Returns:

• (Magick::Image) —

  a new image.

# File 'ext/RMagick/rmimage.cpp', line 7235

VALUE
Image_frame(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    FrameInfo frame_info;

    image = rm_check_destroyed(self);

    frame_info.width = image->columns + 50;
    frame_info.height = image->rows + 50;
    frame_info.x = 25;
    frame_info.y = 25;
    frame_info.inner_bevel = 6;
    frame_info.outer_bevel = 6;

    switch (argc)
    {
        case 7:
            Color_to_PixelColor(&image->matte_color, argv[6]);
        case 6:
            frame_info.outer_bevel = NUM2LONG(argv[5]);
        case 5:
            frame_info.inner_bevel = NUM2LONG(argv[4]);
        case 4:
            frame_info.y = NUM2LONG(argv[3]);
        case 3:
            frame_info.x = NUM2LONG(argv[2]);
        case 2:
            frame_info.height = image->rows + 2*NUM2LONG(argv[1]);
        case 1:
            frame_info.width = image->columns + 2*NUM2LONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 7)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(FrameImage) args = { image, &frame_info, image->compose, exception };
#else
    GVL_STRUCT_TYPE(FrameImage) args = { image, &frame_info, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FrameImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#function_channel(function, *args, channel = Magick::AllChannels) ⇒ Magick::Image #function_channel(function, *args, *channels) ⇒ Magick::Image

Set the function on a channel.

Overloads:

• #function_channel(function, *args, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • function (Magick::MagickFunction) —

    the function

  • *args (Numeric) —

    One or more floating-point numbers. The number of parameters depends on the function. See the ImageMagick documentation for details.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #function_channel(function, *args, *channels) ⇒ Magick::Image

  Parameters:

  • function (Magick::MagickFunction) —

    the function

  • *args (Numeric) —

    One or more floating-point numbers. The number of parameters depends on the function. See the ImageMagick documentation for details.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• https://www.imagemagick.org/script/command-line-options.php#function

# File 'ext/RMagick/rmimage.cpp', line 7356

VALUE
Image_function_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickFunction function;
    unsigned long n, nparms;
    double *parms;
    ChannelType channels;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // The number of parameters depends on the function.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "no function specified");
    }

    VALUE_TO_ENUM(argv[0], function, MagickFunction);
    argc -= 1;
    argv += 1;

    switch (function)
    {
        case PolynomialFunction:
            if (argc == 0)
            {
                rb_raise(rb_eArgError, "PolynomialFunction requires at least one argument.");
            }
            break;
        case SinusoidFunction:
        case ArcsinFunction:
        case ArctanFunction:
           if (argc < 1 || argc > 4)
           {
               rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 4)", argc);
           }
           break;
        default:
            rb_raise(rb_eArgError, "undefined function");
            break;
    }

    nparms = argc;
    parms = ALLOC_N(double, nparms);

    for (n = 0; n < nparms; n++)
    {
        VALUE element = argv[n];
        if (rm_check_num2dbl(element))
        {
            parms[n] = NUM2DBL(element);
        }
        else
        {
            xfree(parms);
            rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
        }
    }

    exception = AcquireExceptionInfo();
    new_image = rm_clone_image(image);
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(FunctionImage) args = { new_image, function, nparms, parms, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FunctionImage), &args);
    END_CHANNEL_MASK(new_image);
#else
    GVL_STRUCT_TYPE(FunctionImageChannel) args = { new_image, channels, function, nparms, parms, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FunctionImageChannel), &args);
#endif
    xfree(parms);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#fuzz ⇒ Float

Get the number of algorithms search for a target color. By default the color must be exact. Use this attribute to match colors that are close to the target color in RGB space.

Returns:

• (Float) —

  the fuzz

See Also:

• Magick::Image::Info#fuzz

# File 'ext/RMagick/rmimage.cpp', line 7444

VALUE
Image_fuzz(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, fuzz, dbl, &rm_image_data_type);
}

#fuzz=(fuzz) ⇒ String, Numeric

Set the number of algorithms search for a target color.

Parameters:

• fuzz (String, Numeric) —

  The argument may be a floating-point numeric value or a string in the form "NN%".

Returns:

• (String, Numeric) —

  the given value

See Also:

• Magick::Image::Info#fuzz=

# File 'ext/RMagick/rmimage.cpp', line 7459

VALUE
Image_fuzz_eq(VALUE self, VALUE fuzz)
{
    Image *image = rm_check_frozen(self);
    image->fuzz = rm_fuzz_to_dbl(fuzz);
    return fuzz;
}

#fx(expression, channel = Magick::AllChannels) ⇒ Magick::Image #fx(expression, *channels) ⇒ Magick::Image

Apply fx on the image.

Overloads:

• #fx(expression, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • expression (String) —

    A mathematical expression

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #fx(expression, *channels) ⇒ Magick::Image

  Parameters:

  • expression (String) —

    A mathematical expression

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 7481

VALUE
Image_fx(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    char *expression;
    ChannelType channels;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There must be exactly 1 remaining argument.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (0 for 1 or more)");
    }
    else if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    expression = StringValueCStr(argv[0]);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(FxImage) args = { image, expression, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FxImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(FxImageChannel) args = { image, channels, expression, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FxImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#gamma ⇒ Float

Get the gamma level of the image.

Returns:

• (Float) —

  the gamma level

# File 'ext/RMagick/rmimage.cpp', line 7526

VALUE
Image_gamma(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, gamma, dbl, &rm_image_data_type);
}

#gamma=(val) ⇒ Numeric

Set the gamma level of the image.

Parameters:

• val (Numeric) —

  the gamma level

Returns:

• (Numeric) —

  the gamma level

# File 'ext/RMagick/rmimage.cpp', line 7538

VALUE
Image_gamma_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, gamma, dbl, &rm_image_data_type);
}

#gamma_channel(gamma, channel = Magick::AllChannels) ⇒ Magick::Image #gamma_channel(gamma, *channels) ⇒ Magick::Image

Apply gamma to a channel.

Overloads:

• #gamma_channel(gamma, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • Values —

    gamma [Numeric] 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 (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #gamma_channel(gamma, *channels) ⇒ Magick::Image

  Parameters:

  • Values —

    gamma [Numeric] typically range from 0.8 to 2.3. You can also reduce the influence of a particular channel with a gamma value of 0.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 7560

VALUE
Image_gamma_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    double gamma;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There must be exactly one remaining argument.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "missing gamma argument");
    }
    else if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    gamma = NUM2DBL(argv[0]);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(GammaImage) args = { new_image, gamma, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(GammaImageChannel) args = { new_image, channels, gamma };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#gamma_correct(red_gamma, green_gamma = red_gamma, blue_gamma = green_gamma) ⇒ Magick::Image

gamma-correct an image.

Returns a new image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 7610

VALUE
Image_gamma_correct(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double red_gamma, green_gamma, blue_gamma;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            red_gamma   = NUM2DBL(argv[0]);
            green_gamma = blue_gamma = red_gamma;
            break;
        case 2:
            red_gamma   = NUM2DBL(argv[0]);
            green_gamma = NUM2DBL(argv[1]);
            blue_gamma  = green_gamma;
            break;
        case 3:
        case 4:
            red_gamma     = NUM2DBL(argv[0]);
            green_gamma   = NUM2DBL(argv[1]);
            blue_gamma    = NUM2DBL(argv[2]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 3)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
#endif

    if ((red_gamma == green_gamma) && (green_gamma == blue_gamma))
    {
#if defined(IMAGEMAGICK_7)
        BEGIN_CHANNEL_MASK(new_image, (ChannelType) (RedChannel | GreenChannel | BlueChannel));
        GVL_STRUCT_TYPE(GammaImage) args = { new_image, red_gamma, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImage), &args);
        END_CHANNEL_MASK(new_image);
#else
        GVL_STRUCT_TYPE(GammaImageChannel) args = { new_image, (ChannelType) (RedChannel | GreenChannel | BlueChannel), red_gamma };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImageChannel), &args);
#endif
    }
    else
    {
#if defined(IMAGEMAGICK_7)
        BEGIN_CHANNEL_MASK(new_image, RedChannel);
        GVL_STRUCT_TYPE(GammaImage) args1 = { new_image, red_gamma, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImage), &args1);
        END_CHANNEL_MASK(new_image);

        BEGIN_CHANNEL_MASK(new_image, GreenChannel);
        GVL_STRUCT_TYPE(GammaImage) args2 = { new_image, green_gamma, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImage), &args2);
        END_CHANNEL_MASK(new_image);

        BEGIN_CHANNEL_MASK(new_image, BlueChannel);
        GVL_STRUCT_TYPE(GammaImage) args3 = { new_image, blue_gamma, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImage), &args3);
        END_CHANNEL_MASK(new_image);
#else
        GVL_STRUCT_TYPE(GammaImageChannel) args1 = { new_image, RedChannel, red_gamma };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImageChannel), &args1);

        GVL_STRUCT_TYPE(GammaImageChannel) args2 = { new_image, GreenChannel, green_gamma };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImageChannel), &args2);

        GVL_STRUCT_TYPE(GammaImageChannel) args3 = { new_image, BlueChannel, blue_gamma };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GammaImageChannel), &args3);
#endif
    }

#if defined(IMAGEMAGICK_7)
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#gaussian_blur(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Blur the image.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian operator.

• sigma (Numeric) (defaults to: 1.0) —

  The sigma (standard deviation) of the Gaussian operator.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 7708

VALUE
Image_gaussian_blur(int argc, VALUE *argv, VALUE self)
{
    return effect_image(self, argc, argv, GVL_FUNC(GaussianBlurImage));
}

#gaussian_blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #gaussian_blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

Blur the image on a channel.

Overloads:

• #gaussian_blur_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The sigma (standard deviation) of the Gaussian operator.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #gaussian_blur_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The sigma (standard deviation) of the Gaussian operator.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 7730

VALUE
Image_gaussian_blur_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    ExceptionInfo *exception;
    double radius = 0.0, sigma = 1.0;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There can be 0, 1, or 2 remaining arguments.
    switch (argc)
    {
        case 2:
            sigma = NUM2DBL(argv[1]);
            /* Fall thru */
        case 1:
            radius = NUM2DBL(argv[0]);
            /* Fall thru */
        case 0:
            break;
        default:
            raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(GaussianBlurImage) args = { image, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GaussianBlurImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
    rm_check_exception(exception, new_image, DestroyOnError);
#else
    GVL_STRUCT_TYPE(GaussianBlurImageChannel) args = { image, channels, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GaussianBlurImageChannel), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
#endif

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#geometry ⇒ String

Get the preferred size of the image when encoding.

Returns:

• (String) —

  the geometry

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 7782

VALUE
Image_geometry(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, geometry, str, &rm_image_data_type);
}

#geometry=(geometry) ⇒ Magick::Geometry, String

Set the preferred size of the image when encoding.

Parameters:

• geometry (Magick::Geometry, String) —

  the geometry

Returns:

• (Magick::Geometry, String) —

  the given geometry

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 7796

VALUE
Image_geometry_eq(VALUE self, VALUE geometry)
{
    Image *image;
    VALUE geom_str;
    char *geom;

    image = rm_check_frozen(self);

    if (geometry == Qnil)
    {
        magick_free(image->geometry);
        image->geometry = NULL;
        return self;
    }


    geom_str = rb_String(geometry);
    geom = StringValueCStr(geom_str);
    if (!IsGeometry(geom))
    {
        rb_raise(rb_eTypeError, "invalid geometry: %s", geom);
    }
    magick_clone_string(&image->geometry, geom);

    RB_GC_GUARD(geom_str);

    return geometry;
}

#get_exif_by_entry(*entry) ⇒ Object

Retrieve EXIF data by entry or all. If one or more entry names specified, return the values associated with the entries. If no entries specified, return all entries and values. The return value is an array of [name,value] arrays.

# File 'lib/rmagick_internal.rb', line 830

def get_exif_by_entry(*entry)
  ary = []
  if entry.empty?
    exif_data = self['EXIF:*']
    exif_data&.split("\n")&.each { |exif| ary.push(exif.split('=')) }
  else
    get_exif_by_entry # ensure properties is populated with exif data
    entry.each do |name|
      rval = self["EXIF:#{name}"]
      ary.push([name, rval])
    end
  end
  ary
end

#get_exif_by_number(*tag) ⇒ Object

Retrieve EXIF data by tag number or all tag/value pairs. The return value is a hash.

# File 'lib/rmagick_internal.rb', line 846

def get_exif_by_number(*tag)
  hash = {}
  if tag.empty?
    exif_data = self['EXIF:!']
    exif_data&.split("\n")&.each do |exif|
      tag, value = exif.split('=')
      tag = tag[1, 4].hex
      hash[tag] = value
    end
  else
    get_exif_by_number # ensure properties is populated with exif data
    tag.each do |num|
      rval = self[sprintf('#%04X', num.to_i)]
      hash[num] = rval == 'unknown' ? nil : rval
    end
  end
  hash
end

#get_iptc_dataset(ds) ⇒ Object

Retrieve IPTC information by record number:dataset tag constant defined in Magick::IPTC, above.

# File 'lib/rmagick_internal.rb', line 867

def get_iptc_dataset(ds)
  self['IPTC:' + ds]
end

#get_pixels(x_arg, y_arg, cols_arg, rows_arg) ⇒ Array<Magick::Pixel>

Gets the pixels from the specified rectangle within the image.

Parameters:

• x_arg (Numeric) —

  x position of start of region

• y_arg (Numeric) —

  y position of start of region

• cols_arg (Numeric) —

  width of region

• rows_arg (Numeric) —

  height of region

Returns:

• (Array<Magick::Pixel>) —

  An array of Magick::Pixel objects corresponding to the pixels in the rectangle defined by the geometry parameters.

See Also:

• #store_pixels

# File 'ext/RMagick/rmimage.cpp', line 7838

VALUE
Image_get_pixels(VALUE self, VALUE x_arg, VALUE y_arg, VALUE cols_arg, VALUE rows_arg)
{
    Image *image;
    ExceptionInfo *exception;
    long x, y;
    unsigned long columns, rows;
    long size, n;
    VALUE pixel_ary;
#if defined(IMAGEMAGICK_7)
    const Quantum *pixels;
#else
    const PixelPacket *pixels;
    const IndexPacket *indexes;
#endif

    image = rm_check_destroyed(self);
    x       = NUM2LONG(x_arg);
    y       = NUM2LONG(y_arg);
    columns = NUM2ULONG(cols_arg);
    rows    = NUM2ULONG(rows_arg);

    if ((x+columns) > image->columns || (y+rows) > image->rows)
    {
        rb_raise(rb_eRangeError, "geometry (%lux%lu%+ld%+ld) exceeds image bounds",
                 columns, rows, x, y);
    }

    // Cast AcquireImagePixels to get rid of the const qualifier. We're not going
    // to change the pixels but I don't want to make "pixels" const.
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(GetVirtualPixels) args = { image, x, y, columns, rows, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetVirtualPixels), &args);
    pixels = reinterpret_cast<decltype(pixels)>(ret);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    // If the function failed, return a 0-length array.
    if (!pixels)
    {
        return rb_ary_new();
    }

    // Allocate an array big enough to contain the PixelPackets.
    size = (long)(columns * rows);
    pixel_ary = rb_ary_new2(size);

#if defined(IMAGEMAGICK_6)
    indexes = GetVirtualIndexQueue(image);
#endif

    // Convert the PixelPackets to Magick::Pixel objects
    for (n = 0; n < size; n++)
    {
#if defined(IMAGEMAGICK_7)
        PixelPacket color;
        memset(&color, 0, sizeof(color));
        color.red   = GetPixelRed(image, pixels);
        color.green = GetPixelGreen(image, pixels);
        color.blue  = GetPixelBlue(image, pixels);
        color.alpha = GetPixelAlpha(image, pixels);
        color.black = GetPixelBlack(image, pixels);
        rb_ary_store(pixel_ary, n, Pixel_from_PixelPacket(&color));

        pixels += GetPixelChannels(image);
#else
        MagickPixel mpp;
        mpp.red = GetPixelRed(pixels);
        mpp.green = GetPixelGreen(pixels);
        mpp.blue = GetPixelBlue(pixels);
        mpp.opacity = GetPixelOpacity(pixels);
        if (indexes)
        {
            mpp.index = GetPixelIndex(indexes + n);
        }
        rb_ary_store(pixel_ary, n, Pixel_from_MagickPixel(&mpp));
        pixels++;
#endif
    }

    return pixel_ary;
}

#gravity ⇒ Magick::GravityType

Get the direction that the image gravitates within the composite.

Returns:

• (Magick::GravityType) —

  the image gravity

# File 'ext/RMagick/rmimage.cpp', line 15032

VALUE Image_gravity(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return GravityType_find(image->gravity);
}

#gravity=(gravity) ⇒ Magick::GravityType

Set the direction that the image gravitates within the composite.

Parameters:

• gravity (Magick::GravityType) —

  the image gravity

Returns:

• (Magick::GravityType) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 15045

VALUE Image_gravity_eq(VALUE self, VALUE gravity)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(gravity, image->gravity, GravityType);
    return gravity;
}

#gray? ⇒ Boolean

Return true if all the pixels in the image have the same red, green, and blue intensities.

Returns:

• (Boolean) —

  true if image is gray, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 7986

VALUE
Image_gray_q(VALUE self)
{
    return has_attribute(self, Image_is_gray_colorspace_type);
}

#grey? ⇒ Boolean

Return true if all the pixels in the image have the same red, green, and blue intensities.

Returns:

• (Boolean) —

  true if image is gray, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 7986

VALUE
Image_gray_q(VALUE self)
{
    return has_attribute(self, Image_is_gray_colorspace_type);
}

#histogram? ⇒ Boolean

Return true if has 1024 unique colors or less.

Returns:

• (Boolean) —

  true if image has <= 1024 unique colors

# File 'ext/RMagick/rmimage.cpp', line 7998

VALUE
Image_histogram_q(VALUE self)
{
    return has_attribute(self, IsHistogramImage);
}

#image_type ⇒ Magick::ImageType

Get the image type classification. For example, GrayscaleType. Don't confuse this attribute with the format, that is "GIF" or "JPG".

Returns:

• (Magick::ImageType) —

  the image type

# File 'ext/RMagick/rmimage.cpp', line 15060

VALUE Image_image_type(VALUE self)
{
    Image *image;
    ImageType type;
#if defined(IMAGEMAGICK_6)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
#if defined(IMAGEMAGICK_7)
    type = GetImageType(image);
#else
    exception = AcquireExceptionInfo();
    type = GetImageType(image, exception);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);
#endif

    return ImageType_find(type);
}

#image_type=(image_type) ⇒ Magick::ImageType

Set the image type classification.

Parameters:

• image_type (Magick::ImageType) —

  the image type

Returns:

• (Magick::ImageType) —

  the given type

# File 'ext/RMagick/rmimage.cpp', line 15089

VALUE Image_image_type_eq(VALUE self, VALUE image_type)
{
    Image *image;
    ImageType type;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);
    VALUE_TO_ENUM(image_type, type, ImageType);
#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    SetImageType(image, type, exception);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    SetImageType(image, type);
#endif
    return image_type;
}

#implode(amount = 0.50) ⇒ Magick::Image

Implode the image by the specified percentage.

Returns a new image.

Parameters:

• amount (Numeric) (defaults to: 0.50) —

  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:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 8013

VALUE
Image_implode(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double amount = 0.50;
    ExceptionInfo *exception;

    switch (argc)
    {
        case 1:
            amount = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
    }

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(ImplodeImage) args = { image, amount, image->interpolate, exception };
#else
    GVL_STRUCT_TYPE(ImplodeImage) args = { image, amount, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImplodeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#store_pixels(x, y, columns, rows, map, pixels, type = Magick::CharPixel) ⇒ Magick::Image

Store image pixel data from an array.

Returns self.

Parameters:

• x (Numeric) —

  The x-offset of the rectangle to be replaced.

• y (Numeric) —

  The y-offset of the rectangle to be replaced.

• columns (Numeric) —

  The number of columns in the rectangle.

• rows (Numeric) —

  The number of rows in the rectangle.

• map (String) —

  his string reflects the expected ordering of the pixel array.

• pixels (Array) —

  An array of pixels. The number of pixels in the array must be the same as the number of pixels in the rectangle, that is, rows*columns.

• type (Magick::StorageType) (defaults to: Magick::CharPixel) —

  A StorageType value that specifies the C datatype to which the pixel data will be converted.

Returns:

• (Magick::Image) —

  self

See Also:

• #export_pixels

# File 'ext/RMagick/rmimage.cpp', line 8063

VALUE
Image_import_pixels(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    long x_off, y_off;
    unsigned long cols, rows;
    unsigned long n, npixels;
    size_t buffer_l;
    char *map;
    VALUE pixel_arg, pixel_ary;
    StorageType stg_type = CharPixel;
    size_t type_sz, map_l;
    Quantum *pixels = NULL;
    double *fpixels = NULL;
    void *buffer;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

    switch (argc)
    {
        case 7:
            VALUE_TO_ENUM(argv[6], stg_type, StorageType);
        case 6:
            x_off = NUM2LONG(argv[0]);
            y_off = NUM2LONG(argv[1]);
            cols = NUM2ULONG(argv[2]);
            rows = NUM2ULONG(argv[3]);
            map = StringValueCStr(argv[4]);
            pixel_arg = argv[5];
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 6 or 7)", argc);
            break;
    }

    if (x_off < 0 || y_off < 0 || cols <= 0 || rows <= 0)
    {
        rb_raise(rb_eArgError, "invalid import geometry");
    }

    map_l = rm_strnlen_s(map, MaxTextExtent);
    npixels = cols * rows * map_l;

    // Assume that any object that responds to :to_str is a string buffer containing
    // binary pixel data.
    if (rb_respond_to(pixel_arg, rb_intern("to_str")))
    {
        buffer = (void *)rm_str2cstr(pixel_arg, &buffer_l);
        switch (stg_type)
        {
            case CharPixel:
                type_sz = 1;
                break;
            case ShortPixel:
                type_sz = sizeof(unsigned short);
                break;
            case LongPixel:
                type_sz = sizeof(unsigned long);
                break;
            case DoublePixel:
                type_sz = sizeof(double);
                break;
            case FloatPixel:
                type_sz = sizeof(float);
                break;
            case QuantumPixel:
                type_sz = sizeof(Quantum);
                break;
            default:
                rb_raise(rb_eArgError, "unsupported storage type %s", StorageType_name(stg_type));
                break;
        }

        if (buffer_l % type_sz != 0)
        {
            rb_raise(rb_eArgError, "pixel buffer must be an exact multiple of the storage type size");
        }
        if ((buffer_l / type_sz) % map_l != 0)
        {
            rb_raise(rb_eArgError, "pixel buffer must contain an exact multiple of the map length");
        }
        if ((unsigned long)(buffer_l / type_sz) < npixels)
        {
            rb_raise(rb_eArgError, "pixel buffer too small (need %lu channel values, got %" RMIuSIZE ")",
                     npixels, buffer_l/type_sz);
        }
    }
    // Otherwise convert the argument to an array and convert the array elements
    // to binary pixel data.
    else
    {
        // rb_Array converts an object that is not an array to an array if possible,
        // and raises TypeError if it can't. It usually is possible.
        pixel_ary = rb_Array(pixel_arg);

        if (RARRAY_LEN(pixel_ary) % map_l != 0)
        {
            rb_raise(rb_eArgError, "pixel array must contain an exact multiple of the map length");
        }
        if ((unsigned long)RARRAY_LEN(pixel_ary) < npixels)
        {
            rb_raise(rb_eArgError, "pixel array too small (need %lu elements, got %ld)",
                     npixels, RARRAY_LEN(pixel_ary));
        }

        if (stg_type == DoublePixel || stg_type == FloatPixel)
        {
            fpixels = ALLOC_N(double, npixels);
            for (n = 0; n < npixels; n++)
            {
                VALUE element = rb_ary_entry(pixel_ary, n);
                if (rm_check_num2dbl(element))
                {
                    fpixels[n] = NUM2DBL(element);
                }
                else
                {
                    xfree(fpixels);
                    rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
                }
            }
            buffer = (void *) fpixels;
            stg_type = DoublePixel;
        }
        else
        {
            pixels = ALLOC_N(Quantum, npixels);
            for (n = 0; n < npixels; n++)
            {
                VALUE element = rb_ary_entry(pixel_ary, n);
                if (rm_check_num2dbl(element))
                {
                    pixels[n] = NUM2DBL(element);
                }
                else
                {
                    xfree(pixels);
                    rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
                }
            }
            buffer = (void *) pixels;
            stg_type = QuantumPixel;
        }
    }


#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ImportImagePixels) args = { image, x_off, y_off, cols, rows, map, stg_type, buffer, exception };
#else
    GVL_STRUCT_TYPE(ImportImagePixels) args = { image, x_off, y_off, cols, rows, map, stg_type, buffer };
#endif
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImportImagePixels), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));

    // Free pixel array before checking for errors.
    if (pixels)
    {
        xfree((void *)pixels);
    }
    if (fpixels)
    {
        xfree((void *)fpixels);
    }

    if (!okay)
    {
#if defined(IMAGEMAGICK_7)
        CHECK_EXCEPTION();
        DestroyExceptionInfo(exception);
#else
        rm_check_image_exception(image, RetainOnError);
#endif
        // Shouldn't get here...
        rm_magick_error("ImportImagePixels failed with no explanation.");
    }
#if defined(IMAGEMAGICK_7)
    DestroyExceptionInfo(exception);
#endif

    RB_GC_GUARD(pixel_arg);
    RB_GC_GUARD(pixel_ary);

    return self;
}

#initialize_copy(orig) ⇒ Magick::Image

Initialize copy, clone, dup.

Parameters:

• orig (Magick::Image) —

  the source image

Returns:

• (Magick::Image) —

  self

See Also:

• #copy
• #clone
• #dup

# File 'ext/RMagick/rmimage.cpp', line 4978

VALUE
Image_init_copy(VALUE copy, VALUE orig)
{
    Image *image, *new_image;

    image = rm_check_destroyed(orig);
    new_image = rm_clone_image(image);
    UPDATE_DATA_PTR(copy, new_image);

    return copy;
}

#inspect ⇒ String

Override Object#inspect - return a string description of the image.

Returns:

• (String) —

  the string

# File 'ext/RMagick/rmimage.cpp', line 8401

VALUE
Image_inspect(VALUE self)
{
    Image *image;
    char buffer[MaxTextExtent];          // image description buffer

    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);
    if (!image)
    {
        return rb_str_new2("#<Magick::Image: (destroyed)>");
    }
    build_inspect_string(image, buffer, sizeof(buffer));
    return rb_str_new2(buffer);
}

#interlace ⇒ Magick::InterlaceType

Get the type of interlacing scheme (default NoInterlace). This option is used to specify the type of interlacing scheme for raw image formats such as RGB or YUV. NoInterlace means do not interlace, LineInterlace uses scanline interlacing, and PlaneInterlace uses plane interlacing. PartitionInterlace is like PlaneInterlace except the different planes are saved to individual files (e.g. image.R, image.G, and image.B).

Returns:

• (Magick::InterlaceType) —

  the interlace

# File 'ext/RMagick/rmimage.cpp', line 8427

VALUE
Image_interlace(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return InterlaceType_find(image->interlace);
}

#interlace=(interlace) ⇒ Magick::InterlaceType

Set the type of interlacing scheme.

Parameters:

• interlace (Magick::InterlaceType) —

  the interlace

Returns:

• (Magick::InterlaceType) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 8441

VALUE
Image_interlace_eq(VALUE self, VALUE interlace)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(interlace, image->interlace, InterlaceType);
    return interlace;
}

#iptc_profile ⇒ String^?

Return the IPTC profile as a String.

Returns:

• (String, nil) —

  the IPTC profile if it exists, otherwise nil

# File 'ext/RMagick/rmimage.cpp', line 8455

VALUE
Image_iptc_profile(VALUE self)
{
    Image *image;
    const StringInfo *profile;

    image = rm_check_destroyed(self);
    profile = GetImageProfile(image, "iptc");
    if (!profile)
    {
        return Qnil;
    }

    return rb_str_new((char *)profile->datum, (long)profile->length);

}

#iptc_profile=(profile) ⇒ String^?

Set the IPTC profile. The argument is a string.

Parameters:

• profile (String, nil) —

  the IPTC profile

Returns:

• (String, nil) —

  the given profile

# File 'ext/RMagick/rmimage.cpp', line 8480

VALUE
Image_iptc_profile_eq(VALUE self, VALUE profile)
{
    Image_delete_profile(self, rb_str_new2("iptc"));
    if (profile != Qnil)
    {
        set_profile(self, "iptc", profile);
    }
    return profile;
}

#iterations ⇒ Object

These are undocumented methods. The writer is called only by Image#iterations=. The reader is only used by the unit tests!

# File 'ext/RMagick/rmimage.cpp', line 8497

VALUE
Image_iterations(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, iterations, int, &rm_image_data_type);
}

#iterations=(val) ⇒ Object

do not document! Only used by Image#iterations=

# File 'ext/RMagick/rmimage.cpp', line 8502

VALUE
Image_iterations_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, iterations, int, &rm_image_data_type);
}

#level(black_point = 0.0, white_point = nil, gamma = nil) ⇒ Object

(Thanks to Al Evans for the suggestion.)

# File 'lib/rmagick_internal.rb', line 896

def level(black_point = 0.0, white_point = nil, gamma = nil)
  black_point = Float(black_point)

  white_point ||= Magick::QuantumRange - black_point
  white_point = Float(white_point)

  gamma_arg = gamma
  gamma ||= 1.0
  gamma = Float(gamma)

  if gamma.abs > 10.0 || white_point.abs <= 10.0 || white_point.abs < gamma.abs
    gamma, white_point = white_point, gamma
    white_point = Magick::QuantumRange - black_point unless gamma_arg
  end

  level2(black_point, white_point, gamma)
end

#level2(black_point = 0.0, white_point = Magick::QuantumRange, gamma = 1.0) ⇒ Magick::Image

Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range.

Returns a new image.

Parameters:

• black_point (Numeric) (defaults to: 0.0) —

  A black point level in the range 0 - QuantumRange.

• white_point (Numeric) (defaults to: Magick::QuantumRange) —

  A white point level in the range 0..QuantumRange.

• gamma (Numeric) (defaults to: 1.0) —

  A gamma correction in the range 0.0 - 10.0.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 8518

VALUE
Image_level2(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double black_point = 0.0, gamma_val = 1.0, white_point = (double)QuantumRange;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#else
    char level[50];
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 0:             // take all the defaults
            break;
        case 1:
            black_point = NUM2DBL(argv[0]);
            white_point = QuantumRange - black_point;
            break;
        case 2:
            black_point = NUM2DBL(argv[0]);
            white_point = NUM2DBL(argv[1]);
            break;
        case 3:
            black_point = NUM2DBL(argv[0]);
            white_point = NUM2DBL(argv[1]);
            gamma_val   = NUM2DBL(argv[2]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 3)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(LevelImage) args = { new_image, black_point, white_point, gamma_val, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    snprintf(level, sizeof(level), "%gx%g+%g", black_point, white_point, gamma_val);
    GVL_STRUCT_TYPE(LevelImage) args = { new_image, level };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#level_channel(aChannelType, black = 0.0, white = 1.0, gamma = Magick::QuantumRange) ⇒ Magick::Image

Similar to #level2 but applies to a single channel only.

Returns a new image.

Parameters:

• aChannelType (Magick::ChannelType) —

  A ChannelType value.

• black (Numeric) (defaults to: 0.0) —

  A black point level in the range 0..QuantumRange.

• white (Numeric) (defaults to: 1.0) —

  A white point level in the range 0..QuantumRange.

• gamma (Numeric) (defaults to: Magick::QuantumRange) —

  A gamma correction in the range 0.0 - 10.0.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #level2

# File 'ext/RMagick/rmimage.cpp', line 8582

VALUE
Image_level_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double black_point = 0.0, gamma_val = 1.0, white_point = (double)QuantumRange;
    ChannelType channel;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:             // take all the defaults
            break;
        case 2:
            black_point = NUM2DBL(argv[1]);
            white_point = QuantumRange - black_point;
            break;
        case 3:
            black_point = NUM2DBL(argv[1]);
            white_point = NUM2DBL(argv[2]);
            break;
        case 4:
            black_point = NUM2DBL(argv[1]);
            white_point = NUM2DBL(argv[2]);
            gamma_val   = NUM2DBL(argv[3]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 4)", argc);
            break;
    }

    VALUE_TO_ENUM(argv[0], channel, ChannelType);

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channel);
    GVL_STRUCT_TYPE(LevelImage) args = { new_image, black_point, white_point, gamma_val, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(LevelImageChannel) args = { new_image, channel, black_point, white_point, gamma_val };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#level_colors(black_color = "black", white_color = "white", invert = true, channel = Magick::AllChannels) ⇒ Magick::Image #level_colors(black_color = "black", white_color = "white", invert = true, *channels) ⇒ Magick::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.

Overloads:

• #level_colors(black_color = "black", white_color = "white", invert = true, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • black_color (Magick::Pixel, String) (defaults to: "black") —

    The color to be mapped to black

  • white_color (Magick::Pixel, String) (defaults to: "white") —

    The color to be mapped to white

  • invert (defaults to: true) —

    See the description above

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #level_colors(black_color = "black", white_color = "white", invert = true, *channels) ⇒ Magick::Image

  Parameters:

  • black_color (Magick::Pixel, String) (defaults to: "black") —

    The color to be mapped to black

  • white_color (Magick::Pixel, String) (defaults to: "white") —

    The color to be mapped to white

  • invert (defaults to: true) —

    See the description above

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 8656

VALUE
Image_level_colors(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickPixel black_color, white_color;
    ChannelType channels;
    MagickBooleanType invert = MagickTrue;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    rm_init_magickpixel(image, &white_color);
    rm_init_magickpixel(image, &black_color);

    switch (argc)
    {
        case 3:
            invert = (MagickBooleanType)RTEST(argv[2]);

        case 2:
            Color_to_MagickPixel(image, &white_color, argv[1]);
            Color_to_MagickPixel(image, &black_color, argv[0]);
            break;

        case 1:
            rm_set_magickpixel(&white_color, "white");
            Color_to_MagickPixel(image, &black_color, argv[0]);
            break;

        case 0:
            rm_set_magickpixel(&white_color, "white");
            rm_set_magickpixel(&black_color, "black");
            break;

        default:
            raise_ChannelType_error(argv[argc-1]);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(LevelImageColors) args = { new_image, &black_color, &white_color, invert, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelImageColors), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(LevelColorsImageChannel) args = { new_image, channels, &black_color, &white_color, invert };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelColorsImageChannel), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(new_image, DestroyOnError);
#endif
    if (!okay)
    {
        DestroyImage(new_image);
        rb_raise(rb_eRuntimeError, "LevelImageColors failed for unknown reason.");
    }

    return rm_image_new(new_image);
}

#levelize_channel(black_point, white_point = Magick::QuantumRange-black_point, gamma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #levelize_channel(black_point, white_point = Magick::QuantumRange-black_point, gamma = 1.0, *channels) ⇒ Magick::Image

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

Overloads:

• #levelize_channel(black_point, white_point = Magick::QuantumRange-black_point, gamma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • black (Numeric) —

    A black point level in the range 0..QuantumRange.

  • white (Numeric) —

    A white point level in the range 0..QuantumRange.

  • gamma (Numeric) (defaults to: 1.0) —

    A gamma correction in the range 0.0 - 10.0.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #levelize_channel(black_point, white_point = Magick::QuantumRange-black_point, gamma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • black (Numeric) —

    A black point level in the range 0..QuantumRange.

  • white (Numeric) —

    A white point level in the range 0..QuantumRange.

  • gamma (Numeric) (defaults to: 1.0) —

    A gamma correction in the range 0.0 - 10.0.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 8745

VALUE
Image_levelize_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    double black_point, white_point;
    double gamma = 1.0;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 3)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    switch (argc)
    {
        case 3:
            gamma = NUM2DBL(argv[2]);
        case 2:
            white_point = NUM2DBL(argv[1]);
            black_point = NUM2DBL(argv[0]);
            break;
        case 1:
            black_point = NUM2DBL(argv[0]);
            white_point = QuantumRange - black_point;
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or more)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(LevelizeImage) args = { new_image, black_point, white_point, gamma, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelizeImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(LevelizeImageChannel) args = { new_image, channels, black_point, white_point, gamma };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LevelizeImageChannel), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    if (!okay)
    {
        DestroyImage(new_image);
        rb_raise(rb_eRuntimeError, "LevelizeImageChannel failed for unknown reason.");
    }
    return rm_image_new(new_image);
}

#linear_stretch(black_point, white_point = pixels-black_point) ⇒ Magick::Image

Linear with saturation stretch.

Returns a new image.

Parameters:

• black_point (Numeric, String) —

  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 (Numeric, String) (defaults to: pixels-black_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 (columns * rows) - black_point.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #contrast_stretch_channel

# File 'ext/RMagick/rmimage.cpp', line 8822

VALUE
Image_linear_stretch(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double black_point, white_point;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    get_black_white_point(image, argc, argv, &black_point, &white_point);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(LinearStretchImage) args = { new_image, black_point, white_point, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LinearStretchImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(LinearStretchImage) args = { new_image, black_point, white_point };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LinearStretchImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#liquid_rescale(columns, rows, delta_x = 0.0, rigidity = 0.0) ⇒ Magick::Image

Rescale image with seam carving.

Returns a new image.

Parameters:

• columns (Numeric) —

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

• rows (Numeric) —

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

• delta_x (Numeric) (defaults to: 0.0) —

  Maximum seam transversal step (0 means straight seams).

• rigidity (Numeric) (defaults to: 0.0) —

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

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 8862

VALUE
Image_liquid_rescale(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    unsigned long cols, rows;
    double delta_x = 0.0;
    double rigidity = 0.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 4:
            rigidity = NUM2DBL(argv[3]);
        case 3:
            delta_x = NUM2DBL(argv[2]);
        case 2:
            rows = NUM2ULONG(argv[1]);
            cols = NUM2ULONG(argv[0]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 4)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(LiquidRescaleImage) args = { image, cols, rows, delta_x, rigidity, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(LiquidRescaleImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#magnify ⇒ Magick::Image

Scale an image proportionally to twice its size.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #magnify!

# File 'ext/RMagick/rmimage.cpp', line 9016

VALUE
Image_magnify(VALUE self)
{
    rm_check_destroyed(self);
    return magnify(False, self, GVL_FUNC(MagnifyImage));
}

#magnify! ⇒ Magick::Image

Scale an image proportionally to twice its size. In-place form of #magnify.

Returns:

• (Magick::Image) —

  self

See Also:

• #magnify

# File 'ext/RMagick/rmimage.cpp', line 9031

VALUE
Image_magnify_bang(VALUE self)
{
    rm_check_frozen(self);
    return magnify(True, self, GVL_FUNC(MagnifyImage));
}

#marshal_dump ⇒ Array<String>

Support Marshal.dump.

Returns:

• (Array<String>) —

  The first element in the array is the file name. The second element is the string of blob.

# File 'ext/RMagick/rmimage.cpp', line 9045

VALUE
Image_marshal_dump(VALUE self)
{
    Image *image;
    Info *info;
    unsigned char *blob;
    size_t length;
    VALUE ary;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    info = CloneImageInfo(NULL);
    if (!info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to initialize Info object");
    }

    ary = rb_ary_new2(2);
    rb_ary_store(ary, 0, rb_str_new2(image->filename));

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ImageToBlob) args = { info, image, &length, exception };
    blob = (unsigned char *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImageToBlob), &args);

    // Destroy info before raising an exception
    DestroyImageInfo(info);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);

    rb_ary_store(ary, 1, rb_str_new((char *)blob, (long)length));
    magick_free((void*)blob);

    return ary;
}

#marshal_load(ary) ⇒ Object

Support Marshal.load.

Parameters:

• ary (Array<String>) —

  the array returned from #marshal_dump

Returns:

• self

# File 'ext/RMagick/rmimage.cpp', line 9088

VALUE
Image_marshal_load(VALUE self, VALUE ary)
{
    VALUE blob, filename;
    Info *info;
    Image *image, *new_image;
    ExceptionInfo *exception;

    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);

    Check_Type(ary, T_ARRAY);

    filename = rb_ary_shift(ary);
    blob = rb_ary_shift(ary);

    filename = StringValue(filename);
    blob = StringValue(blob);

    info = CloneImageInfo(NULL);
    if (!info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to initialize Info object");
    }

    exception = AcquireExceptionInfo();
    if (filename != Qnil)
    {
        strlcpy(info->filename, RSTRING_PTR(filename), sizeof(info->filename));
    }
    GVL_STRUCT_TYPE(BlobToImage) args = { info, RSTRING_PTR(blob), (size_t)RSTRING_LEN(blob), exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BlobToImage), &args);

    // Destroy info before raising an exception
    DestroyImageInfo(info);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);

    UPDATE_DATA_PTR(self, new_image);
    rm_image_destroy(image);

    return self;
}

#mask ⇒ Magick::Image^? #mask(image) ⇒ Magick::Image^?

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

Overloads:

• #mask ⇒ Magick::Image^?

  Get an image clip mask.
• #mask(image) ⇒ Magick::Image^?

  Set an image clip mask.

  Parameters:

  • image (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

Returns:

• (Magick::Image, nil) —

  the mask image

# File 'ext/RMagick/rmimage.cpp', line 9325

VALUE
Image_mask(int argc, VALUE *argv, VALUE self)
{
    VALUE mask;
    Image *image;

    image = rm_check_destroyed(self);
    if (argc == 0)
    {
        return get_image_mask(image);
    }
    if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (expected 0 or 1, got %d)", argc);
    }

    rb_check_frozen(self);
    mask = argv[0];
    return set_image_mask(image, mask);
}

#matte_color ⇒ String

Return the matte color.

Returns:

• (String) —

  the matte color

# File 'ext/RMagick/rmimage.cpp', line 9352

VALUE
Image_matte_color(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return rm_pixelcolor_to_color_name(image, &image->matte_color);
}

#matte_color=(color) ⇒ Magick::Pixel, String

Set the matte color.

Parameters:

• color (Magick::Pixel, String) —

  the matte color

Returns:

• (Magick::Pixel, String) —

  the given color

# File 'ext/RMagick/rmimage.cpp', line 9365

VALUE
Image_matte_color_eq(VALUE self, VALUE color)
{
    Image *image = rm_check_frozen(self);
    Color_to_PixelColor(&image->matte_color, color);
    return color;
}

#matte_fill_to_border(x, y) ⇒ Object

Make transparent any neighbor pixel that is not the border color.

# File 'lib/rmagick_internal.rb', line 947

def matte_fill_to_border(x, y)
  f = copy
  f.alpha(OpaqueAlphaChannel) unless f.alpha?
  f.matte_flood_fill(border_color, x, y, FillToBorderMethod, alpha: TransparentAlpha)
end

#Image ⇒ Magick::Image

Makes transparent all the pixels that are the same color as the pixel at x, y, and are neighbors.

Returns a new image.

Parameters:

• color (Magick::Pixel, String) —

  the color name

• x_obj (Numeric) —

  x position

• y_obj (Numeric) —

  y position

• method_obj (Magick::PaintMethod) —

  which method to call: FloodfillMethod or FillToBorderMethod

• alpha (Numeric) —

  the alpha

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9385

VALUE
Image_matte_flood_fill(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    PixelColor target;
    Quantum alpha;
    long x, y;
    PaintMethod method;
    DrawInfo *draw_info;
    MagickPixel target_mpp;
    MagickBooleanType invert;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif
    VALUE color_obj, x_obj, y_obj, method_obj, kwargs;

    image = rm_check_destroyed(self);

    rb_scan_args(argc, argv, "4:", &color_obj, &x_obj, &y_obj, &method_obj, &kwargs);

    alpha = get_named_alpha_value(kwargs);

    Color_to_PixelColor(&target, color_obj);
    VALUE_TO_ENUM(method_obj, method, PaintMethod);
    if (!(method == FloodfillMethod || method == FillToBorderMethod))
    {
        rb_raise(rb_eArgError, "paint method_obj must be FloodfillMethod or "
                 "FillToBorderMethod (%d given)", method);
    }
    x = NUM2LONG(x_obj);
    y = NUM2LONG(y_obj);
    if ((unsigned long)x > image->columns || (unsigned long)y > image->rows)
    {
        rb_raise(rb_eArgError, "target out of range. %ldx%ld given, image is %" RMIuSIZE "x%" RMIuSIZE "",
                 x, y, image->columns, image->rows);
    }


    new_image = rm_clone_image(image);

    // FloodfillPaintImage looks for the opacity in the DrawInfo.fill field.
    draw_info = CloneDrawInfo(NULL, NULL);
    if (!draw_info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }
#if defined(IMAGEMAGICK_7)
    rm_set_pixelinfo_alpha(&draw_info->fill, alpha);
#else
    draw_info->fill.opacity = QuantumRange - alpha;
#endif

    if (method == FillToBorderMethod)
    {
        invert = MagickTrue;
        target_mpp.red   = (MagickRealType) image->border_color.red;
        target_mpp.green = (MagickRealType) image->border_color.green;
        target_mpp.blue  = (MagickRealType) image->border_color.blue;
#if defined(IMAGEMAGICK_7)
        rm_set_pixelinfo_alpha(&target_mpp, (MagickRealType) image->border_color.alpha);
#else
        target_mpp.opacity = (MagickRealType) image->border_color.opacity;
#endif
    }
    else
    {
        invert = MagickFalse;
        target_mpp.red   = (MagickRealType) target.red;
        target_mpp.green = (MagickRealType) target.green;
        target_mpp.blue  = (MagickRealType) target.blue;
#if defined(IMAGEMAGICK_7)
        rm_set_pixelinfo_alpha(&target_mpp, (MagickRealType) target.alpha);
#else
        target_mpp.opacity = (MagickRealType) target.opacity;
#endif
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, OpacityChannel);
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, draw_info, &target_mpp, x, y, invert, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);
    END_CHANNEL_MASK(new_image);
    DestroyDrawInfo(draw_info);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, OpacityChannel, draw_info, &target_mpp, x, y, invert };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);
    DestroyDrawInfo(draw_info);

    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#matte_floodfill(x, y) ⇒ Object

Make transparent any pixel that matches the color of the pixel at (x,y) and is a neighbor.

# File 'lib/rmagick_internal.rb', line 939

def matte_floodfill(x, y)
  f = copy
  f.alpha(OpaqueAlphaChannel) unless f.alpha?
  target = f.pixel_color(x, y)
  f.matte_flood_fill(target, x, y, FloodfillMethod, alpha: TransparentAlpha)
end

#matte_point(x, y) ⇒ Object

Make the pixel at (x,y) transparent.

# File 'lib/rmagick_internal.rb', line 919

def matte_point(x, y)
  f = copy
  f.alpha(OpaqueAlphaChannel) unless f.alpha?
  pixel = f.pixel_color(x, y)
  pixel.alpha = TransparentAlpha
  f.pixel_color(x, y, pixel)
  f
end

#matte_replace(x, y) ⇒ Object

Make transparent all pixels that are the same color as the pixel at (x, y).

# File 'lib/rmagick_internal.rb', line 930

def matte_replace(x, y)
  f = copy
  f.alpha(OpaqueAlphaChannel) unless f.alpha?
  target = f.pixel_color(x, y)
  f.transparent(target)
end

#matte_reset! ⇒ Object

Make all pixels transparent.

# File 'lib/rmagick_internal.rb', line 954

def matte_reset!
  alpha(TransparentAlphaChannel)
  self
end

#mean_error_per_pixel ⇒ Float

Get the mean error per pixel computed when a image is color reduced.

Returns:

• (Float) —

  the mean error per pixel

# File 'ext/RMagick/rmimage.cpp', line 9525

VALUE
Image_mean_error_per_pixel(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READERF(Image, mean_error_per_pixel, error.mean_error_per_pixel, dbl, &rm_image_data_type);
}

#median_filter(radius = 0.0) ⇒ Magick::Image

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

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The filter radius.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9491

VALUE
Image_median_filter(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius = 0.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            radius = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(StatisticImage) args = { image, MedianStatistic, (size_t)radius, (size_t)radius, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(StatisticImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#mime_type ⇒ String^?

Return the officially registered (or de facto) MIME media-type corresponding to the image format.

Returns:

• (String, nil) —

  the mime type

# File 'ext/RMagick/rmimage.cpp', line 9537

VALUE
Image_mime_type(VALUE self)
{
    Image *image;
    char *type;
    VALUE mime_type;

    image = rm_check_destroyed(self);
    type = MagickToMime(image->magick);
    if (!type)
    {
        return Qnil;
    }
    mime_type = rb_str_new2(type);

    // The returned string must be deallocated by the user.
    magick_free(type);

    RB_GC_GUARD(mime_type);

    return mime_type;
}

#minify ⇒ Magick::Image

Scale an image proportionally to half its size.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #minify!

# File 'ext/RMagick/rmimage.cpp', line 9567

VALUE
Image_minify(VALUE self)
{
    rm_check_destroyed(self);
    return magnify(False, self, GVL_FUNC(MinifyImage));
}

#minify! ⇒ Magick::Image

Scale an image proportionally to half its size. In-place form of #minify.

Returns:

• (Magick::Image) —

  self

See Also:

• #minify

# File 'ext/RMagick/rmimage.cpp', line 9581

VALUE
Image_minify_bang(VALUE self)
{
    rm_check_frozen(self);
    return magnify(True, self, GVL_FUNC(MinifyImage));
}

#modulate(brightness = 1.0, saturation = 1.0, hue = 1.0) ⇒ Magick::Image

Changes the brightness, saturation, and hue.

Returns a new image.

Parameters:

• brightness (Numeric, String) (defaults to: 1.0) —

  The percent change in the brightness. Must be a non-negative number or a string in the form "NN%".

• saturation (Numeric, String) (defaults to: 1.0) —

  The percent change in the saturation. Must be a number or a string in the form "NN%".

• hue (Numeric, String) (defaults to: 1.0) —

  The percent change in the hue. Must be a number or a string in the form "NN%".

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9601

VALUE
Image_modulate(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double pct_brightness = 100.0,
    pct_saturation = 100.0,
    pct_hue        = 100.0;
    char modulate[100];
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 3:
            pct_hue        = rm_percentage2(argv[2], 1.0, false) * 100.0;
        case 2:
            pct_saturation = rm_percentage2(argv[1], 1.0, false) * 100.0;
        case 1:
            pct_brightness = rm_percentage(argv[0], 1.0) * 100.0;
            break;
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 3)", argc);
            break;
    }

    if (pct_brightness <= 0.0)
    {
        rb_raise(rb_eArgError, "brightness is %g%%, must be positive", pct_brightness);
    }
    snprintf(modulate, sizeof(modulate), "%f%%,%f%%,%f%%", pct_brightness, pct_saturation, pct_hue);

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ModulateImage) args = { new_image, modulate, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ModulateImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(ModulateImage) args = { new_image, modulate };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ModulateImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#monochrome? ⇒ Boolean

Return true if all the pixels in the image have the same red, green, and blue intensities and the intensity is either 0 or QuantumRange.

Returns:

• (Boolean) —

  true if monochrome, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 9660

VALUE
Image_monochrome_q(VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return has_image_attribute(self, IsImageMonochrome);
#else
    return has_attribute(self, IsMonochromeImage);
#endif
}

#montage ⇒ String^?

Tile size and offset within an image montage. Only valid for montage images.

Returns:

• (String, nil) —

  the tile size and offset

# File 'ext/RMagick/rmimage.cpp', line 9676

VALUE
Image_montage(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, montage, str, &rm_image_data_type);
}

#morphology(method_v, iterations, kernel_v) ⇒ Magick::Image

Apply a user supplied kernel to the image according to the given mophology method.

Parameters:

• method_v (Magick::MorphologyMethod) —

  the morphology method

• iterations (Numeric) —

  apply the operation this many times (or no change). A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.

• kernel_v (Magick::KernelInfo) —

  morphology kernel to apply

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4670

VALUE
Image_morphology(VALUE self, VALUE method_v, VALUE iterations, VALUE kernel_v)
{
    static VALUE default_channels_const = 0;

    if(!default_channels_const)
    {
        default_channels_const = rb_const_get(Module_Magick, rb_intern("DefaultChannels"));
    }

    return Image_morphology_channel(self, default_channels_const, method_v, iterations, kernel_v);
}

#morphology_channel(channel_v, method_v, iterations_v, kernel_v) ⇒ Magick::Image

Apply a user supplied kernel to the image channel according to the given mophology method.

Parameters:

• channel_v (Magick::ChannelType) —

  a channel type

• method_v (Magick::MorphologyMethod) —

  the morphology method

• iterations_v (Numeric) —

  apply the operation this many times (or no change). A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.

• kernel_v (Magick::KernelInfo) —

  morphology kernel to apply

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 4696

VALUE
Image_morphology_channel(VALUE self, VALUE channel_v, VALUE method_v, VALUE iterations_v, VALUE kernel_v)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    MorphologyMethod method;
    ChannelType channel;
    KernelInfo *kernel;
    ssize_t iterations = NUM2LONG(iterations_v);;

    image = rm_check_destroyed(self);

    VALUE_TO_ENUM(method_v, method, MorphologyMethod);
    VALUE_TO_ENUM(channel_v, channel, ChannelType);

    if (TYPE(kernel_v) == T_STRING)
    {
        kernel_v = rb_class_new_instance(1, &kernel_v, Class_KernelInfo);
    }

    if (!rb_obj_is_kind_of(kernel_v, Class_KernelInfo))
    {
        rb_raise(rb_eArgError, "expected String or Magick::KernelInfo");
    }

    TypedData_Get_Struct(kernel_v, KernelInfo, &rm_kernel_info_data_type, kernel);

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channel);
    GVL_STRUCT_TYPE(MorphologyImage) args = { image, method, iterations, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(MorphologyImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(MorphologyImageChannel) args = { image, channel, method, iterations, kernel, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(MorphologyImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#motion_blur(radius = 0.0, sigma = 1.0, angle = 0.0) ⇒ Magick::Image

Simulate motion blur. Convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and motion_blur selects a suitable radius for you. Angle gives the angle of the blurring motion.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation

• angle (Numeric) (defaults to: 0.0) —

  The angle (in degrees)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9752

VALUE
Image_motion_blur(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return motion_blur(argc, argv, self, GVL_FUNC(MotionBlurImage));
}

#negate(grayscale = false) ⇒ Magick::Image

Negate the colors in the reference image. The grayscale option means that only grayscale values within the image are negated.

Returns a new image.

Parameters:

• grayscale (Boolean) (defaults to: false) —

  If the grayscale argument is true, only the grayscale values are negated.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9768

VALUE
Image_negate(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickBooleanType grayscale = MagickFalse;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    if (argc == 1)
    {
        grayscale = (MagickBooleanType)RTEST(argv[0]);
    }
    else if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(NegateImage) args = { new_image, grayscale, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(NegateImage) args = { new_image, grayscale };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#negate_channel(grayscale = false, channel = Magick::AllChannels) ⇒ Magick::Image #negate_channel(grayscale = false, *channels) ⇒ Magick::Image

Negate the colors on a particular channel. The grayscale option means that only grayscale values within the image are negated.

Overloads:

• #negate_channel(grayscale = false, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • grayscale (Boolean) (defaults to: false) —

    If the grayscale argument is true, only the grayscale values are negated.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #negate_channel(grayscale = false, *channels) ⇒ Magick::Image

  Parameters:

  • grayscale (Boolean) (defaults to: false) —

    If the grayscale argument is true, only the grayscale values are negated.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 9821

VALUE
Image_negate_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    MagickBooleanType grayscale = MagickFalse;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There can be at most 1 remaining argument.
    if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    else if (argc == 1)
    {
        grayscale = (MagickBooleanType)RTEST(argv[0]);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(NegateImage) args = { new_image, grayscale, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(NegateImageChannel) args = { new_image, channels, grayscale };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NegateImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#normalize ⇒ Magick::Image

Enhance the contrast of a color image by adjusting the pixels color to span the entire range of colors available.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10000

VALUE
Image_normalize(VALUE self)
{
    Image *image, *new_image;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(NormalizeImage) args = { new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NormalizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(NormalizeImage) args = { new_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NormalizeImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#normalize_channel(channel = Magick::AllChannels) ⇒ Magick::Image #normalize_channel(*channels) ⇒ Magick::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.

Overloads:

• #normalize_channel(channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #normalize_channel(*channels) ⇒ Magick::Image

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10039

VALUE
Image_normalize_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    // Ensure all arguments consumed.
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(NormalizeImage) args = { new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NormalizeImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(NormalizeImageChannel) args = { new_image, channels };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(NormalizeImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#normalized_maximum_error ⇒ Float

Get The normalized maximum error per pixel computed when an image is color reduced.

Returns:

• (Float) —

  the normalized maximum error

# File 'ext/RMagick/rmimage.cpp', line 10092

VALUE
Image_normalized_maximum_error(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READERF(Image, normalized_maximum_error, error.normalized_maximum_error, dbl, &rm_image_data_type);
}

#normalized_mean_error ⇒ Float

Get the normalized mean error per pixel computed when an image is color reduced.

Returns:

• (Float) —

  the normalized mean error

# File 'ext/RMagick/rmimage.cpp', line 10081

VALUE
Image_normalized_mean_error(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READERF(Image, normalized_mean_error, error.normalized_mean_error, dbl, &rm_image_data_type);
}

#number_colors ⇒ Integer

Return the number of unique colors in the image.

Returns:

• (Integer) —

  number of unique colors

# File 'ext/RMagick/rmimage.cpp', line 10104

VALUE
Image_number_colors(VALUE self)
{
    Image *image;
    ExceptionInfo *exception;
    size_t n = 0;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(GetNumberColors) args = { image, NULL, exception };
    n = (size_t)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetNumberColors), &args);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return ULONG2NUM(n);
}

#offset ⇒ Integer

Get the number of bytes to skip over when reading raw image.

Returns:

• (Integer) —

  the offset

# File 'ext/RMagick/rmimage.cpp', line 10129

VALUE
Image_offset(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, offset, long, &rm_image_data_type);
}

#offset=(val) ⇒ Numeric

Set the number of bytes to skip over when reading raw image.

Parameters:

• val (Numeric) —

  the offset

Returns:

• (Numeric) —

  the given offset

# File 'ext/RMagick/rmimage.cpp', line 10141

VALUE
Image_offset_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, offset, long, &rm_image_data_type);
}

#oil_paint(radius = 3.0) ⇒ Magick::Image

Apply a special effect filter that simulates an oil painting.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 3.0) —

  The radius of the Gaussian in pixels.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10155

VALUE
Image_oil_paint(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius = 3.0;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    double sigma = 1.0;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            radius = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(OilPaintImage) args = { image, radius, sigma, exception };
#else
    GVL_STRUCT_TYPE(OilPaintImage) args = { image, radius, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OilPaintImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#opaque(target, fill) ⇒ Magick::Image

Change any pixel that matches target with the color defined by fill.

• By default a pixel must match the specified target color exactly.
• Use #fuzz= to set the amount of tolerance acceptable to consider two colors as the same.

Parameters:

• target (Magick::Pixel, String) —

  the color name

• fill (Magick::Pixel, String) —

  the color for filling

Returns:

• (Magick::Image) —

  a new image

See Also:

• #fuzz=

# File 'ext/RMagick/rmimage.cpp', line 10204

VALUE
Image_opaque(VALUE self, VALUE target, VALUE fill)
{
    Image *image, *new_image;
    MagickPixel target_pp;
    MagickPixel fill_pp;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    // Allow color name or Pixel
    Color_to_MagickPixel(image, &target_pp, target);
    Color_to_MagickPixel(image, &fill_pp, fill);

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(OpaquePaintImage) args = { new_image, &target_pp, &fill_pp, MagickFalse, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OpaquePaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(OpaquePaintImageChannel) args = { new_image, DefaultChannels, &target_pp, &fill_pp, MagickFalse };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OpaquePaintImageChannel), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    if (!okay)
    {
        // Force exception
        DestroyImage(new_image);
        rm_ensure_result(NULL);
    }

    return rm_image_new(new_image);
}

#opaque? ⇒ Boolean

Returns true if all of the pixels in the receiver have an opacity value of OpaqueOpacity.

Returns:

• (Boolean) —

  true if opaque, false otherwise

# File 'ext/RMagick/rmimage.cpp', line 10351

VALUE
Image_opaque_q(VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return has_attribute(self, IsImageOpaque);
#else
    return has_attribute(self, IsOpaqueImage);
#endif
}

#opaque_channel(target, fill, invert = false, fuzz = self.fuzz, channel = Magick::AllChannels) ⇒ Magick::Image #opaque_channel(target, fill, invert, fuzz, *channels) ⇒ Magick::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.

Overloads:

• #opaque_channel(target, fill, invert = false, fuzz = self.fuzz, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • target (Magick::Pixel, String) —

    the color name

  • fill (Magick::Pixel, String) —

    the color for filling

  • invert (Boolean) (defaults to: false) —

    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 (Numeric) (defaults to: self.fuzz) —

    Colors within this distance are considered equal to the target color.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #opaque_channel(target, fill, invert, fuzz, *channels) ⇒ Magick::Image

  Parameters:

  • target (Magick::Pixel, String) —

    the color name

  • fill (Magick::Pixel, String) —

    the color for filling

  • invert (Boolean) —

    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 (Numeric) —

    Colors within this distance are considered equal to the target color.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10270

VALUE
Image_opaque_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickPixel target_pp, fill_pp;
    ChannelType channels;
    double keep, fuzz;
    MagickBooleanType okay, invert = MagickFalse;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 4)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    // Default fuzz value is image's fuzz attribute.
    fuzz = image->fuzz;

    switch (argc)
    {
        case 4:
            fuzz = NUM2DBL(argv[3]);
            if (fuzz < 0.0)
            {
                rb_raise(rb_eArgError, "fuzz must be >= 0.0 (%g given)", fuzz);
            }
        case 3:
            invert = (MagickBooleanType)RTEST(argv[2]);
        case 2:
            // Allow color name or Pixel
            Color_to_MagickPixel(image, &fill_pp, argv[1]);
            Color_to_MagickPixel(image, &target_pp, argv[0]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (got %d, expected 2 or more)", argc);
            break;
    }

    new_image = rm_clone_image(image);
    keep = new_image->fuzz;
    new_image->fuzz = fuzz;

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(OpaquePaintImage) args = { new_image, &target_pp, &fill_pp, invert, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OpaquePaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    END_CHANNEL_MASK(new_image);
    new_image->fuzz = keep;
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(OpaquePaintImageChannel) args = { new_image, channels, &target_pp, &fill_pp, invert };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OpaquePaintImageChannel), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));

    new_image->fuzz = keep;
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    if (!okay)
    {
        // Force exception
        DestroyImage(new_image);
        rm_ensure_result(NULL);
    }

    return rm_image_new(new_image);
}

#ordered_dither(threshold_map = '2x2') ⇒ Magick::Image

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

• Default threshold_map is '2x2'
• Order of threshold_map must be 2, 3, or 4.

Returns a new image.

Parameters:

• threshold_map (String, Numeric) (defaults to: '2x2') —

  the threshold

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10372

VALUE
Image_ordered_dither(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    int order;
    const char *threshold_map = "2x2";
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
    }
    if (argc == 1)
    {
        if (TYPE(argv[0]) == T_STRING)
        {
            threshold_map = StringValueCStr(argv[0]);
        }
        else
        {
            order = NUM2INT(argv[0]);
            if (order == 3)
            {
                threshold_map = "3x3";
            }
            else if (order == 4)
            {
                threshold_map = "4x4";
            }
            else if (order != 2)
            {
                rb_raise(rb_eArgError, "order must be 2, 3, or 4 (%d given)", order);
            }
        }
    }

    new_image = rm_clone_image(image);

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(OrderedDitherImage) args = { new_image, threshold_map, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OrderedDitherImage), &args);
#else
    GVL_STRUCT_TYPE(OrderedPosterizeImage) args = { new_image, threshold_map, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(OrderedPosterizeImage), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#orientation ⇒ Magick::OrientationType

Get the value of the Exif Orientation Tag.

Returns:

• (Magick::OrientationType) —

  the orientation

# File 'ext/RMagick/rmimage.cpp', line 10434

VALUE
Image_orientation(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return OrientationType_find(image->orientation);
}

#orientation=(orientation) ⇒ Magick::OrientationType

Set the orientation attribute.

Parameters:

• orientation (Magick::OrientationType) —

  the orientation

Returns:

• (Magick::OrientationType) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 10448

VALUE
Image_orientation_eq(VALUE self, VALUE orientation)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(orientation, image->orientation, OrientationType);
    return orientation;
}

#page ⇒ Magick::Rectangle

The page attribute getter.

Returns:

• (Magick::Rectangle) —

  the page rectangle

# File 'ext/RMagick/rmimage.cpp', line 10462

VALUE
Image_page(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return Import_RectangleInfo(&image->page);
}

#page=(rect) ⇒ Magick::Rectangle

The page attribute setter.

Parameters:

• rect (Magick::Rectangle) —

  the page rectangle

Returns:

• (Magick::Rectangle) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 10476

VALUE
Image_page_eq(VALUE self, VALUE rect)
{
    Image *image = rm_check_frozen(self);
    Export_RectangleInfo(&image->page, rect);
    return rect;
}

#paint_transparent(color, invert, fuzz, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

Changes the opacity value of all the pixels that match color to the value specified by opacity. If invert is true, changes the pixels that don't match color.

Returns a new image.

Parameters:

• color (Magick::Pixel, String) —

  the color name

• invert (Boolean) —

  If true, the target pixels are all the pixels that are not the target color.

• fuzz (Numeric) —

  By default the pixel must match exactly, but you can specify a tolerance level by passing a positive value.

• alpha (Numeric) (defaults to: Magick::TransparentAlpha) —

  The new alpha value, either an alpha value or a number between 0 and QuantumRange. The default is TransparentAlpha.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10499

VALUE
Image_paint_transparent(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickPixel color;
    Quantum alpha = TransparentAlpha;
    double keep, fuzz;
    MagickBooleanType okay, invert;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif
    VALUE color_obj, invert_obj, fuzz_obj, kwargs;

    image = rm_check_destroyed(self);

    rb_scan_args(argc, argv, "12:", &color_obj, &invert_obj, &fuzz_obj, &kwargs);

    Color_to_MagickPixel(image, &color, color_obj);
    invert = (invert_obj != Qnil) ? (MagickBooleanType)RTEST(invert_obj) : MagickFalse;
    fuzz = (fuzz_obj != Qnil) ? NUM2DBL(fuzz_obj) : image->fuzz;
    if (RTEST(kwargs))
    {
        alpha = get_named_alpha_value(kwargs);
    }

    new_image = rm_clone_image(image);

    // Use fuzz value from caller
    keep = new_image->fuzz;
    new_image->fuzz = fuzz;

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(TransparentPaintImage) args = { new_image, (const MagickPixel *)&color, alpha, invert, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    new_image->fuzz = keep;
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(TransparentPaintImage) args = { new_image, (const MagickPixel *)&color, (Quantum)(QuantumRange - alpha), invert };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    new_image->fuzz = keep;

    // Is it possible for TransparentPaintImage to silently fail?
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    if (!okay)
    {
        // Force exception
        DestroyImage(new_image);
        rm_ensure_result(NULL);
    }

    return rm_image_new(new_image);
}

#palette? ⇒ Boolean

Return true if the image is PseudoClass and has 256 unique colors or less.

Returns:

• (Boolean) —

  true if palette, otherwise false

# File 'ext/RMagick/rmimage.cpp', line 10564

VALUE
Image_palette_q(VALUE self)
{
#if defined(IMAGEMAGICK_7)
    return has_image_attribute(self, IsPaletteImage);
#else
    return has_attribute(self, IsPaletteImage);
#endif
}

#pixel_color(x, y) ⇒ Magick::Pixel #pixel_color(x, y, color) ⇒ Magick::Pixel

Get/set the color of the pixel at x, y.

Overloads:

• #pixel_color(x, y) ⇒ Magick::Pixel

  Get the color

  Parameters:

  • x (Numeric) —

    The x-coordinates of the pixel.

  • y (Numeric) —

    The y-coordinates of the pixel.

  Returns:

  • (Magick::Pixel) —

    the pixel at x, y.

• #pixel_color(x, y, color) ⇒ Magick::Pixel

  Set the color

  Parameters:

  • x (Numeric) —

    The x-coordinates of the pixel.

  • y (Numeric) —

    The y-coordinates of the pixel.

  • color (Magick::Pixel, String) —

    the color

  Returns:

  • (Magick::Pixel) —

    the old color at x, y.

# File 'ext/RMagick/rmimage.cpp', line 10607

VALUE
Image_pixel_color(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    Pixel new_color;
    PixelPacket old_color;
    ExceptionInfo *exception;
    long x, y;
    unsigned int set = False;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    Quantum *pixel;
    const Quantum *old_pixel;
#else
    PixelPacket *pixel;
    const PixelPacket *old_pixel;
    MagickPixel mpp;
    IndexPacket *indexes;
#endif

    memset(&old_color, 0, sizeof(old_color));

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 3:
            rb_check_frozen(self);
            set = True;
            // Replace with new color? The arg can be either a color name or
            // a Magick::Pixel.
            Color_to_Pixel(&new_color, argv[2]);
        case 2:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or 3)", argc);
            break;
    }

    x = NUM2LONG(argv[0]);
    y = NUM2LONG(argv[1]);

    // Get the color of a pixel
    if (!set)
    {
        exception = AcquireExceptionInfo();
        GVL_STRUCT_TYPE(GetVirtualPixels) args = { image, x, y, 1, 1, exception };
        void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetVirtualPixels), &args);
        old_pixel = reinterpret_cast<decltype(old_pixel)>(ret);
        CHECK_EXCEPTION();

        DestroyExceptionInfo(exception);

#if defined(IMAGEMAGICK_7)
        old_color.red   = GetPixelRed(image, old_pixel) + 0.5;
        old_color.green = GetPixelGreen(image, old_pixel) + 0.5;
        old_color.blue  = GetPixelBlue(image, old_pixel) + 0.5;
        old_color.alpha = GetPixelAlpha(image, old_pixel) + 0.5;
        old_color.black = GetPixelBlack(image, old_pixel) + 0.5;
        return Pixel_from_PixelPacket(&old_color);
#else
        old_color = *old_pixel;
        indexes = GetAuthenticIndexQueue(image);
        // PseudoClass
        if (image->storage_class == PseudoClass)
        {
            old_color = image->colormap[(unsigned long)*indexes];
        }
        if (!image->matte)
        {
            old_color.opacity = OpaqueOpacity;
        }

        rm_init_magickpixel(image, &mpp);
        mpp.red = GetPixelRed(&old_color);
        mpp.green = GetPixelGreen(&old_color);
        mpp.blue = GetPixelBlue(&old_color);
        mpp.opacity = GetPixelOpacity(&old_color);
        if (indexes)
        {
            mpp.index = GetPixelIndex(indexes);
        }
        return Pixel_from_MagickPixel(&mpp);
#endif
    }

    // ImageMagick segfaults if the pixel location is out of bounds.
    // Do what IM does and return the background color.
    if (x < 0 || y < 0 || (unsigned long)x >= image->columns || (unsigned long)y >= image->rows)
    {
        return Pixel_from_PixelColor(&image->background_color);
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
#endif

    if (image->storage_class == PseudoClass)
    {
#if defined(IMAGEMAGICK_7)
        GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, DirectClass, exception };
        void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
        okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
        CHECK_EXCEPTION();
        if (!okay)
        {
            DestroyExceptionInfo(exception);
            rb_raise(Class_ImageMagickError, "SetImageStorageClass failed. Can't set pixel color.");
        }
#else
        GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, DirectClass };
        void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
        okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
        rm_check_image_exception(image, RetainOnError);
        if (!okay)
        {
            rb_raise(Class_ImageMagickError, "SetImageStorageClass failed. Can't set pixel color.");
        }
#endif
    }

#if defined(IMAGEMAGICK_6)
    exception = AcquireExceptionInfo();
#endif

    GVL_STRUCT_TYPE(GetAuthenticPixels) args = { image, x, y, 1, 1, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetAuthenticPixels), &args);
    pixel = reinterpret_cast<decltype(pixel)>(ret);
    CHECK_EXCEPTION();

    if (pixel)
    {
#if defined(IMAGEMAGICK_7)
        old_color.red   = GetPixelRed(image, pixel) + 0.5;
        old_color.green = GetPixelGreen(image, pixel) + 0.5;
        old_color.blue  = GetPixelBlue(image, pixel) + 0.5;
        old_color.alpha = GetPixelAlpha(image, pixel) + 0.5;
        old_color.black = GetPixelBlack(image, pixel) + 0.5;

        SetPixelRed(image,   new_color.red,   pixel);
        SetPixelGreen(image, new_color.green, pixel);
        SetPixelBlue(image,  new_color.blue,  pixel);
        SetPixelAlpha(image, new_color.alpha, pixel);
        SetPixelBlack(image, new_color.black, pixel);
#else
        old_color = *pixel;
        indexes = GetAuthenticIndexQueue(image);
        if (!image->matte)
        {
            old_color.opacity = OpaqueOpacity;
        }

        SetPixelRed(pixel,     new_color.red);
        SetPixelGreen(pixel,   new_color.green);
        SetPixelBlue(pixel,    new_color.blue);
        SetPixelOpacity(pixel, new_color.opacity);
        if (indexes)
        {
            SetPixelIndex(indexes, new_color.black);
        }
#endif

        GVL_STRUCT_TYPE(SyncAuthenticPixels) args = { image, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SyncAuthenticPixels), &args);
        CHECK_EXCEPTION();
    }

    DestroyExceptionInfo(exception);

    return Pixel_from_PixelPacket(&old_color);
}

#pixel_interpolation_method ⇒ Magick::PixelInterpolateMethod

Get the "interpolate" field.

Returns:

• (Magick::PixelInterpolateMethod) —

  the interpolate field

See Also:

• #pixel_interpolation_method=

# File 'ext/RMagick/rmimage.cpp', line 10786

VALUE
Image_pixel_interpolation_method(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return PixelInterpolateMethod_find(image->interpolate);
}

#pixel_interpolation_method=(method) ⇒ Magick::PixelInterpolateMethod

Set the "interpolate" field.

Parameters:

• method (Magick::PixelInterpolateMethod) —

  the interpolate field

Returns:

• (Magick::PixelInterpolateMethod) —

  the given method

See Also:

• #pixel_interpolation_method

# File 'ext/RMagick/rmimage.cpp', line 10801

VALUE
Image_pixel_interpolation_method_eq(VALUE self, VALUE method)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(method, image->interpolate, PixelInterpolateMethod);
    return method;
}

#polaroid(angle = -5.0) ⇒ Magick::Image #polaroid(angle = -5.0) {|opt| ... } ⇒ Magick::Image

Produce an image that looks like a Polaroid instant picture. If the image has a "Caption" property, the value is used as a caption.

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.

Overloads:

• #polaroid(angle = -5.0) ⇒ Magick::Image

  Parameters:

  • angle (Numeric) (defaults to: -5.0) —

    The resulting image is rotated by this amount, measured in degrees.

• #polaroid(angle = -5.0) {|opt| ... } ⇒ Magick::Image

  If present a block, 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 options.shadow_color. To specify a different border color (that is, the color of the image border) use options.border_color. Both of these methods accept either a color name or a Pixel argument.

  Parameters:

  • angle (Numeric) (defaults to: -5.0) —

    The resulting image is rotated by this amount, measured in degrees.

  Yields:

  • (opt)

  Yield Parameters:

  • opt (Magick::Image::PolaroidOptions)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10834

VALUE
Image_polaroid(int argc, VALUE *argv, VALUE self)
{
    Image *image, *clone, *new_image;
    VALUE options;
    double angle = -5.0;
    Draw *draw;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    const char *caption;
#endif

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 1:
            angle = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    options = rm_polaroid_new();
    TypedData_Get_Struct(options, Draw, &rm_draw_data_type, draw);

    clone = rm_clone_image(image);
    clone->background_color = draw->shadow_color;
    clone->border_color = draw->info->border_color;

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    caption = GetImageProperty(clone, "Caption", exception);
    GVL_STRUCT_TYPE(PolaroidImage) args = { clone, draw->info, caption, angle, image->interpolate, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(PolaroidImage), &args);
#else
    GVL_STRUCT_TYPE(PolaroidImage) args = { clone, draw->info, angle, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(PolaroidImage), &args);
#endif
    rm_check_exception(exception, clone, DestroyOnError);

    DestroyImage(clone);
    DestroyExceptionInfo(exception);

    RB_GC_GUARD(options);

    return rm_image_new(new_image);
}

#posterize(levels = 4, dither = false) ⇒ Object

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

Returns a new image.

Parameters:

• levels (Numeric) (defaults to: 4) —

  number of input arguments

• dither (Boolean) (defaults to: false) —

  array of input arguments

Returns:

• a new image

# File 'ext/RMagick/rmimage.cpp', line 10894

VALUE
Image_posterize(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickBooleanType dither = MagickFalse;
    unsigned long levels = 4;
#if defined(IMAGEMAGICK_7)
    DitherMethod dither_method;
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 2:
            dither = (MagickBooleanType) RTEST(argv[1]);
            /* fall through */
        case 1:
            levels = NUM2ULONG(argv[0]);
            /* fall through */
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 2)", argc);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    dither_method = dither ? RiemersmaDitherMethod : NoDitherMethod;
    GVL_STRUCT_TYPE(PosterizeImage) args = { new_image, levels, dither_method, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(PosterizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(PosterizeImage) args = { new_image, levels, dither };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(PosterizeImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#preview(preview) ⇒ Magick::Image

Creates an image that contains 9 small versions of the receiver image. The center image is the unchanged receiver. The other 8 images are variations created by transforming the receiver according to the specified preview type with varying parameters.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 10946

VALUE
Image_preview(VALUE self, VALUE preview)
{
    Image *image, *new_image;
    PreviewType preview_type;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    VALUE_TO_ENUM(preview, preview_type, PreviewType);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(PreviewImage) args = { image, preview_type, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(PreviewImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#profile!(name, profile) ⇒ Magick::Image

Set the image profile. If "profile" is nil, deletes the profile. Otherwise "profile" must be a string containing the specified profile.

Parameters:

• name (String, nil) —

  The profile name, or "*" to represent all the profiles in the image.

• profile (String) —

  The profile value, or nil to cause the profile to be removed.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 10975

VALUE
Image_profile_bang(VALUE self, VALUE name, VALUE profile)
{

    if (profile == Qnil)
    {
        return Image_delete_profile(self, name);
    }
    else
    {
        return set_profile(self, StringValueCStr(name), profile);
    }

}

#properties ⇒ Hash<String, String> #properties {|property, value| ... } ⇒ Magick::Image

If called with an associated block, properties runs the block once for each property defined for the image. The block arguments are the property name and its value. If there is no block, properties returns a hash with one element for each property. The hash key is the property name and the associated value is the property value.

Overloads:

• #properties ⇒ Hash<String, String>

  Returns the properties.

  Returns:

  • (Hash<String, String>) —

    the properties

• #properties {|property, value| ... } ⇒ Magick::Image

  Returns self.

  Yields:

  • (property, value)

  Yield Parameters:

  • property (String) —

    property key

  • value (String) —

    property value

  Returns:

  • (Magick::Image) —

    self

# File 'ext/RMagick/rmimage.cpp', line 12865

VALUE
Image_properties(VALUE self)
{
    Image *image;
    VALUE attr_hash, ary;
    const char *property, *value;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
#endif

    if (rb_block_given_p())
    {
        long i;

        // Collect the properties first so that neither the ExceptionInfo nor
        // the property iterator is held across rb_yield. The block may break
        // or raise, which would otherwise leak the ExceptionInfo.
        ary = rb_ary_new();

        ResetImagePropertyIterator(image);
        property = GetNextImageProperty(image);
        while (property)
        {
#if defined(IMAGEMAGICK_7)
            value = GetImageProperty(image, property, exception);
#else
            value = GetImageProperty(image, property);
#endif
            rb_ary_push(ary, rb_assoc_new(rb_str_new2(property), value ? rb_str_new2(value) : Qnil));
            property = GetNextImageProperty(image);
        }
#if defined(IMAGEMAGICK_7)
        CHECK_EXCEPTION();
        DestroyExceptionInfo(exception);
#else
        rm_check_image_exception(image, RetainOnError);
#endif

        for (i = 0; i < RARRAY_LEN(ary); i++)
        {
            rb_yield(rb_ary_entry(ary, i));
        }

        RB_GC_GUARD(ary);

        return self;
    }

    // otherwise return properties hash
    else
    {
        attr_hash = rb_hash_new();
        ResetImagePropertyIterator(image);
        property = GetNextImageProperty(image);
        while (property)
        {
#if defined(IMAGEMAGICK_7)
            value = GetImageProperty(image, property, exception);
#else
            value = GetImageProperty(image, property);
#endif
            rb_hash_aset(attr_hash, rb_str_new2(property), value ? rb_str_new2(value) : Qnil);
            property = GetNextImageProperty(image);
        }
#if defined(IMAGEMAGICK_7)
        CHECK_EXCEPTION();
        DestroyExceptionInfo(exception);
#else
        rm_check_image_exception(image, RetainOnError);
#endif

        RB_GC_GUARD(attr_hash);

        return attr_hash;
    }

}

#quality ⇒ Integer

Get image quality.

Returns:

• (Integer) —

  the quality

# File 'ext/RMagick/rmimage.cpp', line 10996

VALUE
Image_quality(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, quality, ulong, &rm_image_data_type);
}

#quantize(number_colors = 256, colorspace = Magick::RGBColorspace, dither = true, tree_depth = 0, measure_error = false) ⇒ Magick::Image

Analyzes the colors within a reference image and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the difference between the input and output image while minimizing the processing time.

Returns a new image.

Parameters:

• number_colors (Numeric) (defaults to: 256) —

  The maximum number of colors in the result image.

• colorspace (Magick::ColorspaceType) (defaults to: Magick::RGBColorspace) —

  The colorspace to quantize in.

• dither (Boolean) (defaults to: true) —

  If true, Magick::RiemersmaDitherMethod will be used as DitherMethod. otherwise NoDitherMethod.

• tree_depth (Numeric) (defaults to: 0) —

  The tree depth to use while quantizing. The values 0 and 1 support automatic tree depth determination. The tree depth may be forced via values ranging from 2 to 8. The ideal tree depth depends on the characteristics of the input image, and may be determined through experimentation.

• measure_error (Boolean) (defaults to: false) —

  Set to true to calculate quantization errors when quantizing the image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11216

VALUE
Image_quantize(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    QuantizeInfo quantize_info;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    GetQuantizeInfo(&quantize_info);

    switch (argc)
    {
        case 5:
            quantize_info.measure_error = (MagickBooleanType) RTEST(argv[4]);
        case 4:
            quantize_info.tree_depth = NUM2UINT(argv[3]);
        case 3:
            if (rb_obj_is_kind_of(argv[2], Class_DitherMethod))
            {
                VALUE_TO_ENUM(argv[2], quantize_info.dither_method, DitherMethod);
#if defined(IMAGEMAGICK_6)
                quantize_info.dither = (MagickBooleanType)(quantize_info.dither_method != NoDitherMethod);
#endif
            }
            else
            {
#if defined(IMAGEMAGICK_7)
                quantize_info.dither_method = RTEST(argv[2]) ? RiemersmaDitherMethod : NoDitherMethod;
#else
                quantize_info.dither = (MagickBooleanType) RTEST(argv[2]);
#endif
            }
        case 2:
            VALUE_TO_ENUM(argv[1], quantize_info.colorspace, ColorspaceType);
        case 1:
            quantize_info.number_colors = NUM2UINT(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 5)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(QuantizeImage) args = { &quantize_info, new_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(QuantizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(QuantizeImage) args = { &quantize_info, new_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(QuantizeImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#quantum_depth ⇒ Integer

Return the image depth to the nearest Quantum (8, 16, or 32).

Returns:

• (Integer) —

  image depth

# File 'ext/RMagick/rmimage.cpp', line 11008

VALUE
Image_quantum_depth(VALUE self)
{
    Image *image;
    unsigned long quantum_depth;

    image = rm_check_destroyed(self);
    quantum_depth = GetImageQuantumDepth(image, MagickFalse);

    return ULONG2NUM(quantum_depth);
}

#quantum_operator(quantum_expression_op, rvalue, channel = Magick::AllChannels) ⇒ Magick::Image #quantum_operator(quantum_expression_op, rvalue, *channels) ⇒ Magick::Image

Performs the requested integer arithmetic operation on the selected channel of the image. This method allows simple arithmetic operations on the component values of all pixels in an image. Of course, you could also do this in Ruby using get_pixels and store_pixels, or view, but quantum_operator will be faster, especially for large numbers of pixels, since it does not need to convert the pixels from C to Ruby.

Overloads:

• #quantum_operator(quantum_expression_op, rvalue, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • quantum_expression_op (Magick::QuantumExpressionOperator) —

    the operator

  • rvalue (Numeric) —

    the operation rvalue.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #quantum_operator(quantum_expression_op, rvalue, *channels) ⇒ Magick::Image

  Parameters:

  • quantum_expression_op (Magick::QuantumExpressionOperator) —

    the operator

  • rvalue (Numeric) —

    the operation rvalue.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 11041

VALUE
Image_quantum_operator(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    QuantumExpressionOperator quantum_expression_op;
    MagickEvaluateOperator qop;
    double rvalue;
    ChannelType channel;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    // The default channel is AllChannels
    channel = AllChannels;

    /*
        If there are 3 arguments, argument 2 is a ChannelType argument.
        Arguments 1 and 0 are required and are the rvalue and operator,
        respectively.
    */
    switch (argc)
    {
        case 3:
            VALUE_TO_ENUM(argv[2], channel, ChannelType);
            /* Fall through */
        case 2:
            rvalue = NUM2DBL(argv[1]);
            VALUE_TO_ENUM(argv[0], quantum_expression_op, QuantumExpressionOperator);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 or 3)", argc);
            break;
    }

    // Map QuantumExpressionOperator to MagickEvaluateOperator
    switch (quantum_expression_op)
    {
        default:
        case UndefinedQuantumOperator:
            qop = UndefinedEvaluateOperator;
            break;
        case AddQuantumOperator:
            qop = AddEvaluateOperator;
            break;
        case AndQuantumOperator:
            qop = AndEvaluateOperator;
            break;
        case DivideQuantumOperator:
            qop = DivideEvaluateOperator;
            break;
        case LShiftQuantumOperator:
            qop = LeftShiftEvaluateOperator;
            break;
        case MaxQuantumOperator:
            qop = MaxEvaluateOperator;
            break;
        case MinQuantumOperator:
            qop = MinEvaluateOperator;
            break;
        case MultiplyQuantumOperator:
            qop = MultiplyEvaluateOperator;
            break;
        case OrQuantumOperator:
            qop = OrEvaluateOperator;
            break;
        case RShiftQuantumOperator:
            qop = RightShiftEvaluateOperator;
            break;
        case SubtractQuantumOperator:
            qop = SubtractEvaluateOperator;
            break;
        case XorQuantumOperator:
            qop = XorEvaluateOperator;
            break;
        case PowQuantumOperator:
            qop = PowEvaluateOperator;
            break;
        case LogQuantumOperator:
            qop = LogEvaluateOperator;
            break;
        case ThresholdQuantumOperator:
            qop = ThresholdEvaluateOperator;
            break;
        case ThresholdBlackQuantumOperator:
            qop = ThresholdBlackEvaluateOperator;
            break;
        case ThresholdWhiteQuantumOperator:
            qop = ThresholdWhiteEvaluateOperator;
            break;
        case GaussianNoiseQuantumOperator:
            qop = GaussianNoiseEvaluateOperator;
            break;
        case ImpulseNoiseQuantumOperator:
            qop = ImpulseNoiseEvaluateOperator;
            break;
        case LaplacianNoiseQuantumOperator:
            qop = LaplacianNoiseEvaluateOperator;
            break;
        case MultiplicativeNoiseQuantumOperator:
            qop = MultiplicativeNoiseEvaluateOperator;
            break;
        case PoissonNoiseQuantumOperator:
            qop = PoissonNoiseEvaluateOperator;
            break;
        case UniformNoiseQuantumOperator:
            qop = UniformNoiseEvaluateOperator;
            break;
        case CosineQuantumOperator:
            qop = CosineEvaluateOperator;
            break;
        case SetQuantumOperator:
            qop = SetEvaluateOperator;
            break;
        case SineQuantumOperator:
            qop = SineEvaluateOperator;
            break;
        case AddModulusQuantumOperator:
            qop = AddModulusEvaluateOperator;
            break;
        case MeanQuantumOperator:
            qop = MeanEvaluateOperator;
            break;
        case AbsQuantumOperator:
            qop = AbsEvaluateOperator;
            break;
        case ExponentialQuantumOperator:
            qop = ExponentialEvaluateOperator;
            break;
        case MedianQuantumOperator:
            qop = MedianEvaluateOperator;
            break;
        case SumQuantumOperator:
            qop = SumEvaluateOperator;
            break;
        case RootMeanSquareQuantumOperator:
            qop = RootMeanSquareEvaluateOperator;
            break;
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channel);
    GVL_STRUCT_TYPE(EvaluateImage) args = { image, qop, rvalue, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EvaluateImage), &args);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(EvaluateImageChannel) args = { image, channel, qop, rvalue, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(EvaluateImageChannel), &args);
#endif
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return self;
}

#radial_blur(angle_obj) ⇒ Magick::Image

Applies a radial blur to the image.

Parameters:

• angle_obj (Numeric) —

  the angle (in degrees)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11285

VALUE
Image_radial_blur(VALUE self, VALUE angle_obj)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    double angle = NUM2DBL(angle_obj);

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(RotationalBlurImage) args = { image, angle, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RotationalBlurImage), &args);
    new_image = reinterpret_cast<decltype(new_image)>(ret);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#radial_blur_channel(angle, channel = Magick::AllChannels) ⇒ Magick::Image #radial_blur_channel(angle, *channels) ⇒ Magick::Image

Applies a radial blur to the selected image channels.

Overloads:

• #radial_blur_channel(angle, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • angle (Numeric) —

    the angle (in degrees)

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #radial_blur_channel(angle, *channels) ⇒ Magick::Image

  Parameters:

  • angle (Numeric) —

    the angle (in degrees)

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11318

VALUE
Image_radial_blur_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    ChannelType channels;
    double angle;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There must be 1 remaining argument.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (0 for 1 or more)");
    }
    else if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    angle = NUM2DBL(argv[0]);
    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(RotationalBlurImage) args = { image, angle, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RotationalBlurImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(RotationalBlurImageChannel) args = { image, channels, angle, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RotationalBlurImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#raise(width = 6, height = 6, raised = true) ⇒ Magick::Image

Create a simulated three-dimensional button-like effect by lightening and darkening the edges of the image. The "width" and "height" arguments define the width of the vertical and horizontal edge of the effect. If "raised" is true, creates a raised effect, otherwise a lowered effect.

Returns a new image.

Parameters:

• width (Numeric) (defaults to: 6) —

  The width of the raised edge in pixels.

• height (Numeric) (defaults to: 6) —

  The height of the raised edge in pixels.

• raised (Boolean) (defaults to: true) —

  If true, the image is raised, otherwise lowered.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11449

VALUE
Image_raise(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    RectangleInfo rect;
    MagickBooleanType raised = MagickTrue;      // default
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    memset(&rect, 0, sizeof(rect));
    rect.width = 6;         // default
    rect.height = 6;        // default

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 3:
            raised = (MagickBooleanType)RTEST(argv[2]);
        case 2:
            rect.height = NUM2ULONG(argv[1]);
        case 1:
            rect.width = NUM2ULONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 3)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(RaiseImage) args = { new_image, &rect, raised, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RaiseImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(RaiseImage) args = { new_image, &rect, raised };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RaiseImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#random_threshold_channel(geometry_str, channel = Magick::AllChannels) ⇒ Magick::Image #random_threshold_channel(geometry_str, *channels) ⇒ Magick::Image

Changes the value of individual pixels based on the intensity of each pixel compared to a random threshold. The result is a low-contrast, two color image.

Overloads:

• #random_threshold_channel(geometry_str, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • geometry_str (Magick::Geometry, String) —

    A geometry string containing LOWxHIGH thresholds.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #random_threshold_channel(geometry_str, *channels) ⇒ Magick::Image

  Parameters:

  • geometry_str (Magick::Geometry, String) —

    A geometry string containing LOWxHIGH thresholds.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

See Also:

• https://www.imagemagick.org/Magick++/Geometry.html

# File 'ext/RMagick/rmimage.cpp', line 11374

VALUE
Image_random_threshold_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    char *thresholds;
    VALUE geom_str;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    channels = extract_channels(&argc, argv);

    // There must be 1 remaining argument.
    if (argc == 0)
    {
        rb_raise(rb_eArgError, "missing threshold argument");
    }
    else if (argc > 1)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    // Accept any argument that has a to_s method.
    geom_str = rb_String(argv[0]);
    thresholds = StringValueCStr(geom_str);

    new_image = rm_clone_image(image);

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    {
        GeometryInfo geometry_info;

        if (ParseGeometry(thresholds, &geometry_info) == NoValue && *thresholds)
        {
            (void) ThrowMagickException(exception, GetMagickModule(), OptionError,
                                        "InvalidArgument", "'%s'", thresholds);
        }
        else
        {
            BEGIN_CHANNEL_MASK(new_image, channels);
            {
                GVL_STRUCT_TYPE(RandomThresholdImage) args = { new_image, geometry_info.rho, geometry_info.sigma, exception };
                CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RandomThresholdImage), &args);
            }
            END_CHANNEL_MASK(new_image);
        }
    }
#else
    GVL_STRUCT_TYPE(RandomThresholdImageChannel) args = { new_image, channels, thresholds, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RandomThresholdImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    RB_GC_GUARD(geom_str);

    return rm_image_new(new_image);
}

#recolor(color_matrix) ⇒ Magick::Image

Use this method to translate, scale, shear, or rotate image colors. Although you can use variable sized matrices, typically you use a 5x5 for an RGBA image and a 6x6 for CMYKA. Populate the last row with normalized values to translate.

Parameters:

• color_matrix (Array<Numeric>) —

  An array of Float values representing the recolor matrix.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11639

VALUE
Image_recolor(VALUE self, VALUE color_matrix)
{
    Image *image, *new_image;
    unsigned long order;
    long x, len;
    double *matrix;
    ExceptionInfo *exception;
    KernelInfo *kernel_info;

    image = rm_check_destroyed(self);
    color_matrix = rm_check_ary_type(color_matrix);

    // Allocate color matrix from Ruby's memory
    len = RARRAY_LEN(color_matrix);
    matrix = ALLOC_N(double, len);

    for (x = 0; x < len; x++)
    {
        VALUE element = rb_ary_entry(color_matrix, x);
        if (rm_check_num2dbl(element))
        {
            matrix[x] = NUM2DBL(element);
        }
        else
        {
            xfree(matrix);
            rb_raise(rb_eTypeError, "type mismatch: %s given", rb_class2name(CLASS_OF(element)));
        }
    }

    order = (unsigned long)sqrt((double)(len + 1.0));

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    kernel_info = AcquireKernelInfo(NULL, exception);
    if (rm_should_raise_exception(exception, RetainExceptionRetention))
    {
        if (kernel_info != (KernelInfo *) NULL)
        {
            DestroyKernelInfo(kernel_info);
        }
        xfree((void *)matrix);
        rm_raise_exception(exception);
    }
#else
    kernel_info = AcquireKernelInfo(NULL);
#endif
    if (kernel_info == (KernelInfo *) NULL)
    {
        xfree((void *) matrix);
        DestroyExceptionInfo(exception);
        return Qnil;
    }
    kernel_info->width = order;
    kernel_info->height = order;
    kernel_info->values = (double *) matrix;

    GVL_STRUCT_TYPE(ColorMatrixImage) args = { image, kernel_info, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ColorMatrixImage), &args);
    kernel_info->values = (double *) NULL;
    DestroyKernelInfo(kernel_info);
    xfree((void *) matrix);

    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#reduce_noise(radius) ⇒ Magick::Image

Smooth the contours of an image while still preserving edge information.

Parameters:

• radius (Numeric) —

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

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 11815

VALUE
Image_reduce_noise(VALUE self, VALUE radius)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    size_t radius_size = NUM2SIZET(radius);

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(StatisticImage) args = { image, NonpeakStatistic, radius_size, radius_size, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(StatisticImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#remap(remap_image, dither_method = Magick::RiemersmaDitherMethod) ⇒ Object Also known as: affinity

Reduce the number of colors in img to the colors used by remap_image. If a dither method is specified then the given colors are dithered over the image as necessary, otherwise the closest color (in RGB colorspace) is selected to replace that pixel in the image.

Returns self.

Parameters:

• remap_image (Magick::Image, Magick::ImageList) —

  The reference image or imagelist. If an imagelist, uses the current image.

• dither_method (Magick::DitherMethod) (defaults to: Magick::RiemersmaDitherMethod) —

  this object

Returns:

• self

# File 'ext/RMagick/rmimage.cpp', line 11846

VALUE
Image_remap(int argc, VALUE *argv, VALUE self)
{
    Image *image, *remap_image;
    QuantizeInfo quantize_info;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

    GetQuantizeInfo(&quantize_info);

    switch (argc)
    {
        case 2:
            VALUE_TO_ENUM(argv[1], quantize_info.dither_method, DitherMethod);
#if defined(IMAGEMAGICK_6)
            quantize_info.dither = MagickTrue;
#endif
            break;
        case 1:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 or 2)", argc);
            break;
    }

    remap_image = rm_check_destroyed(rm_cur_image(argv[0]));

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(RemapImage) args = { &quantize_info, image, remap_image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RemapImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(RemapImage) args = { &quantize_info, image, remap_image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RemapImage), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return self;
}

#rendering_intent ⇒ Magick::RenderingIntent

Get the type of rendering intent.

Returns:

• (Magick::RenderingIntent) —

  the rendering intent

# File 'ext/RMagick/rmimage.cpp', line 11897

VALUE
Image_rendering_intent(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return RenderingIntent_find(image->rendering_intent);
}

#rendering_intent=(ri) ⇒ Magick::RenderingIntent

Set the type of rendering intent..

Parameters:

• ri (Magick::RenderingIntent) —

  the rendering intent

Returns:

• (Magick::RenderingIntent) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 11911

VALUE
Image_rendering_intent_eq(VALUE self, VALUE ri)
{
    Image *image = rm_check_frozen(self);
    VALUE_TO_ENUM(ri, image->rendering_intent, RenderingIntent);
    return ri;
}

#resample(x_resolution = 72.0, y_resolution = 72.0, filter = self.filter, blur = self.blur) ⇒ Magick

Resample image to specified horizontal resolution, vertical resolution, filter and blur factor.

Resize the image so that its rendered size remains the same as the original at the specified target resolution. For example, if a 300 DPI image renders at 3 inches by 2 inches on a 300 DPI device, when the image has been resampled to 72 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of storing the image resolution. For formats which do not support an image resolution, the original resolution of the image must be specified via the density attribute prior to specifying the resample resolution.

Returns a new image.

Parameters:

• x_resolution (Numeric) (defaults to: 72.0) —

  the target horizontal resolution.

• y_resolution (Numeric) (defaults to: 72.0) —

  the target vertical resolution.

• filter (Magick::FilterType) (defaults to: self.filter) —

  the filter type

• blur (Numeric) (defaults to: self.blur) —

  the blur size

Returns:

• (Magick) —

  a new image

See Also:

• #resample!

# File 'ext/RMagick/rmimage.cpp', line 12078

VALUE
Image_resample(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return resample(False, argc, argv, self);
}

#resample!(x_resolution = 72.0, y_resolution = 72.0, filter = self.filter, blur = self.blur) ⇒ Magick

Resample image to specified horizontal resolution, vertical resolution, filter and blur factor. In-place form of #resample.

Returns a new image.

Parameters:

• x_resolution (Numeric) (defaults to: 72.0) —

  the target horizontal resolution.

• y_resolution (Numeric) (defaults to: 72.0) —

  the target vertical resolution.

• filter (Magick::FilterType) (defaults to: self.filter) —

  the filter type

• blur (Numeric) (defaults to: self.blur) —

  the blur size

Returns:

• (Magick) —

  a new image

See Also:

• #resample

# File 'ext/RMagick/rmimage.cpp', line 12098

VALUE
Image_resample_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return resample(True, argc, argv, self);
}

#resize(scale) ⇒ Magick::Image #resize(cols, rows, filter, blur) ⇒ Magick::Image

Scale an image to the desired dimensions using the specified filter and blur factor.

Overloads:

• #resize(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

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

• #resize(cols, rows, filter, blur) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width

  • rows (Numeric) —

    The desired height.

  • filter (Magick::FilterType) —

    the filter type

  • blur (Numeric) —

    the blur size

Returns:

• (Magick::Image) —

  a new image

See Also:

• #resize!

# File 'ext/RMagick/rmimage.cpp', line 12221

VALUE
Image_resize(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return resize(False, argc, argv, self);
}

#resize!(scale) ⇒ Magick::Image #resize!(cols, rows, filter, blur) ⇒ Magick::Image

Scale an image to the desired dimensions using the specified filter and blur factor. In-place form of #resize.

Overloads:

• #resize!(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

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

• #resize!(cols, rows, filter, blur) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width

  • rows (Numeric) —

    The desired height.

  • filter (Magick::FilterType) —

    the filter type

  • blur (Numeric) —

    the blur size

Returns:

• (Magick::Image) —

  a new image

See Also:

• #resize!

# File 'ext/RMagick/rmimage.cpp', line 12247

VALUE
Image_resize_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return resize(True, argc, argv, self);
}

#resize_to_fill(ncols, nrows = nil, gravity = CenterGravity) ⇒ Object Also known as: crop_resized

Force an image to exact dimensions without changing the aspect ratio. Resize and crop if necessary. (Thanks to Jerett Taylor!)

# File 'lib/rmagick_internal.rb', line 961

def resize_to_fill(ncols, nrows = nil, gravity = CenterGravity)
  copy.resize_to_fill!(ncols, nrows, gravity)
end

#resize_to_fill!(ncols, nrows = nil, gravity = CenterGravity) ⇒ Object Also known as: crop_resized!

# File 'lib/rmagick_internal.rb', line 965

def resize_to_fill!(ncols, nrows = nil, gravity = CenterGravity)
  nrows ||= ncols
  if ncols != columns || nrows != rows
    scale = [ncols / columns.to_f, nrows / rows.to_f].max
    resize!(scale * columns + 0.5, scale * rows + 0.5)
  end
  crop!(gravity, ncols, nrows, true) if ncols != columns || nrows != rows
  self
end

#resize_to_fit(cols, rows = nil) ⇒ Object

Convenience method to resize retaining the aspect ratio. (Thanks to Robert Manni!)

# File 'lib/rmagick_internal.rb', line 981

def resize_to_fit(cols, rows = nil)
  rows ||= cols
  change_geometry(Geometry.new(cols, rows)) do |ncols, nrows|
    resize(ncols, nrows)
  end
end

#resize_to_fit!(cols, rows = nil) ⇒ Object

# File 'lib/rmagick_internal.rb', line 988

def resize_to_fit!(cols, rows = nil)
  rows ||= cols
  change_geometry(Geometry.new(cols, rows)) do |ncols, nrows|
    resize!(ncols, nrows)
  end
end

#roll(x_offset, y_offset) ⇒ Magick::Image

Offset an image as defined by x_offset and y_offset.

Parameters:

• x_offset (Numeric) —

  the x offset

• y_offset (Numeric) —

  the y offset

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 12262

VALUE
Image_roll(VALUE self, VALUE x_offset, VALUE y_offset)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    ssize_t x = NUM2LONG(x_offset);
    ssize_t y = NUM2LONG(y_offset);

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(RollImage) args = { image, x, y, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(RollImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#rotate(degrees) ⇒ Magick::Image #rotate(degrees, qualifier) ⇒ Magick::Image

Rotate the receiver by the specified angle. Positive angles rotate clockwise while negative angles rotate counter-clockwise. New pixels introduced by the rotation are the same color as the current background color. Set the background color to "none" to make the new pixels transparent black.

Overloads:

• #rotate(degrees) ⇒ Magick::Image

  Parameters:

  • degrees (Numeric) —

    The number of degrees to rotate the image.

• #rotate(degrees, qualifier) ⇒ Magick::Image

  Parameters:

  • degrees (Numeric) —

    The number of degrees to rotate the image.

  • qualifier (String) —

    If present, either ">" or "<". If ">", rotates the image only if the image's width exceeds its height. If "<" rotates the image only if its height exceeds its width. If this argument is omitted the image is always rotated.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #rotate!

# File 'ext/RMagick/rmimage.cpp', line 12366

VALUE
Image_rotate(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return rotate(False, argc, argv, self);
}

#rotate!(degrees) ⇒ Magick::Image #rotate!(degrees, qualifier) ⇒ Magick::Image

Rotate the image. In-place form of #rotate.

Overloads:

• #rotate!(degrees) ⇒ Magick::Image

  Parameters:

  • degrees (Numeric) —

    The number of degrees to rotate the image.

• #rotate!(degrees, qualifier) ⇒ Magick::Image

  Parameters:

  • degrees (Numeric) —

    The number of degrees to rotate the image.

  • qualifier (String) —

    If present, either ">" or "<". If ">", rotates the image only if the image's width exceeds its height. If "<" rotates the image only if its height exceeds its width. If this argument is omitted the image is always rotated.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #rotate!

# File 'ext/RMagick/rmimage.cpp', line 12390

VALUE
Image_rotate_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return rotate(True, argc, argv, self);
}

#rows ⇒ Integer

Return image rows.

Returns:

• (Integer) —

  the image rows

# File 'ext/RMagick/rmimage.cpp', line 12403

VALUE
Image_rows(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, rows, int, &rm_image_data_type);
}

#sample(scale) ⇒ Magick::Image #sample(cols, rows) ⇒ Magick::Image

Scale an image to the desired dimensions with pixel sampling. Unlike other scaling methods, this method does not introduce any additional color into the scaled image.

Overloads:

• #sample(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

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

• #sample(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #sample!

# File 'ext/RMagick/rmimage.cpp', line 12426

VALUE
Image_sample(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return scale(False, argc, argv, self, GVL_FUNC(SampleImage));
}

#sample!(scale) ⇒ Magick::Image #sample!(cols, rows) ⇒ Magick::Image

Scale an image to the desired dimensions with pixel sampling. In-place form of #sample.

Overloads:

• #sample!(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

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

• #sample!(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #sample

# File 'ext/RMagick/rmimage.cpp', line 12450

VALUE
Image_sample_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return scale(True, argc, argv, self, GVL_FUNC(SampleImage));
}

#scale(scale) ⇒ Magick::Image #scale(cols, rows) ⇒ Magick::Image

Change the size of an image to the given dimensions. Alias of #sample.

Overloads:

• #scale(scale) ⇒ Magick::Image

  Parameters:

  • scale (Float) —

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

• #scale(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #sample
• #scale!

# File 'ext/RMagick/rmimage.cpp', line 12474

VALUE
Image_scale(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return scale(False, argc, argv, self, GVL_FUNC(ScaleImage));
}

#scale!(scale) ⇒ Magick::Image #scale!(cols, rows) ⇒ Magick::Image

Change the size of an image to the given dimensions. Alias of #sample!.

Overloads:

• #scale!(scale) ⇒ Magick::Image

  Parameters:

  • scale (Float) —

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

• #scale!(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #sample
• #scale!

# File 'ext/RMagick/rmimage.cpp', line 12498

VALUE
Image_scale_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return scale(True, argc, argv, self, GVL_FUNC(ScaleImage));
}

#scene ⇒ Integer

Return the scene number assigned to the image the last time the image was written to a multi-image image file.

Returns:

• (Integer) —

  the image scene

# File 'ext/RMagick/rmimage.cpp', line 12593

VALUE
Image_scene(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, scene, ulong, &rm_image_data_type);
}

#segment(colorspace = Magick::RGBColorspace, cluster_threshold = 1.0, smoothing_threshold = 1.5, verbose = false) ⇒ Magick::Image

Segments an image by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique.

Returns a new image.

Parameters:

• colorspace (Magick::ColorspaceType) (defaults to: Magick::RGBColorspace) —

  A ColorspaceType value. Empirical evidence suggests that distances in YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. The image is then returned to RGB colorspace after color reduction.

• cluster_threshold (Numeric) (defaults to: 1.0) —

  The number of pixels in each cluster must exceed the the cluster threshold to be considered valid.

• smoothing_threshold (Numeric) (defaults to: 1.5) —

  The smoothing threshold eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative.

• verbose (Boolean) (defaults to: false) —

  If true, segment prints detailed information about the identified classes.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 12802

VALUE
Image_segment(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ColorspaceType colorspace   = RGBColorspace;    // These are the Magick++ defaults
    MagickBooleanType verbose   = MagickFalse;
    double cluster_threshold    = 1.0;
    double smoothing_threshold  = 1.5;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 4:
            verbose = (MagickBooleanType)RTEST(argv[3]);
        case 3:
            smoothing_threshold = NUM2DBL(argv[2]);
        case 2:
            cluster_threshold = NUM2DBL(argv[1]);
        case 1:
            VALUE_TO_ENUM(argv[0], colorspace, ColorspaceType);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 4)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SegmentImage) args = { new_image, colorspace, verbose, cluster_threshold, smoothing_threshold, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SegmentImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SegmentImage) args = { new_image, colorspace, verbose, cluster_threshold, smoothing_threshold };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SegmentImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#selective_blur_channel(radius, sigma, threshold, channel = Magick::AllChannels) ⇒ Magick::Image #selective_blur_channel(radius, sigma, threshold, *channels) ⇒ Magick::Image

Selectively blur pixels within a contrast threshold.

Overloads:

• #selective_blur_channel(radius, sigma, threshold, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) —

    the radius value

  • sigma (Numeric) —

    the sigma value

  • threshold (Numeric, String) —

    Either a number between 0.0 and 1.0 or a string in the form "NN%"

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #selective_blur_channel(radius, sigma, threshold, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) —

    the radius value

  • sigma (Numeric) —

    the sigma value

  • threshold (Numeric, String) —

    Either a number between 0.0 and 1.0 or a string in the form "NN%"

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 12619

VALUE
Image_selective_blur_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius, sigma, threshold;
    ExceptionInfo *exception;
    ChannelType channels;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 3)
    {
        raise_ChannelType_error(argv[argc-1]);
    }
    if (argc != 3)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 3 or more)", argc);
    }
    radius = NUM2DBL(argv[0]);
    sigma = NUM2DBL(argv[1]);

    // threshold is either a floating-point number or a string in the form "NN%".
    // Either way it's supposed to represent a percentage of the QuantumRange.
    threshold = rm_percentage(argv[2], 1.0) * QuantumRange;

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(SelectiveBlurImage) args = { image, radius, sigma, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SelectiveBlurImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(SelectiveBlurImageChannel) args = { image, channels, radius, sigma, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SelectiveBlurImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#separate(channel = Magick::AllChannels) ⇒ Magick::ImageList #separate(*channels) ⇒ Magick::ImageList

Constructs a grayscale image for each channel specified.

Overloads:

• #separate(channel = Magick::AllChannels) ⇒ Magick::ImageList

  Parameters:

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #separate(*channels) ⇒ Magick::ImageList

  Parameters:

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::ImageList) —

  a new ImageList

# File 'ext/RMagick/rmimage.cpp', line 12713

VALUE
Image_separate(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_images;
    ChannelType channels = UndefinedChannel;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // All arguments are ChannelType enums
    if (argc > 0)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(SeparateImages) args = { image, exception };
    new_images = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SeparateImages), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_images);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(SeparateImages) args = { image, channels, exception };
    new_images = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SeparateImages), &args);
#endif
    rm_check_exception(exception, new_images, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_imagelist_from_images(new_images);
}

#sepiatone(threshold = Magick::QuantumRange) ⇒ Magick::Image

Applies a special effect to the image, similar to the effect achieved in a photo darkroom by sepia toning.

Returns a new image.

Parameters:

• threshold (Numeric) (defaults to: Magick::QuantumRange) —

  Threshold ranges from 0 to QuantumRange and is a measure of the extent of the sepia toning. A threshold of 80% is a good starting point for a reasonable tone.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 12756

VALUE
Image_sepiatone(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double threshold = (double) QuantumRange;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 1:
            threshold = NUM2DBL(argv[0]);
            break;
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SepiaToneImage) args = { image, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SepiaToneImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#set_channel_depth(channel_arg, depth) ⇒ Object

Sets the depth of the image channel.

Parameters:

• channel_arg (Magick::ChannelType) —

  the channel

• depth (Numeric) —

  the depth

Returns:

• self

# File 'ext/RMagick/rmimage.cpp', line 12669

VALUE
Image_set_channel_depth(VALUE self, VALUE channel_arg, VALUE depth)
{
    Image *image;
    ChannelType channel;
    unsigned long channel_depth;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);

    VALUE_TO_ENUM(channel_arg, channel, ChannelType);
    channel_depth = NUM2ULONG(depth);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(image, channel);
    GVL_STRUCT_TYPE(SetImageDepth) args = { image, channel_depth, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageDepth), &args);
    END_CHANNEL_MASK(image);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SetImageChannelDepth) args = { image, channel, channel_depth };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageChannelDepth), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    return self;
}

#shade(shading = false, azimuth = 30.0, elevation = 30.0) ⇒ Magick::Image

Shine a distant light on an image to create a three-dimensional effect. You control the positioning of the light with azimuth and elevation; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis.

Returns a new image.

Parameters:

• shading (Boolean) (defaults to: false) —

  If true, shade shades the intensity of each pixel.

• azimuth (Numeric) (defaults to: 30.0) —

  The light source direction. The azimuth is measured in degrees. 0 is at 9 o'clock. Increasing values move the light source counter-clockwise.

• elevation (Numeric) (defaults to: 30.0) —

  The light source direction. The azimuth is measured in degrees. 0 is at 9 o'clock. Increasing values move the light source counter-clockwise.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 12963

VALUE
Image_shade(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double azimuth = 30.0, elevation = 30.0;
    MagickBooleanType shading = MagickFalse;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 3:
            elevation = NUM2DBL(argv[2]);
        case 2:
            azimuth = NUM2DBL(argv[1]);
        case 1:
            shading = (MagickBooleanType)RTEST(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 3)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ShadeImage) args = { image, shading, azimuth, elevation, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ShadeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#Image ⇒ Magick::Image

Call ShadowImage. X- and y-offsets are the pixel offset. Alpha is either a number between 0 and 1 or a string "NN%". Sigma is the std. dev. of the Gaussian, in pixels.

Returns a new image.

Parameters:

• x_offset (Numeric) —

  The shadow x-offset

• y_offset (Numeric) —

  The shadow y-offset

• sigma (Numeric) —

  The standard deviation of the Gaussian operator used to produce the shadow. The higher the number, the "blurrier" the shadow, but the longer it takes to produce the shadow. Must be > 0.0.

• alpha (Numeric, String) —

  The percent alpha of the shadow. The argument may be a floating-point numeric value or a string in the form "NN%".

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13011

VALUE
Image_shadow(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double alpha = 100.0;
    double sigma = 4.0;
    long x_offset = 4L;
    long y_offset = 4L;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 4:
            alpha = rm_percentage(argv[3], 1.0);   // Clamp to 1.0 < x <= 100.0
            if (fabs(alpha) < 0.01)
            {
                rb_warning("shadow will be transparent - alpha %g very small", alpha);
            }
            alpha = FMIN(alpha, 1.0);
            alpha = FMAX(alpha, 0.01);
            alpha *= 100.0;
        case 3:
            sigma = NUM2DBL(argv[2]);
        case 2:
            y_offset = NUM2LONG(argv[1]);
        case 1:
            x_offset = NUM2LONG(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 4)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ShadowImage) args = { image, alpha, sigma, x_offset, y_offset, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ShadowImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#sharpen(radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Sharpen an image.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian operator.

• sigma (Numeric) (defaults to: 1.0) —

  The sigma (standard deviation) of the Gaussian operator.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13064

VALUE
Image_sharpen(int argc, VALUE *argv, VALUE self)
{
    return effect_image(self, argc, argv, GVL_FUNC(SharpenImage));
}

#sharpen_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image #sharpen_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

Sharpen image on a channel.

Overloads:

• #sharpen_channel(radius = 0.0, sigma = 1.0, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The sigma (standard deviation) of the Gaussian operator.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #sharpen_channel(radius = 0.0, sigma = 1.0, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The sigma (standard deviation) of the Gaussian operator.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13086

VALUE
Image_sharpen_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    ExceptionInfo *exception;
    double radius = 0.0, sigma = 1.0;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    // There must be 0, 1, or 2 remaining arguments.
    switch (argc)
    {
        case 2:
            sigma = NUM2DBL(argv[1]);
            /* Fall thru */
        case 1:
            radius = NUM2DBL(argv[0]);
            /* Fall thru */
        case 0:
            break;
        default:
            raise_ChannelType_error(argv[argc-1]);
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(SharpenImage) args = { image, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SharpenImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(SharpenImageChannel) args = { image, channels, radius, sigma, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SharpenImageChannel), &args);
#endif

    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#shave(width, height) ⇒ Magick::Image

Shave pixels from the image edges, leaving a rectangle of the specified width & height in the center.

Parameters:

• width (Numeric) —

  the width to leave

• height (Numeric) —

  the hight to leave

Returns:

• (Magick::Image) —

  a new image

See Also:

• #shave!

# File 'ext/RMagick/rmimage.cpp', line 13140

VALUE
Image_shave(VALUE self, VALUE width, VALUE height)
{
    rm_check_destroyed(self);
    return xform_image(False, self, INT2FIX(0), INT2FIX(0), width, height, GVL_FUNC(ShaveImage));
}

#shave!(width, height) ⇒ Magick::Image

Shave pixels from the image edges, leaving a rectangle of the specified width & height in the center. In-place form of #shave.

Parameters:

• width (Numeric) —

  the width to leave

• height (Numeric) —

  the hight to leave

Returns:

• (Magick::Image) —

  a new image

See Also:

• #shave

# File 'ext/RMagick/rmimage.cpp', line 13158

VALUE
Image_shave_bang(VALUE self, VALUE width, VALUE height)
{
    rm_check_frozen(self);
    return xform_image(True, self, INT2FIX(0), INT2FIX(0), width, height, GVL_FUNC(ShaveImage));
}

#shear(x_shear, y_shear) ⇒ Magick::Image

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

Parameters:

• x_shear (Numeric) —

  the x shear (in degrees)

• y_shear (Numeric) —

  the y shear (in degrees)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13178

VALUE
Image_shear(VALUE self, VALUE x_shear, VALUE y_shear)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    double x = NUM2DBL(x_shear);
    double y = NUM2DBL(y_shear);

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ShearImage) args = { image, x, y, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ShearImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#sigmoidal_contrast_channel(contrast = 3.0, midpoint = 50.0, sharpen = false, channel = Magick::AllChannels) ⇒ Magick::Image #sigmoidal_contrast_channel(contrast = 3.0, midpoint = 50.0, sharpen = false, *channels) ⇒ Magick::Image

Adjusts the contrast of an image channel with a non-linear sigmoidal contrast algorithm. Increases the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows.

Overloads:

• #sigmoidal_contrast_channel(contrast = 3.0, midpoint = 50.0, sharpen = false, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • contrast (Numeric) (defaults to: 3.0) —

    indicates how much to increase the contrast (0 is none; 3 is typical; 20 is pushing it)

  • midpoint (Numeric) (defaults to: 50.0) —

    indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). Note that "50%" means "50% of the quantum range." This argument is a number between 0 and QuantumRange. To specify "50%" use QuantumRange * 0.50.

  • sharpen (Boolean) (defaults to: false) —

    Set sharpen to true to increase the image contrast otherwise the contrast is reduced.

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #sigmoidal_contrast_channel(contrast = 3.0, midpoint = 50.0, sharpen = false, *channels) ⇒ Magick::Image

  Parameters:

  • contrast (Numeric) (defaults to: 3.0) —

    indicates how much to increase the contrast (0 is none; 3 is typical; 20 is pushing it)

  • midpoint (Numeric) (defaults to: 50.0) —

    indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). Note that "50%" means "50% of the quantum range." This argument is a number between 0 and QuantumRange. To specify "50%" use QuantumRange * 0.50.

  • sharpen (Boolean) (defaults to: false) —

    Set sharpen to true to increase the image contrast otherwise the contrast is reduced.

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13225

VALUE
Image_sigmoidal_contrast_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickBooleanType sharpen = MagickFalse;
    double contrast = 3.0;
    double midpoint = 50.0;
    ChannelType channels;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);

    switch (argc)
    {
        case 3:
            sharpen  = (MagickBooleanType) RTEST(argv[2]);
        case 2:
            midpoint = NUM2DBL(argv[1]);
        case 1:
            contrast = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            raise_ChannelType_error(argv[argc-1]);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    BEGIN_CHANNEL_MASK(new_image, channels);
    GVL_STRUCT_TYPE(SigmoidalContrastImage) args = { new_image, sharpen, contrast, midpoint, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SigmoidalContrastImage), &args);
    END_CHANNEL_MASK(new_image);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SigmoidalContrastImageChannel) args = { new_image, channels, sharpen, contrast, midpoint };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SigmoidalContrastImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#signature ⇒ String^?

Compute a message digest from an image pixel stream with an implementation of the NIST SHA-256 Message Digest algorithm.

Returns:

• (String, nil) —

  the message digest

# File 'ext/RMagick/rmimage.cpp', line 13281

VALUE
Image_signature(VALUE self)
{
    Image *image;
    const char *signature;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SignatureImage) args = { image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SignatureImage) args = { image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SignatureImage), &args);
    rm_check_image_exception(image, RetainOnError);
#endif
    signature = rm_get_property(image, "signature");
    if (!signature)
    {
        return Qnil;
    }
    return rb_str_new(signature, 64);
}

#sketch(radius = 0.0, sigma = 1.0, angle = 0.0) ⇒ Magick::Image

Simulates a pencil sketch. For best results start with a grayscale image.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation

• angle (Numeric) (defaults to: 0.0) —

  The angle (in degrees)

Returns:

• (Magick::Image) —

  a new image

See Also:

• #motion_blur

# File 'ext/RMagick/rmimage.cpp', line 13322

VALUE
Image_sketch(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return motion_blur(argc, argv, self, GVL_FUNC(SketchImage));
}

#solarize(threshold = 50.0) ⇒ Object

Apply a special effect to the image, similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light. Threshold ranges from 0 to QuantumRange and is a measure of the extent of the solarization.

solarization.

Parameters:

• threshold (Numeric) (defaults to: 50.0) —

  Ranges from 0 to QuantumRange and is a measure of the extent of the

Returns:

• a new image

# File 'ext/RMagick/rmimage.cpp', line 13340

VALUE
Image_solarize(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double threshold = 50.0;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            threshold = NUM2DBL(argv[0]);
            if (threshold < 0.0 || threshold > QuantumRange)
            {
                rb_raise(rb_eArgError, "threshold out of range, must be >= 0.0 and < QuantumRange");
            }
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SolarizeImage) args = { new_image, threshold, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SolarizeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(SolarizeImage) args = { new_image, threshold };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SolarizeImage), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#sparse_color(method, x1, y1, color) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color, ...) ⇒ Magick::Image #sparse_color(method, x1, y1, color, channel) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color, channel) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color, ..., channel) ⇒ Magick::Image #sparse_color(method, x1, y1, color, channel, ...) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color, channel, ...) ⇒ Magick::Image #sparse_color(method, x1, y1, color, x2, y2, color, ..., channel, ...) ⇒ Magick::Image

Fills the image with the specified color or colors, starting at the x,y coordinates associated with the color and using the specified interpolation method.

Overloads:

• #sparse_color(method, x1, y1, color, x2, y2, color, ..., channel, ...) ⇒ Magick::Image

  Parameters:

  • method (Magick::SparseColorMethod) —

    the method

  • x1 (Float) —

    One or more x.

  • y1 (Float) —

    One or more y.

  • color (Magick::Pixel, String) —

    One or more color

  • channel (Magick::ChannelType) —

    one or more ChannelType arguments

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13512

VALUE
Image_sparse_color(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    unsigned long x, nargs, ncolors;
    SparseColorMethod method;
    int n, exp;
    double * volatile args;
    ChannelType channels;
    MagickPixel pp;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    n = argc;
    channels = extract_channels(&argc, argv);
    n -= argc;  // n is now the number of channel arguments

    // After the channel arguments have been removed, and not counting the first
    // (method) argument, the number of arguments should be a multiple of 3.
    if (argc < 4 || argc % 3 != 1)
    {
        exp = (argc + 2) / 3 * 3;
        exp = max(exp, 3);
        rb_raise(rb_eArgError, "wrong number of arguments (expected at least %d, got %d)", n+exp+1,  n+argc);
    }

    // Get the method from the argument list
    VALUE_TO_ENUM(argv[0], method, SparseColorMethod);
    argv += 1;
    argc -= 1;

    // A lot of the following code is based on SparseColorOption, in wand/mogrify.c
    ncolors = count_channels(image, &channels);
    nargs = (argc / 3) * (2 + ncolors);

    // Allocate args from Ruby's memory so that GC will collect it if one of
    // the type conversions below raises an exception.
    args = ALLOC_N(double, nargs);
    memset(args, 0, nargs * sizeof(double));

    x = 0;
    n = 0;
    while (n < argc)
    {
        VALUE elem1 = argv[n++];
        VALUE elem2 = argv[n++];
        if (rm_check_num2dbl(elem1) && rm_check_num2dbl(elem2))
        {
            args[x++] = NUM2DBL(elem1);
            args[x++] = NUM2DBL(elem2);
        }
        else
        {
            xfree((void *) args);
            rb_raise(rb_eTypeError, "type mismatch: %s and %s given", rb_class2name(CLASS_OF(elem1)), rb_class2name(CLASS_OF(elem2)));
        }
        Color_to_MagickPixel(NULL, &pp, argv[n++]);
        if (channels & RedChannel)
        {
            args[x++] = pp.red / QuantumRange;
        }
        if (channels & GreenChannel)
        {
            args[x++] = pp.green / QuantumRange;
        }
        if (channels & BlueChannel)
        {
            args[x++] = pp.blue / QuantumRange;
        }
        if (channels & IndexChannel)
        {
            args[x++] = pp.index / QuantumRange;
        }
        if (channels & OpacityChannel)
        {
#if defined(IMAGEMAGICK_7)
            args[x++] = pp.alpha / QuantumRange;
#else
            args[x++] = pp.opacity / QuantumRange;
#endif
        }
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(SparseColorImage) args_SparseColorImage = { image, method, nargs, args, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SparseColorImage), &args_SparseColorImage);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(SparseColorImage) args_SparseColorImage = { image, channels, method, nargs, args, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SparseColorImage), &args_SparseColorImage);
#endif
    xfree((void *) args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#splice(x, y, width, height, color = self.background_color) ⇒ Magick::Image

Splice a solid color into the part of the image specified by the x, y, width, and height arguments. If the color argument is specified it must be a color name or Pixel.

Returns a new image.

Parameters:

• x (Numeric) —

  Describe the rectangle to be spliced.

• y (Numeric) —

  Describe the rectangle to be spliced.

• width (Numeric) —

  Describe the rectangle to be spliced.

• height (Numeric) —

  Describe the rectangle to be spliced.

• color (Magick::Pixel, String) (defaults to: self.background_color) —

  The color to be spliced.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #chop

# File 'ext/RMagick/rmimage.cpp', line 13629

VALUE
Image_splice(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    PixelColor color, old_color;
    RectangleInfo rectangle;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 4:
            // use background color
            color = image->background_color;
            break;
        case 5:
            // Convert color argument to PixelColor
            Color_to_PixelColor(&color, argv[4]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 4 or 5)", argc);
            break;
    }

    rectangle.x      = NUM2LONG(argv[0]);
    rectangle.y      = NUM2LONG(argv[1]);
    rectangle.width  = NUM2ULONG(argv[2]);
    rectangle.height = NUM2ULONG(argv[3]);

    exception = AcquireExceptionInfo();

    // Swap in color for the duration of this call.
    old_color = image->background_color;
    image->background_color = color;
    GVL_STRUCT_TYPE(SpliceImage) args = { image, &rectangle, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SpliceImage), &args);
    image->background_color = old_color;

    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#spread(radius = 3.0) ⇒ Magick::Image

Randomly displace each pixel in a block defined by "radius".

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 3.0) —

  The radius

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13682

VALUE
Image_spread(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius = 3.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 1:
            radius = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 or 1)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(SpreadImage) args = { image, image->interpolate, radius, exception };
#else
    GVL_STRUCT_TYPE(SpreadImage) args = { image, radius, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SpreadImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#start_loop ⇒ Boolean

Get the Boolean value that indicates the first image in an animation.

Returns:

• (Boolean) —

  true or false

# File 'ext/RMagick/rmimage.cpp', line 13720

VALUE
Image_start_loop(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, start_loop, boolean, &rm_image_data_type);
}

#start_loop=(val) ⇒ Boolean

Set the Boolean value that indicates the first image in an animation.

Parameters:

• val (Boolean) —

  true or false

Returns:

• (Boolean) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 13732

VALUE
Image_start_loop_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, start_loop, boolean, &rm_image_data_type);
}

#stegano(watermark_image, offset) ⇒ Magick::Image

Hides a digital watermark in the receiver. You can retrieve the watermark by reading the file with the stegano: prefix, thereby proving the authenticity of the file.

The watermarked image must be saved in a lossless RGB format such as MIFF, or PNG. You cannot save a watermarked image in a lossy format such as JPEG or a pseudocolor format such as GIF. Once written, the file must not be modified or processed in any way.

Parameters:

• watermark_image (Magick::Image, Magick::ImageList) —

  Either an imagelist or an image

• offset (Numeric) —

  the start position within the image to hide the watermark.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13751

VALUE
Image_stegano(VALUE self, VALUE watermark_image, VALUE offset)
{
    Image *image, *new_image;
    VALUE wm_image;
    Image *watermark;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    wm_image = rm_cur_image(watermark_image);
    watermark = rm_check_destroyed(wm_image);

    image->offset = NUM2LONG(offset);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SteganoImage) args = { image, watermark, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SteganoImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    RB_GC_GUARD(wm_image);

    return rm_image_new(new_image);
}

#stereo(offset_image_arg) ⇒ Magick::Image

Combine two images and produces a single image that is the composite of a left and right image of a stereo pair. Special red-green stereo glasses are required to view this effect.

Parameters:

• offset_image_arg (Magick::Image, Magick::ImageList) —

  Either an imagelist or an image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 13786

VALUE
Image_stereo(VALUE self, VALUE offset_image_arg)
{
    Image *image, *new_image;
    VALUE offset_image;
    Image *offset;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    offset_image = rm_cur_image(offset_image_arg);
    offset = rm_check_destroyed(offset_image);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(StereoImage) args = { image, offset, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(StereoImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);

    DestroyExceptionInfo(exception);

    RB_GC_GUARD(offset_image);

    return rm_image_new(new_image);
}

#store_pixels(x_arg, y_arg, cols_arg, rows_arg, new_pixels) ⇒ Magick::Image

Replace the pixels in the specified rectangle with the pixels in the pixels array.

• This is the complement of get_pixels. The array object returned by get_pixels is suitable for use as the "new_pixels" argument.

Parameters:

• x_arg (Numeric) —

  x position of start of region

• y_arg (Numeric) —

  y position of start of region

• cols_arg (Numeric) —

  width of region

• rows_arg (Numeric) —

  height of region

• new_pixels (Array<Magick::Pixel>) —

  the replacing pixels

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 13909

VALUE
Image_store_pixels(VALUE self, VALUE x_arg, VALUE y_arg, VALUE cols_arg,
                   VALUE rows_arg, VALUE new_pixels)
{
    Image *image;
    Pixel *pixel;
    VALUE new_pixel;
    long n, size;
    long x, y;
    unsigned long cols, rows;
    MagickBooleanType okay;
    ExceptionInfo *exception;
#if defined(IMAGEMAGICK_7)
    Quantum *pixels;
#else
    PixelPacket *pixels;
#endif

    image = rm_check_destroyed(self);

    x = NUM2LONG(x_arg);
    y = NUM2LONG(y_arg);
    cols = NUM2ULONG(cols_arg);
    rows = NUM2ULONG(rows_arg);
    if (x < 0 || y < 0 || x+cols > image->columns || y+rows > image->rows)
    {
        rb_raise(rb_eRangeError, "geometry (%lux%lu%+ld%+ld) exceeds image bounds",
                 cols, rows, x, y);
    }

    size = (long)(cols * rows);
    new_pixels = rb_Array(new_pixels);
    rm_check_ary_len(new_pixels, size);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, DirectClass, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    CHECK_EXCEPTION();
    if (!okay)
    {
        DestroyExceptionInfo(exception);
        rb_raise(Class_ImageMagickError, "SetImageStorageClass failed. Can't store pixels.");
    }
#else
    GVL_STRUCT_TYPE(SetImageStorageClass) args = { image, DirectClass };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(image, RetainOnError);
    if (!okay)
    {
        rb_raise(Class_ImageMagickError, "SetImageStorageClass failed. Can't store pixels.");
    }
    exception = AcquireExceptionInfo();
#endif

    // Get a pointer to the pixels. Replace the values with the PixelPackets
    // from the pixels argument.
    {
        GVL_STRUCT_TYPE(GetAuthenticPixels) args = { image, x, y, cols, rows, exception };
        void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetAuthenticPixels), &args);
        pixels = reinterpret_cast<decltype(pixels)>(ret);
        CHECK_EXCEPTION();

        if (pixels)
        {
#if defined(IMAGEMAGICK_6)
            IndexPacket *indexes = GetAuthenticIndexQueue(image);
#endif
            for (n = 0; n < size; n++)
            {
                new_pixel = rb_ary_entry(new_pixels, n);
                if (CLASS_OF(new_pixel) != Class_Pixel)
                {
                    DestroyExceptionInfo(exception);
                    rb_raise(rb_eTypeError, "Item in array should be a Pixel.");
                }
                TypedData_Get_Struct(new_pixel, Pixel, &rm_pixel_data_type, pixel);
#if defined(IMAGEMAGICK_7)
                SetPixelRed(image,   pixel->red,   pixels);
                SetPixelGreen(image, pixel->green, pixels);
                SetPixelBlue(image,  pixel->blue,  pixels);
                SetPixelAlpha(image, pixel->alpha, pixels);
                SetPixelBlack(image, pixel->black, pixels);
                pixels += GetPixelChannels(image);
#else
                SetPixelRed(pixels, pixel->red);
                SetPixelGreen(pixels, pixel->green);
                SetPixelBlue(pixels, pixel->blue);
                SetPixelOpacity(pixels, pixel->opacity);
                if (indexes)
                {
                    SetPixelIndex(indexes + n, pixel->black);
                }
                pixels++;
#endif
            }
            GVL_STRUCT_TYPE(SyncAuthenticPixels) args = { image, exception };
            CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SyncAuthenticPixels), &args);
            CHECK_EXCEPTION();
        }

        DestroyExceptionInfo(exception);
    }

    RB_GC_GUARD(new_pixel);

    return self;
}

#strip! ⇒ Magick::Image

Strips an image of all profiles and comments.

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 14026

VALUE
Image_strip_bang(VALUE self)
{
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    Image *image = rm_check_frozen(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    StripImage(image, exception);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    StripImage(image);
    rm_check_image_exception(image, RetainOnError);
#endif
    return self;
}

#swirl(degrees_obj) ⇒ Magick::Image

Swirl the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360.

Parameters:

• degrees_obj (Numeric) —

  the degrees

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 14056

VALUE
Image_swirl(VALUE self, VALUE degrees_obj)
{
    Image *image, *new_image;
    ExceptionInfo *exception;
    double degrees = NUM2DBL(degrees_obj);

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(SwirlImage) args = { image, degrees, image->interpolate, exception };
#else
    GVL_STRUCT_TYPE(SwirlImage) args = { image, degrees, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SwirlImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#texture_fill_to_border(x, y, texture) ⇒ Object

Replace neighboring pixels to border color with texture pixels

# File 'lib/rmagick_internal.rb', line 1002

def texture_fill_to_border(x, y, texture)
  texture_flood_fill(border_color, texture, x, y, FillToBorderMethod)
end

#texture_flood_fill(color_obj, texture_obj, x_obj, y_obj, method_obj) ⇒ Magick::Image

Emulates Magick++'s floodFillTexture.

If the FloodfillMethod method is specified, flood-fills texture across pixels starting at the target pixel and matching the specified color.

If the FillToBorderMethod method is specified, flood-fills 'texture across pixels starting at the target pixel and stopping at pixels matching the specified color.'

Parameters:

• color_obj (Magick::Pixel, String) —

  the color

• texture_obj (Magick::Image, Magick::ImageList) —

  the texture to fill

• x_obj (Numeric) —

  the x position

• y_obj (Numeric) —

  the y position

• method_obj (Magick::PaintMethod) —

  the method to call (FloodfillMethod or FillToBorderMethod)

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 14096

VALUE
Image_texture_flood_fill(VALUE self, VALUE color_obj, VALUE texture_obj,
                         VALUE x_obj, VALUE y_obj, VALUE method_obj)
{
    Image *image, *new_image;
    Image *texture_image;
    PixelColor color;
    VALUE texture;
    DrawInfo *draw_info;
    long x, y;
    PaintMethod method;
    MagickPixel color_mpp;
    MagickBooleanType invert;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    Color_to_PixelColor(&color, color_obj);
    texture = rm_cur_image(texture_obj);
    texture_image = rm_check_destroyed(texture);

    x = NUM2LONG(x_obj);
    y = NUM2LONG(y_obj);

    if ((unsigned long)x > image->columns || (unsigned long)y > image->rows)
    {
        rb_raise(rb_eArgError, "target out of range. %ldx%ld given, image is %" RMIuSIZE "x%" RMIuSIZE "",
                 x, y, image->columns, image->rows);
    }

    VALUE_TO_ENUM(method_obj, method, PaintMethod);
    if (method != FillToBorderMethod && method != FloodfillMethod)
    {
        rb_raise(rb_eArgError, "paint method must be FloodfillMethod or "
                 "FillToBorderMethod (%d given)", (int)method);
    }

    draw_info = CloneDrawInfo(NULL, NULL);
    if (!draw_info)
    {
        rb_raise(rb_eNoMemError, "not enough memory to continue");
    }

    draw_info->fill_pattern = rm_clone_image(texture_image);
    new_image = rm_clone_image(image);


    rm_init_magickpixel(new_image, &color_mpp);
    if (method == FillToBorderMethod)
    {
        invert = MagickTrue;
        color_mpp.red   = (MagickRealType) image->border_color.red;
        color_mpp.green = (MagickRealType) image->border_color.green;
        color_mpp.blue  = (MagickRealType) image->border_color.blue;
    }
    else
    {
        invert = MagickFalse;
        color_mpp.red   = (MagickRealType) color.red;
        color_mpp.green = (MagickRealType) color.green;
        color_mpp.blue  = (MagickRealType) color.blue;
    }

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, draw_info, &color_mpp, x, y, invert, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);
    DestroyDrawInfo(draw_info);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(FloodfillPaintImage) args = { new_image, DefaultChannels, draw_info, &color_mpp, x, y, invert };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FloodfillPaintImage), &args);

    DestroyDrawInfo(draw_info);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    RB_GC_GUARD(texture);

    return rm_image_new(new_image);
}

#texture_floodfill(x, y, texture) ⇒ Object

Replace matching neighboring pixels with texture pixels

# File 'lib/rmagick_internal.rb', line 996

def texture_floodfill(x, y, texture)
  target = pixel_color(x, y)
  texture_flood_fill(target, texture, x, y, FloodfillMethod)
end

#threshold(threshold_obj) ⇒ Magick::Image

Change the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image.

Parameters:

• threshold_obj (Numeric) —

  the threshold

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 14189

VALUE
Image_threshold(VALUE self, VALUE threshold_obj)
{
    Image *image, *new_image;
    double threshold = NUM2DBL(threshold_obj);
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);
    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(BilevelImage) args = { new_image, threshold, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BilevelImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(BilevelImageChannel) args = { new_image, DefaultChannels, threshold };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(BilevelImageChannel), &args);
    rm_check_image_exception(new_image, DestroyOnError);
#endif

    return rm_image_new(new_image);
}

#thumbnail(scale) ⇒ Magick::Image #thumbnail(cols, rows) ⇒ Magick::Image

The thumbnail method is a fast resizing method suitable for use when the size of the resulting image is < 10% of the original.

Overloads:

• #thumbnail(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

    The desired size represented as a floating-point number. For example, to make a thumbnail that is 9.5% of the size of the original image, use 0.095.

• #thumbnail(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width in pixels.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #thumbnail!

# File 'ext/RMagick/rmimage.cpp', line 14387

VALUE
Image_thumbnail(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return thumbnail(False, argc, argv, self);
}

#thumbnail!(scale) ⇒ Magick::Image #thumbnail!(cols, rows) ⇒ Magick::Image

The thumbnail method is a fast resizing method suitable for use when the size of the resulting image is < 10% of the original. In-place form of #thumbnail.

Overloads:

• #thumbnail!(scale) ⇒ Magick::Image

  Parameters:

  • scale (Numeric) —

    The desired size represented as a floating-point number. For example, to make a thumbnail that is 9.5% of the size of the original image, use 0.095.

• #thumbnail!(cols, rows) ⇒ Magick::Image

  Parameters:

  • cols (Numeric) —

    The desired width in pixels.

  • rows (Numeric) —

    The desired height.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #thumbnail

# File 'ext/RMagick/rmimage.cpp', line 14410

VALUE
Image_thumbnail_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return thumbnail(True, argc, argv, self);
}

#ticks_per_second ⇒ Integer

Get the number of ticks per second. This attribute is used in conjunction with the delay attribute to establish the amount of time that must elapse between frames in an animation.The default is 100.

Returns:

• (Integer) —

  ticks per second

# File 'ext/RMagick/rmimage.cpp', line 14425

VALUE
Image_ticks_per_second(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return INT2FIX(image->ticks_per_second);
}

#ticks_per_second=(tps) ⇒ Numeric

Set the number of ticks per second. This attribute is used in conjunction with the delay attribute to establish the amount of time that must elapse between frames in an animation.The default is 100.

Parameters:

• tps (Numeric) —

  ticks per second

Returns:

• (Numeric) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 14441

VALUE
Image_ticks_per_second_eq(VALUE self, VALUE tps)
{
    Image *image = rm_check_frozen(self);
    image->ticks_per_second = NUM2ULONG(tps);
    return tps;
}

#tint(tint, red_alpha, green_alpha = red_alpha, blue_alpha = red_alpha, alpha_alpha = 1.0) ⇒ Object

Applies a color vector to each pixel in the image.

• Alpha values are percentages: 0.10 -> 10%.

Returns a new image.

Parameters:

• tint (Magick::Pixel, String) —

  the color name

• red_alpha (Numeric) —

  the red value

• green_alpha (Numeric) (defaults to: red_alpha) —

  the green value

• blue_alpha (Numeric) (defaults to: red_alpha) —

  the blue value

• alpha_alpha (Numeric) (defaults to: 1.0) —

  the alpha value

Returns:

• a new image

# File 'ext/RMagick/rmimage.cpp', line 14463

VALUE
Image_tint(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    PixelColor tint;
    double red_pct_opaque, green_pct_opaque, blue_pct_opaque;
    double alpha_pct_opaque = 1.0;
    char alpha[50];
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    switch (argc)
    {
        case 2:
            red_pct_opaque   = NUM2DBL(argv[1]);
            green_pct_opaque = blue_pct_opaque = red_pct_opaque;
            break;
        case 3:
            red_pct_opaque   = NUM2DBL(argv[1]);
            green_pct_opaque = NUM2DBL(argv[2]);
            blue_pct_opaque  = red_pct_opaque;
            break;
        case 4:
            red_pct_opaque     = NUM2DBL(argv[1]);
            green_pct_opaque   = NUM2DBL(argv[2]);
            blue_pct_opaque    = NUM2DBL(argv[3]);
            break;
        case 5:
            red_pct_opaque     = NUM2DBL(argv[1]);
            green_pct_opaque   = NUM2DBL(argv[2]);
            blue_pct_opaque    = NUM2DBL(argv[3]);
            alpha_pct_opaque   = NUM2DBL(argv[4]);
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 2 to 5)", argc);
            break;
    }

    if (red_pct_opaque < 0.0 || green_pct_opaque < 0.0
        || blue_pct_opaque < 0.0 || alpha_pct_opaque < 0.0)
    {
        rb_raise(rb_eArgError, "alpha percentages must be non-negative.");
    }

    snprintf(alpha, sizeof(alpha),
            "%g,%g,%g,%g", red_pct_opaque*100.0, green_pct_opaque*100.0,
            blue_pct_opaque*100.0, alpha_pct_opaque*100.0);

    Color_to_PixelColor(&tint, argv[0]);
    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(TintImage) args = { image, alpha, &tint, exception };
#else
    GVL_STRUCT_TYPE(TintImage) args = { image, alpha, tint, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TintImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#to_blob {|info| ... } ⇒ String

Return a "blob" (a String) from the image.

• The magick member of the Image structure determines the format of the returned blob (GIG, JPEG, PNG, etc.)

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (String) —

  the blob

See Also:

• from_blob

# File 'ext/RMagick/rmimage.cpp', line 14539

VALUE
Image_to_blob(VALUE self)
{
    Image *image;
    Info *info;
    const MagickInfo *magick_info;
    VALUE info_obj;
    VALUE blob_str;
    void *blob = NULL;
    size_t length = 2048;       // Do what Magick++ does
    ExceptionInfo *exception;

    // The user can specify the depth (8 or 16, if the format supports
    // both) and the image format by setting the depth and format
    // values in the info parm block.
    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

    image = rm_check_destroyed(self);

    exception = AcquireExceptionInfo();

    // Copy the depth and magick fields to the Image
    if (info->depth != 0)
    {
#if defined(IMAGEMAGICK_7)
        GVL_STRUCT_TYPE(SetImageDepth) args = { image, info->depth, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageDepth), &args);
        CHECK_EXCEPTION();
#else
        GVL_STRUCT_TYPE(SetImageDepth) args = { image, info->depth };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageDepth), &args);
        rm_check_image_exception(image, RetainOnError);
#endif
    }

    if (*info->magick)
    {
        SetImageInfo(info, MagickTrue, exception);
        CHECK_EXCEPTION();

        if (*info->magick == '\0')
        {
            return Qnil;
        }
        strlcpy(image->magick, info->magick, sizeof(image->magick));
    }

    // Fix #2844 - libjpeg exits when image is 0x0
    magick_info = GetMagickInfo(image->magick, exception);
    CHECK_EXCEPTION();

    if (magick_info)
    {
        if (  (!rm_strcasecmp(magick_info->name, "JPEG")
               || !rm_strcasecmp(magick_info->name, "JPG"))
              && (image->rows == 0 || image->columns == 0))
        {
            rb_raise(rb_eRuntimeError, "Can't convert %" RMIuSIZE "x%" RMIuSIZE " %.4s image to a blob",
                     image->columns, image->rows, magick_info->name);
        }
    }

    rm_sync_image_options(image, info);

    GVL_STRUCT_TYPE(ImageToBlob) args = { info, image, &length, exception };
    blob = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ImageToBlob), &args);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    if (length == 0 || !blob)
    {
        return Qnil;
    }

    blob_str = rb_str_new((const char *)blob, length);

    magick_free((void*)blob);

    RB_GC_GUARD(info_obj);
    RB_GC_GUARD(blob_str);

    return blob_str;
}

#to_color(pixel_arg) ⇒ String

Return a color name for the color intensity specified by the Magick::Pixel argument.

Parameters:

• pixel_arg (Magick::Pixel, String) —

  the pixel

Returns:

• (String) —

  the color name

# File 'ext/RMagick/rmimage.cpp', line 14632

VALUE
Image_to_color(VALUE self, VALUE pixel_arg)
{
    Image *image;
    PixelColor pixel;
    ExceptionInfo *exception;
    char name[MaxTextExtent];

    image = rm_check_destroyed(self);
    Color_to_PixelColor(&pixel, pixel_arg);
    exception = AcquireExceptionInfo();

#if defined(IMAGEMAGICK_7)
    pixel.depth = MAGICKCORE_QUANTUM_DEPTH;
    pixel.colorspace = image->colorspace;
#endif

    // QueryColorname returns False if the color represented by the PixelPacket
    // doesn't have a "real" name, just a sequence of hex digits. We don't care
    // about that.

    QueryColorname(image, &pixel, AllCompliance, name, exception);
    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    return rb_str_new2(name);

}

#total_colors ⇒ Integer

Alias for #number_colors.

Returns:

• (Integer) —

  number of unique colors

See Also:

• #number_colors

# File 'ext/RMagick/rmimage.cpp', line 14669

VALUE
Image_total_colors(VALUE self)
{
    return Image_number_colors(self);
}

#total_ink_density ⇒ Float

Return the total ink density for a CMYK image.

Returns:

• (Float) —

  the total ink density

# File 'ext/RMagick/rmimage.cpp', line 14681

VALUE
Image_total_ink_density(VALUE self)
{
    Image *image;
    double density;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    density = GetImageTotalInkDensity(image, exception);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    density = GetImageTotalInkDensity(image);
    rm_check_image_exception(image, RetainOnError);
#endif

    return rb_float_new(density);
}

#transparent(color, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

Changes the opacity value of all the pixels that match color to the value specified by opacity. By default the pixel must match exactly, but you can specify a tolerance level by setting the fuzz attribute on the image.

• Default alpha is Magick::TransparentAlpha.
• Can use Magick::OpaqueAlpha or Magick::TransparentAlpha, or any value >= 0 && <= QuantumRange.
• Use Image#fuzz= to define the tolerance level.

Returns a new image.

Parameters:

• color (Magick::Pixel, String) —

  The color

• alpha (defaults to: Magick::TransparentAlpha) —

  alpha [Numeric] the alpha

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 14721

VALUE
Image_transparent(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    MagickPixel color;
    Quantum alpha = TransparentAlpha;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif
    VALUE color_obj, kwargs;

    image = rm_check_destroyed(self);

    rb_scan_args(argc, argv, "1:", &color_obj, &kwargs);
    Color_to_MagickPixel(image, &color, color_obj);
    if (RTEST(kwargs))
    {
        alpha = get_named_alpha_value(kwargs);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(TransparentPaintImage) args = { new_image, &color, alpha, MagickFalse, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(TransparentPaintImage) args = { new_image, &color, (Quantum)(QuantumRange - alpha), MagickFalse };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImage), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(new_image, DestroyOnError);
#endif
    if (!okay)
    {
        // Force exception
        DestroyImage(new_image);
        rm_magick_error("TransparentPaintImage failed with no explanation");
    }

    return rm_image_new(new_image);
}

#transparent_chroma(low, high, invert, alpha: Magick::TransparentAlpha) ⇒ Magick::Image

Changes the opacity value associated with any pixel between low and high to the value defined by opacity.

As there is one fuzz value for the all the channels, the transparent method is not suitable for the operations like chroma, where the tolerance for similarity of two color components (RGB) can be different, Thus we define this method take two target pixels (one low and one high) and all the pixels of an image which are lying between these two pixels are made transparent.

Returns a new image.

Parameters:

• low (Magick::Pixel, String) —

  The low ends of the pixel range

• high (Magick::Pixel, String) —

  The high ends of the pixel range

• invert (Boolean) —

  If true, all pixels outside the range are set to opacity.

• alpha (Numeric) (defaults to: Magick::TransparentAlpha) —

  The desired alpha.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 14784

VALUE
Image_transparent_chroma(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    Quantum alpha = TransparentAlpha;
    MagickPixel low, high;
    MagickBooleanType invert = MagickFalse;
    MagickBooleanType okay;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif
    VALUE low_obj, high_obj, invert_obj, kwargs;

    image = rm_check_destroyed(self);

    rb_scan_args(argc, argv, "21:", &low_obj, &high_obj, &invert_obj, &kwargs);

    Color_to_MagickPixel(image, &low, low_obj);
    Color_to_MagickPixel(image, &high, high_obj);
    if (invert_obj != Qnil)
    {
        invert = (MagickBooleanType)RTEST(invert_obj);
    }
    if (RTEST(kwargs))
    {
        alpha = get_named_alpha_value(kwargs);
    }

    new_image = rm_clone_image(image);

#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(TransparentPaintImageChroma) args = { new_image, &low, &high, alpha, invert, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImageChroma), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(TransparentPaintImageChroma) args = { new_image, &low, &high, (Quantum)(QuantumRange - alpha), invert };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(TransparentPaintImageChroma), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));
    rm_check_image_exception(new_image, DestroyOnError);
#endif
    if (!okay)
    {
        // Force exception
        DestroyImage(new_image);
        rm_magick_error("TransparentPaintImageChroma failed with no explanation");
    }

    return rm_image_new(new_image);
}

#transparent_color ⇒ String

Return the name of the transparent color as a String.

Returns:

• (String) —

  the name of the transparent color

# File 'ext/RMagick/rmimage.cpp', line 14843

VALUE
Image_transparent_color(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return rm_pixelcolor_to_color_name(image, &image->transparent_color);
}

#transparent_color=(color) ⇒ Magick::Pixel, String

Set the the transparent color to the specified color spec.

Parameters:

• color (Magick::Pixel, String) —

  the transparent color

Returns:

• (Magick::Pixel, String) —

  the given color

# File 'ext/RMagick/rmimage.cpp', line 14857

VALUE
Image_transparent_color_eq(VALUE self, VALUE color)
{
    Image *image = rm_check_frozen(self);
    Color_to_PixelColor(&image->transparent_color, color);
    return color;
}

#transpose ⇒ Magick::Image

Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them by 90 degrees.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #transpose!

# File 'ext/RMagick/rmimage.cpp', line 14873

VALUE
Image_transpose(VALUE self)
{
    rm_check_destroyed(self);
    return crisscross(False, self, GVL_FUNC(TransposeImage));
}

#transpose! ⇒ Magick::Image

Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them by 90 degrees. In-place form of #transpose.

Returns:

• (Magick::Image) —

  self

See Also:

• #transpose

# File 'ext/RMagick/rmimage.cpp', line 14889

VALUE
Image_transpose_bang(VALUE self)
{
    rm_check_frozen(self);
    return crisscross(True, self, GVL_FUNC(TransposeImage));
}

#transverse ⇒ Magick::Image

Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them by 270 degrees

Returns:

• (Magick::Image) —

  a new image

See Also:

• #transverse!

# File 'ext/RMagick/rmimage.cpp', line 14904

VALUE
Image_transverse(VALUE self)
{
    rm_check_destroyed(self);
    return crisscross(False, self, GVL_FUNC(TransverseImage));
}

#transverse! ⇒ Magick::Image

Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them by 270 degrees In-place form of #transverse.

Returns:

• (Magick::Image) —

  self

See Also:

• #transverse

# File 'ext/RMagick/rmimage.cpp', line 14919

VALUE
Image_transverse_bang(VALUE self)
{
    rm_check_frozen(self);
    return crisscross(True, self, GVL_FUNC(TransverseImage));
}

#trim(reset = false) ⇒ Magick::Image

Removes the edges that are exactly the same color as the corner pixels. Use the fuzz attribute to make trim remove edges that are nearly the same color as the corner pixels.

Returns a new image.

Parameters:

• reset (Boolean) (defaults to: false) —

  The trim method retains the offset information in the cropped image. This may cause the image to appear to be surrounded by blank or black space when viewed with an external viewer. This only occurs when the image is saved in a format (such as GIF) that saves offset information. To reset the offset data, use true as the argument to trim.

Returns:

• (Magick::Image) —

  a new image

See Also:

• #trim!

# File 'ext/RMagick/rmimage.cpp', line 14999

VALUE
Image_trim(int argc, VALUE *argv, VALUE self)
{
    rm_check_destroyed(self);
    return trimmer(False, argc, argv, self);
}

#trim!(reset = false) ⇒ Magick::Image

Removes the edges that are exactly the same color as the corner pixels. Use the fuzz attribute to make trim remove edges that are nearly the same color as the corner pixels.

Returns self.

Parameters:

• reset (Boolean) (defaults to: false) —

  The trim method retains the offset information in the cropped image. This may cause the image to appear to be surrounded by blank or black space when viewed with an external viewer. This only occurs when the image is saved in a format (such as GIF) that saves offset information. To reset the offset data, use true as the argument to trim.

Returns:

• (Magick::Image) —

  self

See Also:

• #trim

# File 'ext/RMagick/rmimage.cpp', line 15019

VALUE
Image_trim_bang(int argc, VALUE *argv, VALUE self)
{
    rm_check_frozen(self);
    return trimmer(True, argc, argv, self);
}

#undefine(artifact) ⇒ Magick::Image

Removes an artifact from the image and returns its value.

Parameters:

• artifact (String) —

  the artifact

Returns:

• (Magick::Image) —

  self

See Also:

• #define

# File 'ext/RMagick/rmimage.cpp', line 15118

VALUE
Image_undefine(VALUE self, VALUE artifact)
{
    Image *image;
    char *key;

    image = rm_check_frozen(self);
    key = StringValueCStr(artifact);
    DeleteImageArtifact(image, key);
    return self;
}

#unique_colors ⇒ Magick::Image

Constructs a new image with one pixel for each unique color in the image. The new image has 1 row. The row has 1 column for each unique pixel in the image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15137

VALUE
Image_unique_colors(VALUE self)
{
    Image *image, *new_image;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(UniqueImageColors) args = { image, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(UniqueImageColors), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#units ⇒ Magick::ResolutionType

Get the units of image resolution.

Returns:

• (Magick::ResolutionType) —

  the resolution type

# File 'ext/RMagick/rmimage.cpp', line 15160

VALUE
Image_units(VALUE self)
{
    Image *image = rm_check_destroyed(self);
    return ResolutionType_find(image->units);
}

#units=(restype) ⇒ Magick::ResolutionType

Set the units of image resolution.

Parameters:

• restype (Magick::ResolutionType) —

  the resolution type

Returns:

• (Magick::ResolutionType) —

  the given value

# File 'ext/RMagick/rmimage.cpp', line 15174

VALUE
Image_units_eq(VALUE self, VALUE restype)
{
    ResolutionType units;
    Image *image = rm_check_frozen(self);

    VALUE_TO_ENUM(restype, units, ResolutionType);

    if (image->units != units)
    {
        switch (image->units)
        {
            case PixelsPerInchResolution:
                if (units == PixelsPerCentimeterResolution)
                {
#if defined(IMAGEMAGICK_7)
                    image->resolution.x /= 2.54;
                    image->resolution.y /= 2.54;
#else
                    image->x_resolution /= 2.54;
                    image->y_resolution /= 2.54;
#endif
                }
                break;

            case PixelsPerCentimeterResolution:
                if (units == PixelsPerInchResolution)
                {
#if defined(IMAGEMAGICK_7)
                    image->resolution.x *= 2.54;
                    image->resolution.y *= 2.54;
#else
                    image->x_resolution *= 2.54;
                    image->y_resolution *= 2.54;
#endif
                }
                break;

            default:
                // UndefinedResolution
#if defined(IMAGEMAGICK_7)
                image->resolution.x = 0.0;
                image->resolution.y = 0.0;
#else
                image->x_resolution = 0.0;
                image->y_resolution = 0.0;
#endif
                break;
        }

        image->units = units;
    }

    return restype;
}

#unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05) ⇒ Magick::Image

Sharpen an image. "amount" is the percentage of the difference between the original and the blur image that is added back into the original. "threshold" is the threshold in pixels needed to apply the diffence amount.

Returns a new image.

Parameters:

• radius (Numeric) (defaults to: 0.0) —

  The radius of the Gaussian operator.

• sigma (Numeric) (defaults to: 1.0) —

  The standard deviation of the Gaussian operator.

• amount (Numeric) (defaults to: 1.0) —

  The percentage of the blurred image to be added to the receiver, specified as a fraction between 0 and 1.0

• threshold (Numeric) (defaults to: 0.05) —

  The threshold needed to apply the amount, specified as a fraction between 0 and 1.0

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15301

VALUE
Image_unsharp_mask(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    unsharp_mask_args(argc, argv, &radius, &sigma, &amount, &threshold);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(UnsharpMaskImage) args = { image, radius, sigma, amount, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(UnsharpMaskImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05, channel = Magick::AllChannels) ⇒ Magick::Image #unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05, *channels) ⇒ Magick::Image

Sharpen an image. "amount" is the percentage of the difference between the original and the blur image that is added back into the original. "threshold" is the threshold in pixels needed to apply the diffence amount.

Only the specified channels are sharpened.

Overloads:

• #unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05, channel = Magick::AllChannels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Gaussian operator.

  • amount (Numeric) (defaults to: 1.0) —

    The percentage of the blurred image to be added to the receiver, specified as a fraction between 0 and 1.0

  • threshold (Numeric) (defaults to: 0.05) —

    The threshold needed to apply the amount, specified as a fraction between 0 and 1.0

  • channel (Magick::ChannelType) (defaults to: Magick::AllChannels) —

    a ChannelType arguments.

• #unsharp_mask(radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05, *channels) ⇒ Magick::Image

  Parameters:

  • radius (Numeric) (defaults to: 0.0) —

    The radius of the Gaussian operator.

  • sigma (Numeric) (defaults to: 1.0) —

    The standard deviation of the Gaussian operator.

  • amount (Numeric) (defaults to: 1.0) —

    The percentage of the blurred image to be added to the receiver, specified as a fraction between 0 and 1.0

  • threshold (Numeric) (defaults to: 0.05) —

    The threshold needed to apply the amount, specified as a fraction between 0 and 1.0

  • *channels (Magick::ChannelType) —

    one or more ChannelType arguments.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15349

VALUE
Image_unsharp_mask_channel(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    ChannelType channels;
    double radius = 0.0, sigma = 1.0, amount = 1.0, threshold = 0.05;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    channels = extract_channels(&argc, argv);
    if (argc > 4)
    {
        raise_ChannelType_error(argv[argc-1]);
    }

    unsharp_mask_args(argc, argv, &radius, &sigma, &amount, &threshold);

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    BEGIN_CHANNEL_MASK(image, channels);
    GVL_STRUCT_TYPE(UnsharpMaskImage) args = { image, radius, sigma, amount, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(UnsharpMaskImage), &args);
    CHANGE_RESULT_CHANNEL_MASK(new_image);
    END_CHANNEL_MASK(image);
#else
    GVL_STRUCT_TYPE(UnsharpMaskImageChannel) args = { image, channels, radius, sigma, amount, threshold, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(UnsharpMaskImageChannel), &args);
#endif
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#view(x, y, width, height) ⇒ Object

Construct a view. If a block is present, yield and pass the view object, otherwise return the view object.

# File 'lib/rmagick_internal.rb', line 1008

def view(x, y, width, height)
  view = View.new(self, x, y, width, height)

  return view unless block_given?

  begin
    yield(view)
  ensure
    view.sync
  end
  nil
end

#vignette(horz_radius = self.columns*0.1+0.5, vert_radius = self.rows*0.1+0.5, radius = 0.0, sigma = 1.0) ⇒ Magick::Image

Soften the edges of an image.

Returns a new image.

Parameters:

• horz_radius (Numeric) (defaults to: self.columns*0.1+0.5) —

  Influences the amount of background color in the horizontal dimension.

• vert_radius (Numeric) (defaults to: self.rows*0.1+0.5) —

  Influences the amount of background color in the vertical dimension.

• radius (Numeric) (defaults to: 0.0) —

  Controls the amount of blurring.

• sigma (Numeric) (defaults to: 1.0) —

  Controls the amount of blurring.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15394

VALUE
Image_vignette(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    long horz_radius, vert_radius;
    double radius = 0.0, sigma = 10.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);

    horz_radius = (long)(image->columns * 0.10 + 0.5);
    vert_radius = (long)(image->rows * 0.10 + 0.5);

    switch (argc)
    {
        case 4:
            sigma = NUM2DBL(argv[3]);
        case 3:
            radius = NUM2DBL(argv[2]);
        case 2:
            vert_radius = NUM2INT(argv[1]);
        case 1:
            horz_radius = NUM2INT(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 4)", argc);
            break;
    }

    exception = AcquireExceptionInfo();

    GVL_STRUCT_TYPE(VignetteImage) args = { image, radius, sigma, horz_radius, vert_radius, exception };
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(VignetteImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#virtual_pixel_method ⇒ Magick::VirtualPixelMethod

Get the "virtual pixels" behave. Virtual pixels are pixels that are outside the boundaries of the image.

Returns:

• (Magick::VirtualPixelMethod) —

  the VirtualPixelMethod

# File 'ext/RMagick/rmimage.cpp', line 15441

VALUE
Image_virtual_pixel_method(VALUE self)
{
    Image *image;
    VirtualPixelMethod vpm;

    image = rm_check_destroyed(self);
    vpm = GetImageVirtualPixelMethod(image);
    return VirtualPixelMethod_find(vpm);
}

#virtual_pixel_method=(method) ⇒ Magick::VirtualPixelMethod

Specify how "virtual pixels" behave. Virtual pixels are pixels that are outside the boundaries of the image.

Parameters:

• method (Magick::VirtualPixelMethod) —

  the VirtualPixelMethod

Returns:

• (Magick::VirtualPixelMethod) —

  the given method

# File 'ext/RMagick/rmimage.cpp', line 15460

VALUE
Image_virtual_pixel_method_eq(VALUE self, VALUE method)
{
    Image *image;
    VirtualPixelMethod vpm;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_frozen(self);
    VALUE_TO_ENUM(method, vpm, VirtualPixelMethod);
#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    SetImageVirtualPixelMethod(image, vpm, exception);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    SetImageVirtualPixelMethod(image, vpm);
    rm_check_image_exception(image, RetainOnError);
#endif
    return method;
}

#watermark(mark, brightness = 1.0, saturation = 1.0, x_off = 0, y_off = 0) ⇒ Magick::Image #watermark(mark, brightness, saturation, gravity, x_off = 0, y_off = 0) ⇒ Magick::Image

Composites a watermark image on the target image using the Modulate composite operator. This composite operation operates in the HSL colorspace and combines part of the lightness, part of the saturation, and all of the hue of each pixel in the watermark with the corresponding pixel in the target image

Overloads:

• #watermark(mark, brightness = 1.0, saturation = 1.0, x_off = 0, y_off = 0) ⇒ Magick::Image

  Parameters:

  • mark (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • brightness (Numeric, String) (defaults to: 1.0) —

    The fraction of the lightness component of the watermark pixels to be composited onto the target image. Must be a non-negative number or a string in the form "NN%". If lightness is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. The default is 100%.

  • saturation (Numeric, String) (defaults to: 1.0) —

    The fraction of the saturation component of the watermark pixels to be composited onto the target image. Must be a non-negative number or a string in the form "NN%". If lightness is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. The default is 100%.

  • x_off (Numeric) (defaults to: 0) —

    The offset of the watermark, measured from the left-hand side of the target image.

  • y_off (Numeri) (defaults to: 0) —

    The offset of the watermark, measured from the top of the target image.

• #watermark(mark, brightness, saturation, gravity, x_off = 0, y_off = 0) ⇒ Magick::Image

  Parameters:

  • mark (Magick::Image, Magick::ImageList) —

    Either an imagelist or an image. If an imagelist, uses the current image.

  • brightness (Numeric, String) —

    The fraction of the lightness component of the watermark pixels to be composited onto the target image. Must be a non-negative number or a string in the form "NN%". If lightness is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. The default is 100%.

  • saturation (Numeric, String) —

    The fraction of the saturation component of the watermark pixels to be composited onto the target image. Must be a non-negative number or a string in the form "NN%". If lightness is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. The default is 100%.

  • gravity (Magick::GravityType) —

    the gravity for offset. the offsets are measured from the NorthWest corner by default.

  • x_off (Numeric) (defaults to: 0) —

    The offset of the watermark, measured from the left-hand side of the target image.

  • y_off (Numeri) (defaults to: 0) —

    The offset of the watermark, measured from the top of the target image.

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15524

VALUE
Image_watermark(int argc, VALUE *argv, VALUE self)
{
    Image *image, *overlay, *new_image;
    double src_percent = 100.0, dst_percent = 100.0;
    long x_offset = 0L, y_offset = 0L;
    char geometry[20];
    VALUE ovly;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    if (argc < 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 6)", argc);
    }

    ovly = rm_cur_image(argv[0]);
    overlay = rm_check_destroyed(ovly);

    if (argc > 3)
    {
        get_composite_offsets(argc-3, &argv[3], image, overlay, &x_offset, &y_offset);
        // There must be 3 arguments left
        argc = 3;
    }

    switch (argc)
    {
        case 3:
            dst_percent = rm_percentage(argv[2], 1.0) * 100.0;
        case 2:
            src_percent = rm_percentage(argv[1], 1.0) * 100.0;
        case 1:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 1 to 6)", argc);
            break;
    }

    blend_geometry(geometry, sizeof(geometry), src_percent, dst_percent);
    CloneString(&overlay->geometry, geometry);
    SetImageArtifact(overlay, "compose:args", geometry);

    new_image = rm_clone_image(image);
#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(CompositeImage) args = { new_image, overlay, ModulateCompositeOp, MagickTrue, x_offset, y_offset, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompositeImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(CompositeImage) args = { new_image, ModulateCompositeOp, overlay, x_offset, y_offset };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CompositeImage), &args);

    rm_check_image_exception(new_image, DestroyOnError);
#endif

    RB_GC_GUARD(ovly);

    return rm_image_new(new_image);
}

#wave(amplitude = 25.0, wavelength = 150.0) ⇒ Magick::Image

Create a "ripple" effect in the image by shifting the pixels vertically along a sine wave whose amplitude and wavelength is specified by the given parameters.

Returns a new image.

Parameters:

• amplitude (Numeric) (defaults to: 25.0) —

  the amplitude

• wavelength (Numeric) (defaults to: 150.0) —

  the wave length

Returns:

• (Magick::Image) —

  a new image

# File 'ext/RMagick/rmimage.cpp', line 15599

VALUE
Image_wave(int argc, VALUE *argv, VALUE self)
{
    Image *image, *new_image;
    double amplitude = 25.0, wavelength = 150.0;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 2:
            wavelength = NUM2DBL(argv[1]);
        case 1:
            amplitude = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 2)", argc);
            break;
    }

    exception = AcquireExceptionInfo();
#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(WaveImage) args = { image, amplitude, wavelength, image->interpolate, exception };
#else
    GVL_STRUCT_TYPE(WaveImage) args = { image, amplitude, wavelength, exception };
#endif
    new_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(WaveImage), &args);
    rm_check_exception(exception, new_image, DestroyOnError);
    DestroyExceptionInfo(exception);

    return rm_image_new(new_image);
}

#wet_floor(initial = 0.5, rate = 1.0) ⇒ Magick::Image

Creates a "wet floor" reflection. The reflection is an inverted copy of the image that changes from partially transparent to entirely transparent. By default only the bottom third of the image appears in the reflection.

Returns a new image.

Parameters:

• initial (Numeric) (defaults to: 0.5) —

  A value between 0.0 and 1.0 that specifies the initial percentage of transparency. Higher values cause the top of the reflection to be more transparent, lower values less transparent. The default is 0.5, which means that the top of the reflection is 50% transparent.

• rate (Numeric) (defaults to: 1.0) —

  A non-negative value that specifies how rapidly the reflection transitions from the initial level of transparency to entirely transparent. The default value is 1.0, which means that the transition occurs in 1/3 the image height. Values greater than 1.0 speed up the transition (the reflection will have fewer rows), values lower than 1.0 slow down the transition (the reflection will have more rows). A value of 0.0 means that the level of transparency will not change.

Returns:

• (Magick::Image) —

  a new image

See Also:

• http://en.wikipedia.org/wiki/Wet_floor_effect

# File 'ext/RMagick/rmimage.cpp', line 15653

VALUE
Image_wet_floor(int argc, VALUE *argv, VALUE self)
{
    Image *image, *reflection, *flip_image;
#if defined(IMAGEMAGICK_7)
    const Quantum *p;
    Quantum *q;
#else
    const PixelPacket *p;
    PixelPacket *q;
#endif
    RectangleInfo geometry;
    long x, y, max_rows;
    double initial = 0.5;
    double rate = 1.0;
    double opacity, step;
    const char *func;
    ExceptionInfo *exception;

    image = rm_check_destroyed(self);
    switch (argc)
    {
        case 2:
            rate = NUM2DBL(argv[1]);
        case 1:
            initial = NUM2DBL(argv[0]);
        case 0:
            break;
        default:
            rb_raise(rb_eArgError, "wrong number of arguments (%d for 0 to 2)", argc);
            break;
    }


    if (initial < 0.0 || initial > 1.0)
    {
        rb_raise(rb_eArgError, "Initial transparency must be in the range 0.0-1.0 (%g)", initial);
    }
    if (rate < 0.0)
    {
        rb_raise(rb_eArgError, "Transparency change rate must be >= 0.0 (%g)", rate);
    }

#if defined(IMAGEMAGICK_7)
    initial *= QuantumRange;
#else
    initial *= TransparentOpacity;
#endif

    // The number of rows in which to transition from the initial level of
    // transparency to complete transparency. rate == 0.0 -> no change.
    if (rate > 0.0)
    {
        max_rows = (long)((double)image->rows) / (3.0 * rate);
        max_rows = (long)min((unsigned long)max_rows, image->rows);
#if defined(IMAGEMAGICK_7)
        step =  (QuantumRange - initial) / max_rows;
#else
        step =  (TransparentOpacity - initial) / max_rows;
#endif
    }
    else
    {
        max_rows = (long)image->rows;
        step = 0.0;
    }


    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(FlipImage) args_FlipImage = { image, exception };
    flip_image = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(FlipImage), &args_FlipImage);
    CHECK_EXCEPTION();


    geometry.x = 0;
    geometry.y = 0;
    geometry.width = image->columns;
    geometry.height = max_rows;
    GVL_STRUCT_TYPE(CropImage) args_CropImage = { flip_image, &geometry, exception };
    reflection = (Image *)CALL_FUNC_WITHOUT_GVL(GVL_FUNC(CropImage), &args_CropImage);
    DestroyImage(flip_image);
    CHECK_EXCEPTION();


#if defined(IMAGEMAGICK_7)
    GVL_STRUCT_TYPE(SetImageStorageClass) args_SetImageStorageClass = { reflection, DirectClass, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args_SetImageStorageClass);
    rm_check_exception(exception, reflection, DestroyOnError);
    GVL_STRUCT_TYPE(SetImageAlphaChannel) args_SetImageAlphaChannel = { reflection, ActivateAlphaChannel, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageAlphaChannel), &args_SetImageAlphaChannel);
    rm_check_exception(exception, reflection, DestroyOnError);
#else
    GVL_STRUCT_TYPE(SetImageStorageClass) args_SetImageStorageClass = { reflection, DirectClass };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SetImageStorageClass), &args_SetImageStorageClass);
    rm_check_image_exception(reflection, DestroyOnError);


    reflection->matte = MagickTrue;
#endif
    opacity = initial;

    for (y = 0; y < max_rows; y++)
    {
#if defined(IMAGEMAGICK_7)
        if (opacity > QuantumRange)
        {
            opacity = QuantumRange;
        }
#else
        if (opacity > TransparentOpacity)
        {
            opacity = TransparentOpacity;
        }
#endif

        GVL_STRUCT_TYPE(GetVirtualPixels) args_GetVirtualPixels = { reflection, 0, y, image->columns, 1, exception };
        void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(GetVirtualPixels), &args_GetVirtualPixels);
        p = reinterpret_cast<decltype(p)>(ret);
        rm_check_exception(exception, reflection, DestroyOnError);
        if (!p)
        {
            func = "AcquireImagePixels";
            goto error;
        }

        q = QueueAuthenticPixels(reflection, 0, y, image->columns, 1, exception);

        rm_check_exception(exception, reflection, DestroyOnError);
        if (!q)
        {
            func = "SetImagePixels";
            goto error;
        }

        for (x = 0; x < (long) image->columns; x++)
        {
            // Never make a pixel *less* transparent than it already is.
#if defined(IMAGEMAGICK_7)
            *q = *p;
            SetPixelAlpha(reflection, min(GetPixelAlpha(image, q), QuantumRange - (Quantum)opacity), q);

            p += GetPixelChannels(reflection);
            q += GetPixelChannels(reflection);
#else
            q[x] = p[x];
            q[x].opacity = max(q[x].opacity, (Quantum)opacity);
#endif
        }

        GVL_STRUCT_TYPE(SyncAuthenticPixels) args_SyncAuthenticPixels = { reflection, exception };
        CALL_FUNC_WITHOUT_GVL(GVL_FUNC(SyncAuthenticPixels), &args_SyncAuthenticPixels);
        rm_check_exception(exception, reflection, DestroyOnError);

        opacity += step;
    }


    DestroyExceptionInfo(exception);
    return rm_image_new(reflection);

    error:
    DestroyExceptionInfo(exception);
    DestroyImage(reflection);
    rb_raise(rb_eRuntimeError, "%s failed on row %lu", func, y);
    return(VALUE)0;
}

#white_threshold(red, green, blue, alpha: alpha) ⇒ Magick::Image

Forces all pixels above the threshold into white while leaving all pixels below the threshold unchanged.

Returns a new image.

Parameters:

• red (Numeric) —

  the number for red channel

• green (Numeric) —

  the number for green channel

• blue (Numeric) —

  the number for blue channel

• alpha (Numeric) (defaults to: alpha) —

  the number for alpha channel

Returns:

• (Magick::Image) —

  a new image

See Also:

• #black_threshold

# File 'ext/RMagick/rmimage.cpp', line 15833

VALUE
Image_white_threshold(int argc, VALUE *argv, VALUE self)
{
    return threshold_image(argc, argv, self, GVL_FUNC(WhiteThresholdImage));
}

#write(file) {|info| ... } ⇒ Magick::Image

Write the image to the file.

Parameters:

• file (File, String) —

  the file

Yields:

• (info)

Yield Parameters:

• info (Magick::Image::Info)

Returns:

• (Magick::Image) —

  self

# File 'ext/RMagick/rmimage.cpp', line 15945

VALUE
Image_write(VALUE self, VALUE file)
{
    Image *image;
    Info *info;
    VALUE info_obj;
#if defined(IMAGEMAGICK_7)
    ExceptionInfo *exception;
#endif

    image = rm_check_destroyed(self);

    info_obj = rm_info_new();
    TypedData_Get_Struct(info_obj, Info, &rm_info_data_type, info);

    if (TYPE(file) == T_FILE)
    {
        rb_io_t *fptr;

        // Ensure file is open - raise error if not
        GetOpenFile(file, fptr);
        rb_io_check_writable(fptr);

        add_format_prefix(info, rm_io_path(file));
#if defined(_WIN32) && !defined(IMAGEMAGICK_GREATER_THAN_EQUAL_7_1_2)
        SetImageInfoFile(info, NULL);
#else
        SetImageInfoFile(info, rb_io_stdio_file(fptr));
#endif
    }
    else
    {
        add_format_prefix(info, file);
        SetImageInfoFile(info, NULL);
    }
    strlcpy(image->filename, info->filename, sizeof(image->filename));

    rm_sync_image_options(image, info);

    info->adjoin = MagickFalse;
#if defined(IMAGEMAGICK_7)
    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(WriteImage) args = { info, image, exception };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(WriteImage), &args);
    CHECK_EXCEPTION();
    DestroyExceptionInfo(exception);
#else
    GVL_STRUCT_TYPE(WriteImage) args = { info, image };
    CALL_FUNC_WITHOUT_GVL(GVL_FUNC(WriteImage), &args);
    rm_check_image_exception(image, RetainOnError);
#endif

    RB_GC_GUARD(info_obj);

    return self;
}

#x_resolution ⇒ Float

Get the horizontal resolution of the image.

Returns:

• (Float) —

  the resolution

# File 'ext/RMagick/rmimage.cpp', line 16054

VALUE
Image_x_resolution(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, x_resolution, dbl, &rm_image_data_type);
}

#x_resolution=(val) ⇒ Numeric

Set the horizontal resolution of the image.

Parameters:

• val (Numeric) —

  the resolution

Returns:

• (Numeric) —

  the given resolution

# File 'ext/RMagick/rmimage.cpp', line 16066

VALUE
Image_x_resolution_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, x_resolution, dbl, &rm_image_data_type);
}

#y_resolution ⇒ Float

Get the vertical resolution of the image.

Returns:

• (Float) —

  the resolution

# File 'ext/RMagick/rmimage.cpp', line 16077

VALUE
Image_y_resolution(VALUE self)
{
    IMPLEMENT_TYPED_ATTR_READER(Image, y_resolution, dbl, &rm_image_data_type);
}

#y_resolution=(val) ⇒ Numeric

Set the vertical resolution of the image.

Parameters:

• val (Numeric) —

  the resolution

Returns:

• (Numeric) —

  the given resolution

# File 'ext/RMagick/rmimage.cpp', line 16089

VALUE
Image_y_resolution_eq(VALUE self, VALUE val)
{
    IMPLEMENT_TYPED_ATTR_WRITER(Image, y_resolution, dbl, &rm_image_data_type);
}