RMagick: class Image::Info - Optional method arguments

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

# class Image::Info - Optional method arguments

## The Image::Info class

Some `Image` and `ImageList` methods, such as `read` and `write`, accept an "optional arguments" block in which you can set attributes that modify the method's output. These attributes belong to the `Image::Info` class. The `Image::Info` class exists only to accept optional arguments for those `Image` and `ImageList` methods.

This page explains the methods defined in the `Image::Info` class. Generally, each `Image` or `ImageList` method that uses the `Image::Info` class to get optional arguments will only accept some of the attributes listed on this page, that is, only those attributes that are meaningful for the particular method. Any other attributes that you set are ignored. Also, some attributes are only used by a subset of the image formats. See the ×Magick documentation for more information.

Remember, you do not ever need to create an `Image::Info` object. The object is created for you before the optional arguments block is entered and destroyed after the block is exited.

All the attributes in the `Image::Info` class are read/write. For simplicity, and because usually you only set these attributes, this page only describes the setter version of each attribute method.

## instance methods

### []=

self[format, key] = value -> self

#### Description

Define a format-specific option. An alternative to define, below. Use this method to set options for reading or writing certain image formats. ImageMagick and GraphicsMagick support different options, and the list of supported options changes from release to release. For a list of the valid image formats, keys, and values, refer to the documentation for the -define option for the specific release of the library you're using.

#### Arguments

format
  An image format name such as "ps" or "tiff".
key
  A string that identifies the option.
value
  The value of the option. Value can be any object that responds to `to_s`. Use `nil` to set the key to a null value.

#### Returns

self

#### Example

    self["tiff", "bits-per-sample"] = 2

#### Magick API

SetImageOption (ImageMagick 6.0.0), AddDefinitions (GraphicsMagick 1.1)

### []

self[format, key] -> value

#### Description

Returns the value of the specified option for the specified format.

#### Arguments

format
  An image format name such as "ps" or "tiff".
key
  A string that identifies the option.

#### Returns

The value of the option. Always a string.

#### Example

    self["tiff", "bits-per-sample"] » 2

#### Magick API

GetImageOption (ImageMagick 6.0.0), AccessDefinitions (GraphicsMagick 1.1)

### channel

self.channel([channel [, channel...]])

#### Description

Restrict the method to the specified channel(s). This attribute is set-only.

#### Argument

The arguments may be any ChannelType values.

#### Notes

If you call `channel` with no arguments, all channels are included. If you do not call `channel` at all, the channels used do not include the alpha channel.

### define

self.define(format, key[, value])

#### Description

Define a format-specific option. See []=, above.

#### Arguments

format
  An image format name such as "ps" or "tiff".
key
  A string that identifies the option.
value
  The value of the option. Value can be any object that responds to `to_s`. If omitted, the key is simply defined to an null value.

#### Returns

self

#### Example

    self.define("tiff", "bits-per-sample", 2)

#### Magick API

SetImageOption (ImageMagick 6.0.0), AddDefinitions (GraphicsMagick 1.1)

### undefine

self.undefine(format, key)

#### Description

Delete an option definition set by []= or define. This is not the same as setting the option to a null value. The `undefine` method removes the option name from the list of options for the specified format.

#### Arguments

format
  An image format name such as "ps" or "tiff".
key
  A string that identifies the option.

#### Returns

self

#### Example

    self.undefine("tiff", "bits-per-sample")

## attribute methods

### antialias

self.antialias= `true` or `false`

#### Description

Control antialiasing of rendered Postscript and Postscript or TrueType fonts. The default is `true`.

### authenticate

self.authenticate= aString

#### Description

Decrypt an image with this password.

This attribute can be used to specify the password to be used when reading an image or image sequence that is in an encrypted format, such as PDF.

### background_color

self.background_color= aString or aPixel

#### Description

Set the image background color. The default is "white".

#### Arguments

A color name or a aPixel.

### border_color

self.border_color= aString or aPixel

#### Description

Set the image border color. The default is "#dfdfdf".

#### Arguments

A color name or a aPixel.

### colorspace

self.colorspace= aColorspaceType

#### Description

Specify the image pixel interpretation.

#### Arguments

A ColorspaceType constant.

### comment

self.comment= aString

#### Description

Use this option to assign a specific comment to the image, when writing to an image format that supports comments.

#### Arguments

You can include the image filename, type, width, height, or other image attribute by embedding special format characters listed under the annotate method.

### compression

self.compression= aCompressionType

#### Description

Specify the type of compression used when writing the image. Only some image formats support compression. For those that do, only some compression types are supported. If you specify an compression type that is not supported, the default compression type (usually NoCompression) is used instead.

Some compression types support varying levels of compression. See the `quality` attribute.

The following table shows the image formats that support compression. For each format, the right-hand column shows the supported compression types. The default compression type is shown in bold.

Supported Compression Types
Format | Compression Types
--- | ---
BMP | NoCompression, RLECompression
DIB | NoCompression, RLECompression
FPX | NoCompression, JPEGCompression
GIF | LZWCompression (see Notes, below)
JNG | NoCompression, JPEGCompression
JP2 | JPEGCompression, LosslessJPEGCompression
JPG | JPEGCompression, LosslessJPEGCompression
MIFF | NoCompression, RLECompression
MNG | NoCompression, JPEGCompression
PALM | NoCompression, FaxCompression, RLECompression
PDB | NoCompression, RLECompression
PDF | NoCompression, JPEGCompression, LZWCompression, ZipCompression
PICT | NoCompression, JPEGCompression
PNG | NoCompression, ZIPCompression
PS | NoCompression, RLECompression
PS2 | RLECompression, FaxCompression, JPEGCompression, LZWCompression, NoCompression
PS3 | FaxCompression, JPEGCompression, LZWCompression, NoCompression, RLECompression, ZipCompression
TIFF | NoCompression, FaxCompression, Group4Compression, JPEGCompression, LZWCompression, RLECompression, ZipCompression

##### Notes

1. NoCompression is accepted for all image formats. Except as noted in the table, it is the default.
2. Prior to July 10, 2004, the default for GIF images was NoCompression.
3. ×Magick must be configured and built with extra support to use LZWCompression (in releases prior to July 10, 2004) and LosslessJPEGCompression.
4. This table is based on my examination of the ×Magick source code. It is not necessarily complete and it may contain mistakes. If you need an authoritative list, you should consult the ×Magick developers.

#### Arguments

A CompressionType constant.

### density

self.density= aString or aGeometry

#### Description

Specify the vertical and horizontal resolution in pixels. The default density is "72.0x72.0". This attribute can be used when writing JBIG, PCL, PS, PS2, and PS3 format images.

This attribute can also be used to specify the width and height of HISTOGRRAM format images. For HISTOGRAM, the default is 256x200.

#### Arguments

The argument can be either a string in the form "XxY" where "X" is the horizontal resolution and "Y" is the vertical resolution, or a Geometry object where `width` is the horizontal resolution and `height` is the vertical resolution.

### delay

self.delay= anInteger

#### Description

This attribute is useful for regulating the animation of image sequences. delay/100 seconds must expire before the display of the next image. The default is no delay between each showing of the image sequence. The maximum delay is 65535.

### depth

self.depth= aNumber

#### Description

Specify the image depth.

#### Arguments

Either 8, 16, or 32. You can specify 16 and 32 only when ×Magick was compiled with a QuantumDepth that allows these depth values.

Use `depth` to specify the depth of CMYK, GRAY, RGB, RGBA, MAP, and XC format images. See also `size`.

### dispose

self.dispose= aDisposeType

#### Description

The argument indicates the way in which the graphic is to be treated after being displayed.

#### Argument

A DisposeType constant.

### dither

self.dither= `true` or `false`

#### Description

This attribute can be used when writing GIF images.

Apply Floyd/Steinberg error diffusion to the image. The basic strategy of dithering is to trade intensity resolution for spatial resolution by averaging the intensities of several neighboring pixels. Images which suffer from severe contouring when reducing colors can be improved with this option.

### extract

self.extract= aString or aGeometry

#### Description

Specify a portion of an image to be extracted when the image is constituted. This attribute can be used to identify a subset of an image that is otherwise too large to keep in memory.

#### Arguments

Either a geometry string or a Geometry object. For example: `self.extract = "200x200+100+100"`.

### filename

self.filename= aString

#### Description

See capture.

### fill

self.fill= aString or aPixel

#### Description

In the `Image::Info` class, the `fill` attribute specifies the fill color to use when creating an image with the "caption:" format..

#### Arguments

A color name or a aPixel.

### font

self.font= aString

#### Description

Set the text rendering font.

### format

self.format= aString

#### Description

Set the image format, "GIF" or "JPG" for example.

#### Arguments

See File Formats.

### fuzz

self.fuzz= aNumeric or aString

#### Description

Set the level of "fuzziness" for comparing pixels. By default the pixels must be identical to be considered equal. The larger the `fuzz` value the more difference is tolerated. See Image#fuzz.

#### Arguments

The argument may be a 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.

### gravity

self.gravity= aGravityType

#### Description

The direction text gravitates to when annotating the image.

The direction you choose specifies where to position the text when annotating the image. For example, a gravity of `CenterGravity` forces the text to be centered within the image. By default, the image gravity is `NorthWestGravity`.

This attribute can be used to position the text when creating an image with the "caption:" format.

#### Arguments

A GravityType constant.

### image_type

self.image_type= anImageType

#### Description

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

#### Arguments

An ImageType constant.

### interlace

self.interlace= anInterlaceType

#### Description

[S]pecify 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. The default is NoInterlace.

#### Arguments

An InterlaceType constant.

### label

self.label= aString

#### Description

Use this option to assign a specific label to the image, when writing to an image format that supports labels, such as TIFF, PNG, MIFF, or PostScript. You can include the the image filename, type, width, height, or other image attribute by embedding special format characters. See annotate for details.

### matte_color

self.matte_color= aString or aPixel

#### Description

Set the image transparent color. The default is "#bdbdbd".

#### Arguments

A color name or a aPixel.

### monitor

self.monitor= aProc

#### Description

Set a `Proc` object as a progress monitor. This proc can be used to monitor the progress of methods that accept optional arguments such as `read` and `write`. To stop monitoring, set the monitor to `nil`. See Image#monitor for more informat about the proc. This attribute is set-only.

If you assign a monitor to an image with `self.monitor=` when the image is created, the image object inherits the monitor. Any methods applied to the new image will be monitored as well.

Available in ImageMagick 6.1.0 and later. This method supercedes the `Magick.set_monitor` method.

### monochrome

self.monochrome= `true` or `false`

#### Description

Transform the image to black and white on input. Only the EPT, PDF, and PS formats respect this attribute.

### orientation

self.orientation=anOrientationType

#### Description

Specify the orientation of the image pixels.

#### Argument

An OrientationType value.

### page

self.page= aString or aGeometry

#### Description

Set the equivalent size of the Postscript page. The default is "612x792>".

#### Arguments

A geometry string or a Geometry object.

### pointsize

self.pointsize= aNumeric

#### Description

Set the font size in points. Useful when creating "caption:" format images, for example.

### quality

self.quality= anInteger

#### Description

The compression level for JPEG, MPEG, JPEG-2000, MIFF, MNG, and PNG image format. Corresponds to ×Magick's -quality option. The default is 75. See Compressing image files.

### sampling_factor

self.sampling_factor= aString

#### Description

sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.

This attribute specifies the sampling factors to be used by the JPEG encoder for chroma downsampling. If this attribute is omitted, the JPEG library will use its own default values. When reading or writing the YUV format and when writing the M2V (MPEG-2) format, use sampling-factor="2x1" to specify the 4:2:2 downsampling method.

#### Argument

A string in the form "horizontal-factorxvertical-factor"

### server_name

self.server_name= aString

#### Description

Set the X11 display to obtain fonts from.

### size

self.size= aString or aGeometry

#### Description

Set the width and height of the image when reading a built-in image format that does not have an inherent size, or when reading an image from a multi-resolution file format such as Photo CD, JBIG, or JPEG.

Use `size` to specify the width and height of images in the CMYK, DIB, EMF, GRAY, RGB, RGBA, UYVY, YUV, or XC formats, the width and height of some builtin formats, or the subimage size of PTIF-format images.

#### Arguments

A geometry string or a Geometry object.

### texture

self.texture= image

#### Description

Set a texture to tile onto the image background. Corresponds to the -texture option to ×Magick's convert and mogrify commands. This attribute is set-only.

#### Argument

An image

### units

self.units= aResolutionType

#### Description

Specify the units of image resolution.

#### Arguments

A ResolutionType constant.

### view

self.view= aString

#### Description

FlashPix viewing parameters.