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 ImageMagick 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.
self[format, key] =
value -> self
self[key] =
value -> self
Define an option. An alternative to define, below. Use this method to set options for reading or writing certain image formats. 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 release of ImageMagick installed on your system.
to_s. Use
nil to set the key to a null value.The "user" option is unique to RMagick. It may be set to any
string. If this option is used when creating an image via one
of the methods listed below then the new image gets the value
assigned as a property as if img["user"] had been
used. In addition, the value is displayed in the string
returned by Image#inspect. The "user" property can
be used to help distinguish otherwise similar images when
debugging.
For example,
img = Magick::Image.new(10,10) do self['user'] = __FILE__ + ':' + __LINE__.to_s end » 10x10 DirectClass 16-bit user:test.rb:3
These methods propogate the value of the "user" option to
new image(s): Image.new, ImageList.new,
ImageList.new_image, Image.capture, Image.from_blob,
ImageList.from_blob, Image.read, ImageList.read,
Image.read_inline, and Image.ping.
self
self["tiff", "bits-per-sample"] = 2
SetImageOption
self[format, key] ->
value
self[key]
-> value
Returns the value of the specified option for the specified format.
The value of the option. Always a string.
self["tiff", "bits-per-sample"] » 2
GetImageOption
self.channel([channel [, channel...]])
Restrict the method to the specified channel(s). This attribute is set-only.
The arguments may be any ChannelType values.
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.
self.define(format, key[, value])
Define a format-specific option. See []=, above.
to_s. If
omitted, the key is simply defined to an null value.self
self.define("tiff", "bits-per-sample", 2)
SetImageOption
self.undefine(format, key)
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.
self
self.undefine("tiff", "bits-per-sample")
self.antialias= true or false
Control antialiasing of rendered
Postscript and Postscript or TrueType fonts. The default
is true.
self.attenuate= number
Lessen (or intensify) when adding noise to an image.
self.authenticate= string
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.
self.background_color= string or pixel
Set the image background color. The default is "white".
A color name or a Pixel.
self.border_color= string or pixel
Set the image border color. The default is "#dfdfdf".
A color name or a Pixel.
self.caption= string
When used with Image.read, assigns a caption to an image. The caption is an image property:
img = Magick::Image.read("xc:white") do
self.caption = "a new caption"
self.size = "20x20"
end
p img.first.properties » {"caption"=>"a new caption"}
p img.first['caption'] » "a new caption"
A string.
self.colorspace= colorspace
self.comment= string
Use this option to assign a specific comment to the image, when writing to an image format that supports comments.
You can include the image filename, type, width, height, or other image attribute by embedding special format characters listed under the annotate method.
self.compression= type
Specifies 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.
| Format | Compression Types |
|---|---|
| BMP | NoCompression, RLECompression |
| DIB | NoCompression, RLECompression |
| FPX | NoCompression, JPEGCompression |
| GIF | LZWCompression |
| JNG | NoCompression, JPEGCompression |
| JP2 | JPEGCompression, LosslessJPEGCompression |
| JPG | JPEGCompression, LosslessJPEGCompression |
| MIFF | NoCompression, RLECompression |
| MNG | NoCompression, JPEGCompression |
| PALM | NoCompression, FaxCompression, RLECompression |
| PDB | NoCompression, RLECompression |
| 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 |
self.density= string or geometry
Specifies 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 HISTOGRAM format images. For HISTOGRAM, the default is 256x200.
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.
self.delay= integer
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.
self.depth= integer
Specifies the image depth.
Either 8, 16, or 32. You can specify 16 and 32 only when ImageMagick 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.
self.dispose= type
The argument indicates the way in which the graphic is to be treated after being displayed.
A DisposeType constant.
self.dither= true or false
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.
self.endian= type
Specify the endianess of the image when reading the image file.
One of the following Magick::EndianType enum values:
self.extract= string or geometry
Specifies 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.
Either a geometry string or a Geometry object. For example:
self.extract = "200x200+100+100".
self.filename= string
See capture.
self.fill= string or pixel
Specifies the fill color to use when creating an image with the "caption:" format..
A color name or a pixel.
self.font= string
Set the text rendering font.
self.format= string
self.fuzz= number or string
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.
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 QuantumRange. For
example, a value of '5%' sets fuzz to
0.05*QuantumRange.
self.gravity= gravity
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.
A GravityType constant.
self.image_type= image_type
The image type classification. For example, GrayscaleType. Don't confuse this attribute with the format such as "GIF" or "JPG".
An ImageType constant.
self.interlace= type
[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.
An InterlaceType constant.
self.label= string
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.
self.matte_color= string or pixel
Set the image transparent color. The default is "#bdbdbd".
A color name or a pixel.
self.monitor= proc
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
information 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.
This method supercedes the Magick.set_monitor
method.
self.monochrome= true or false
Transform the image to black and white on input. Only the EPT, PDF, and PS formats respect this attribute.
self.orientation=type
self.origin=string or geometry
Set the image origin.
A geometry string of the
form +x+y (a "-" may be used instead of "+" to
indicate a negative offset) or a Geometry object.
self.page= string or geometry
Set the equivalent size of the Postscript page. The default is "612x792>".
A geometry string or a Geometry object.
self.pointsize= number
Set the font size in points. Useful when creating "caption:" format images, for example.
self.quality= integer
The compression level for JPEG, MPEG, JPEG-2000, MIFF, MNG, and PNG image format. Corresponds to ImageMagick's -quality option. The default is 75. See Compressing image files.
self.sampling_factor= string
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.
A string in the form "horizontal-factorxvertical-factor"
self.scene= number
Set the scene number of an image or the first image in a sequence.
self.server_name= string
Set the X11 display to obtain fonts from.
self.size= string or geometry
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 built in formats, or the
subimage size of PTIF-format images.
A geometry string or a Geometry object.
self.stroke= string or pixel
Specifies the stroke color to use when creating an image with the "caption:" format..
A color name or a pixel.
self.stroke_width= number
Specifies the stroke width to use when creating an image with the "caption:" format..
The stroke width.
self.texture= image
Set a texture to tile onto the image background. Corresponds to the -texture option to ImageMagick's convert and mogrify commands. This attribute is set-only.
An image
self.transparent_color= string or pixel
The transparent color. Sometimes used for saving to image formats such as GIF and PNG8 which uses this color to represent boolean transparency. This does not make a color transparent, just defines what color the transparent color will be in the color pallette of the saved image.
This attribute allows you to have both a opaque visible color as well as a transparent color of the same color value without conflict. That is you can use the same color for both the transparent and opaque color areas within an image. This in turn frees to you to select a transparenct color that is appropriate when a image is displayed by application that does not handle a transparent color index, while allowing RMagick to correctly handle images of this type.
self.tile_offset= string or geometry
Specifies the offset for tile images, relative to the background image it will be tiled on.
This attribute is useful with the "tile:" and "pattern:" image formats.
A geometry string or a Geometry object.
self.undercolor= string or pixel
Specifies the undercolor color to use when creating an image with the "caption:" format..
A color name or a pixel.
self.units= unit
self.view= string
FlashPix viewing parameters.