RMagick: class Image (attribute methods)

###### RMagick User's Guide and Reference

# class Image < Object (attribute methods)
mixes in Comparable

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

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

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