class Image < Object (attribute methods)
mixes in Comparable

Table of Contents

attribute methods

attribute methods

background_color

image.background_color -> aString
image.background_color = aString or aPixel

Description

The image's background color. By default the background color is "white".

Arguments

Either a color name or a Pixel object.

Returns

A color name.

base_columns

image.base_columns -> anInteger

Description

The number of columns in the image before any transformations. Get-only.

base_filename

image.base_filename -> aString

Description

The image's original filename before any transformations. Get-only.

base_rows

image.base_rows -> anInteger

Description

The number of rows in the image before any transformations. Get-only.

bias

image.bias -> bias
image.bias = aFloat
image.bias = aString

Description

Add bias when convolving an image

Argument

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

black_point_compensation

image.black_point_compensation -> true or false
image.black_point_compensation = true or false -> self

Description

Use black point compensation. Typically used in CMYK-to-RGB conversion along with image.rendering_intent=Magick::RelativeIntent

blur

image.blur -> aFloat
image.blur = aFloat

Description

The blur factor to use when resizing. See resize.

Argument

> 1.0 is blurry, < 1.0 is sharp.

border_color

image.border_color -> aString
image.border_color = aString or aPixel

Description

The image's border color. The default border color is "#dfdfdf" (gray).

Arguments

Either a color name or a Pixel object.

Returns

A color name.

bounding_box

bounding_box -> aRectangle

Description

The image's bounding box. The bounding box is the rectangle that encloses all the pixels not in the border color. Uses the current fuzz value. Get-only.

Returns

A Rectangle object.

Example

In this example, the bounding box is the gray square enclosing the blue circle. (The coordinates and red circles were added after the bounding box was computed.)

ex/bounding_box.rb

chromaticity

image.chromaticity -> aChromaticity
image.chromaticity = aChromaticity

Description

The red, green, blue, and white-point chromaticity values..

Arguments

A Chromaticity object.

Returns

A Chromaticity object.

class_type

image.class_type -> aClassType
image.class_type = aClassType

Description

The image's storage class. 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.

Arguments

A ClassType constant.

Returns

A ClassType constant.

color_profile

image.color_profile -> aString
image.color_profile = aString

Description

The ICC color profile.

Arguments

A color profile is represented as a string. If the argument is nil instead of aString then any ICC color profile present in the image is deleted.

The setter form of this attribute deletes any existing ICC color profile(s) before adding the new one. If you need to add both source and destination profiles use add_profile or profile!.

Returns

The current color profile, or nil if there is no profile.

See also

add_profile, delete_profile, each_profile, profile!

colors

image.colors -> anInteger

Description

The number of colors in the colormap. Only meaningful for PseudoClass images. Get-only.

colorspace

image.colorspace -> aColorspace
image.colorspace = aColorspace

Description

Image pixel interpretation. If the colorspace is RGBColorspace the pixels are red, green, blue. If matte is true, then red, green, blue, and opacity. If it is CMYKColorspace, the pixels are cyan, yellow, magenta, black. Otherwise the colorspace is ignored.

Arguments

A Colorspace constant.

Returns

A Colorspace constant.

columns

image.columns -> anInteger

Description

The width of the image in pixels. Get-only.

compose

image.compose -> aCompositeOperator
image.compose = aCompositeOperator

Description

The image composite operator. The default is OverCompositeOp. See montage.

Arguments

A composite operator constant.

Returns

A composite operator constant.

compression

image.compression -> aCompressionType
image.compression = aCompressionType

Description

The image compression type. The default is the compression type of the specified image file.

Arguments

A CompressionType constant.

Returns

A CompressionType constant.

delay

image.delay -> anInteger
image.delay = anInteger

Description

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.

Arguments

An integer value between 0 and 65535, inclusive.

Returns

The current delay value.

density

image.density -> aString
image.density = aString or aGeometry

Description

The vertical and horizontal resolution in pixels of the image. The default is "72x72".

Arguments

The density may be expressed either as a string or a Geometry object. If a string, it is in the form "XxY", or simply "X". If "Y" is omitted it is set to "X". To specify the density with a Geometry object, set the width attribute to the x resolution and the height argument to the y resolution. If height is nil, width will be used as the y resolution as well.

Returns

The image density represented as a string.

See also

Also see x_resolution and y_resolution.

depth

image.depth -> anInteger

Description

The image depth (8, 16, or 32). Get-only.

directory

image.directory -> aString

Description

Tile names from within an image montage. Only valid after calling montage or reading a MIFF file which contains a directory. Get-only.

Returns

A newline ("\n")-delimited list of the images in the montage.

dispose

image.dispose -> anInteger
image.dispose = aDisposeType

Description

GIF disposal method. This attribute is used to control how successive images are rendered (how the preceding image is disposed of) when creating a GIF animation.

Arguments

An integer corresponding to the disposal method.

Returns

A DisposeType constant.

endian

image.endian -> anEndianType
image.endian = anEndianType

Description

Get or set the endian attribute. (As best I can tell, only the TIFF format supports this attribute.)

Arguments

An EndianType value.

Returns

An EndianType value.

extract_info

image.extract_info -> aRectangle
image.extract_info = aRectangle

Description

Specify a rectangle within an image, or retrieve the rectangle specified when the image was constituted. See extract=.

Arguments

A Rectangle object.

Returns

A Rectangle object.

filename

image.filename -> aString

Description

The image filename. Get-only.

filesize

image.filesize -> anInteger

Description

The image filesize in bytes. Get-only.

filter

image.filter -> aFilterType
image.filter = aFilterType

Description

Filter to use when resizing image. The reduction filter employed has a significant effect on the time required to resize an image and the resulting quality. The default filter is Lanczos which has been shown to produce high quality results when reducing most images.

Arguments

A FilterType constant.

Returns

A FilterType constant.

format

image.format -> aString
image.format = aString

Description

The image encoding format. For example, "GIF" or "PNG". See formats.

Arguments

The format name.

Returns

The format name.

fuzz

image.fuzz -> aFloat
image.fuzz = aNumeric or aString

Description

Colors within this distance are considered equal. A 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.

See opaque, texture_floodfill, and transparent.

Arguments

The argument may be a floating-point numeric value or a string in the form "NN%". In the second case, the argument is computed as a percentage of MaxRGB. For example, a value of '5%' sets fuzz to 0.05*MaxRGB.

Returns

A Float

gamma

image.gamma -> aFloat
image.gamma = aFloat

Description

Gamma level of the image. The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference.

geometry

image.geometry -> aString
image.geometry = aString or aGeometry

Description

Preferred size of the image when encoding.

Arguments

A geometry string or a Geometry object.

Returns

A geometry string.

image_type

image.image_type -> anImageType

Description

The image type classification. For example, GrayscaleType. Don't confuse this attribute with the format, that is "GIF" or "JPG".

Returns

An ImageType value.

interlace

image.interlace -> anInterlaceType
image.interlace = anInterlaceType

Description

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). Use LineInterlace or PlaneInterlace to create an interlaced GIF or progressive JPEG image.

Arguments

An InterlaceType constant.

Returns

An InterlaceType constant.

iptc_profile

image.iptc_profile -> aString
image.iptc_profile = aString

Description

The International Press Telecommunications Council profile.

Arguments

A IPTC profile is represented as a string. If the argument is nil instead of aString then any IPTC profile present in the image is deleted.

Returns

The current IPTC profile, or nil if there is no profile.

See also

add_profile, delete_profile, each_profile. profile!

mask

image.mask -> anImage or nil
image.mask = anImage or anImageList or nil

Description

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

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

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

The mask attribute reader returns a copy of the clip mask. This is not a copy of the mask image that was used to create the clip mask, nor is it the clip mask image itself. Therefore, modifying the image returned by mask does not change the clip mask itself. To change the clip mask you must assign a new image to the mask= attribute writer.

Arguments

If the value is an imagelist, uses the current image as the mask image. Assign nil to remove the clip mask.

Example

mask example

matte

image.matte -> true or false
image.matte = true or false

Description

If true, honor the opacity values in the image pixels. See Pixel.

mean_error_per_pixel

image.mean_error_per_pixel -> aFloat

Description

The mean error per pixel computed when a image is color reduced. This attribute is only valid if the measure_error argument to quantize[ImageList][Image] is set to true. Get-only.

mime_type

image.mime_type -> aString

Description

Returns the officially registered (or de facto) MIME media-type. If there is no registered media-type, returns "image/x-magick". Get-only.

monitor

image.monitor = aProc

Description

Establish a progress monitor. Most Image and ImageList methods will periodically call the monitor with arguments indicating the progress of the method. The argument is a Proc object that accepts the three arguments listed here:

method_name
The name of the monitored method.
quantum
A number between 0 and span that identifies how much of the operation has been completed (or, in some cases, remains to be completed).
span
The number of quanta needed to complete the operation.

If the monitor proc returns nil or false the operation will be immediately terminated. To stop monitoring, set monitor to nil. Available in ImageMagick 6.1.0 and later, this attribute supercedes Magick.set_monitor. Set-only.

Argument

Any object that can respond to

    obj.call(method_name, quantum, span)

With very large images it is possible, though not very likely, for the quantum and span arguments to be Bignum objects.

Example

img.monitor = Proc.new do |method, offset, span|
    printf("%s is %3.0f%% complete.\n", method, (offset.to_f/span)*100)
    true
    end

img.blur_image(0,20)

produces:

blur_image is   0% complete.
blur_image is   0% complete.
blur_image is   0% complete.
blur_image is   1% complete.
blur_image is   2% complete.
blur_image is   4% complete.
blur_image is   7% complete.
blur_image is  14% complete.
blur_image is  28% complete.
blur_image is  56% complete.
blur_image is  56% complete.
blur_image is  56% complete.
blur_image is  56% complete.
blur_image is  57% complete.
blur_image is  59% complete.
blur_image is  63% complete.
blur_image is  70% complete.
blur_image is  84% complete.
blur_image is 100% complete.

See also

Image::Info#monitor=

montage

image.montage -> aString
image.montage = nil

Description

Tile size and offset within an image montage. Only valid for [images produced by montage.] The string is in the form of a geometry string.

Arguments

To release the montage string, set this attribute to nil.

normalized_mean_error

image.normalized_mean_error -> aFloat

Description

The normalized mean error computed when an image is color reduced. This attribute is only valid if the measure_error argument to quantize[ImageList][Image] is set to true. Get-only.

normalized_maximum_error

image.normalized_maximum_error -> aFloat

Description

The normalized mean error per pixel computed when an image is color reduced. This attribute is only valid if the measure_error argument to quantize[ImageList][Image] is set to true. Get-only.

number_colors

image.number_colors -> anInteger

Description

Number of unique colors in the image. Get-only.

offset

image.offset -> anInteger
image.offset = anInteger

Description

Number of initial bytes to skip over when reading raw image.

opacity

image.opacity = anInteger

Description

Attenuates the opacity channel of an image. If the image pixels are opaque, they are set to the specified opacity level. Otherwise, the pixel opacity values are blended with the supplied transparency value. Set-only.

Arguments

A number between 0 and MaxRGB. Higher numbers increase transparency.

orientation

image.orientation -> anOrientationType
image.orientation = anOrientationType

Description

The value of the Exif Orientation Tag.

Returns

An OrientationType value.

Magick API

Available in ImageMagick 6.0.0.

Notes

See http://jpegclub.org/exif_orientation.html for more information about the Exif Orientation Tag.

page

image.page -> aRectangle
image.page = aRectangle

Description

When compositing, this attribute describes the position of this image with respect to the underlying image. See coalesce, flatten_images, and mosaic.

Arguments

A Rectangle object.

Returns

A Rectangle object.

pixel_interpolation_method

image.pixel_interpolation_method -> anInterpolatePixelMethod
image.pixel_interpolation_method = anInterpolatePixelMethod

Description

Get/set the pixel color interpolation method. Some methods (such as wave, swirl, implode, and composite) use the pixel color interpolation method to determine how to blend adjacent pixels.

Argument

An InterpolatePixelMethod enum value.

Returns

An InterpolatePixelMethod enum value.

quality

image.quality -> aFixnum

Description

For JPEG images, returns the Independent JPEG Group quality value. This number is a measurement of the amount of compression used when the image was saved. Lower numbers mean higher compression.

Returns

A number between 0-100.

Notes

For more information, see The JPEG image compression FAQ.

quantum_depth

image.quantum_depth -> anInteger

Description

The image depth to the nearest Quantum (8, 16, or 32). Get-only. Available in ImageMagick 6.0.0.

rendering_intent

image.rendering_intent -> aRenderingIntent
image.rendering_intent = aRenderingIntent

Description

The type of rendering intent. See http://www.cambridgeincolour.com/tutorials/color-space-conversion.htm

Arguments

A RenderingIntent constant.

Returns

A RenderingIntent constant.

rows

image.rows -> anInteger

Description

The height of the image in pixels. Get-only.

scene

image.scene -> anInteger

Description

The scene number assigned to the image the last time the image was written to a multi-image image file. Don't confuse this attribute with ImageList's scene attribute, which denotes the image to which Image methods will be sent.

start_loop

image.start_loop -> true or false
image.start_loop = true or false

Description

Indicates the first image in an animation.

ticks_per_second

image.ticks_per_second -> aNumeric
iamge.ticks_per_second = aNumeric

Description

Gets/sets 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

The current number of ticks per second

Notes

Available in ImageMagick 6.2.4 and later. Prior to this release the number of ticks per second was fixed at 100. The GIF image format only accepts 100 ticks per second regardless of the value of this attribute.

total_colors

image.total_colors -> anInteger

Description

The number of colors in the image after quantization. Set by quantize [ImageList][Image] if the measure_error argument is true. Get-only.

units

image.units -> aResolutionType
image.units = aResolutionType

Description

Units of image resolution.

Arguments

A ResolutionType constant.

Returns

A ResolutionType constant.

See also

x_resolution, y_resolution

virtual_pixel_method

image.virtual_pixel_method -> aVirtualPixelMethod
image.virtual_pixel_method = aVirtualPixelMethod

Description

Specify how "virtual pixels" behave. Virtual pixels are pixels that are outside the boundaries of the image. Methods such as blur_image, sharpen, and wave use virtual pixels.

Arguments

The virtual pixel method can be any one of the following VirtualPixelMethod constants:

EdgeVirtualPixelMethod
Extend the edge pixel toward infinity. This is the default.
MirrorVirtualPixelMethod
Mirror the image.
TileVirtualPixelMethod
Tile the image.
BackgroundVirtualPixelMethod
The area surrounding the image is the background color.
TransparentVirtualPixelMethod
The area surrounding the image is transparent blackness.

BackgroundVirtualPixelMethod and TransparentVirtualPixelMethod are available only in ImageMagick 6.2.4 and later.

Returns

A VirtualPixelMethod constant.

Example

  img.virtual_pixel_method = Magick::TransparentVirtualPixelMethod

x_resolution

image.x_resolution -> aFloat
image.x_resolution = aFloat

Description

Horizontal resolution of the image.

See also

units

y_resolution

image.y_resolution -> aFloat
image.y_resolution = aFloat

Description

Vertical resolution of the image.

See also

units