RMagick User's Guide and Reference
ImageMagick/GraphicsMagick Conventions

Table Of Contents

Image formats and filenames

×Magick supports over 87 major image formats.

×Magick determines the format (GIF, PNG, JPEG, etc.) of an image file either from its magic number, the filename suffix (.gif, .png, .jpg) or from a prefix attached to the filename. For example, ps:mydoc indicates that mydoc is a Postscript file. The magic number takes precedence over the filename suffix and the prefix takes precedence over the magic number and the suffix in input files. The prefix takes precedence over the filename suffix in output files.

This makes it easy to convert an image file to another format. Simply write the image file using a name that has either a prefix or a suffix corresponding to the format you want.

Note: Keep in mind that files in some formats may only be read by ×Magick, not written.

Color names

Many RMagick methods expect color name arguments or return color names. A color name can be

  1. an X color name such as "red", "chocolate", or "lightslategray". (On Linux and FreeBSD, the master list is usually /usr/X11R6/lib/X11/rgb.txt.)
  2. an SVG color name (similar to the X color names), or
  3. a hex digit string in one of the following forms:
    #RGB 4 bits each
    #RRGGBB 8 bits each
    #RRRGGGBBB 12 bits each
    #RRRRGGGGBBBB 16 bits each
    #RGBA 4 bits each, plus alpha channel
    #RRGGBBAA 8 bits each, plus alpha channel
    #RRRGGGBBBAAA 12 bits each, plus alpha channel
    #RRRRGGGGBBBBAAAA 16 bits each, plus alpha channel
    rgb(r,g,b)  
    rgba(r,g,b,a)  
    The alpha channel is the opacity of the image, which can range from 0 (Magick::OpaqueOpacity) to MaxRGB (Magick::TransparentOpacity).

A Pixel object contains the numeric representation of a color. The Pixel.from_color method converts a color name to a pixel. There are two methods to convert a pixel to a color name. The Pixel#to_color method requires that you specify whether the alpha channel is used, the depth (8 or 16) and the color standard to use. The Image#to_color method uses the image's depth and matte attributes. If matte is false the opacity value is ignored.

Hint: The name of the transparent color is "transparent", or "#000000ff".

This is ×Magick's page about color names.

The geometry string

RMagick methods frequently require a geometry string argument. This string generally specifies width and height values as well as x and y offset values. The values are usually specified in pixels (but see the % flag, below).

The format of the geometry string is <width>x<height>+-<x>+-<y>{%@!<>} Any of the values may be omitted, depending on the context.

This is the ×Magick description of the geometry string:

By default, the width and height are maximum values. That is, the image is expanded or contracted to fit the width and height value while maintaining the aspect ratio of the image. Append an exclamation point to the geometry to force the image size to exactly the size you specify. For example, if you specify 640x480! the image width is set to 640 pixels and height to 480.
If only the width is specified, the width assumes the value and the height is chosen to maintain the aspect ratio of the image. Similarly, if only the height is specified (e.g., "x256"), the width is chosen to maintain the aspect ratio. To specify a percentage width or height instead, append %. The image size is multiplied by the width and height percentages to obtain the final image dimensions. To increase the size of an image, use a value greater than 100 (e.g. 125%). To decrease an image's size, use a percentage less than 100.
Use @ to specify the maximum area in pixels of an image.
Use > to change the dimensions of the image only if its width or height exceeds the geometry specification. < resizes the image only if both of its dimensions are less than the geometry specification. For example, if you specify '640x480>' and the image size is 256x256, the image size does not change. However, if the image is 512x512 or 1024x1024, it is resized to 480x480.

The x and y offsets, if present, can be preceeded with either a + or - sign. The + causes x and y to be measured from the left or top edges, respectively. Conversely, - measures from the right or bottom edges. Offsets are always measured in pixels.

Some RMagick methods interpret the geometry string values differently. Where this is the case the documentation for the method will explain the differences.

DirectClass and PseudoClass

×Magick classifies all images into two classes, PseudoClass and DirectClass.

DirectClass images are continuous-tone images stored as RGB (red, green, blue), RGBA (red, green, blue, alpha), or CMYK (cyan, yellow, magenta, black) intensity values as defined by the colorspace [attribute].
PseudoClass images are colormapped RGB images. The colormap is stored as a series of red, green, and blue pixel values, each value being a byte in size. If the image depth is 16, each colormap entry consumes two bytes with the most significant byte being first. The number of colormap entries is defined by the colors [attribute].

GIF format images are PseudoClass. JPEG format images are DirectClass. You can change the class of a image with the Image#class_type= method.

Built-in image formats

Some of the image formats that ×Magick supports are special-purpose formats that are built-in to ×Magick itself. That is, even though you can "read" images in these formats, they do not correspond to any real image files.

These are the built-in formats that I know something about. (There are more but I've never used them.) When the format is marked with an *, you must supply the desired size of the image in order to "read" it. Specify the size by assigning a string in the form "WxH" to the size attribute in the read method's additional parms block. For example, to create a image in the gradient format that is 100 pixels wide and 200 pixels high, use:

i = Image.new
i.read("gradient:red-blue") { self.size = "100x200" }

See demo.rb for more examples of reading built-in formats.

gradient*
Gradient filenames have the form "gradient:color1-color2". These images are created by gradually changing from color1 at the top edge to color2 at the bottom.

Don't confuse this image format with the GradientFill class, which is part of RMagick.

granite
A mottled gray image suitable for use as a tiled background texture. Ex: "granite:".
logo
The ×Magick logo. Ex: "logo:".
netscape
The 216-color "Web safe" cube. Ex: "netscape:".
null*
An empty image. Ex: "null:".
pattern (5.5.7)
ImageMagick 5.5.7-3 introduced the pattern: format. This format supplies a number of built-in patterns that may be referenced by specifying the pattern name. For example, pattern:checkerboard
plasma*
Creates a swirly, psychedelic image. Specify a pair of colors in the filename ("plasma:red-blue")or specify the filename "plasma:fractal" for best results.
rose
A small picture of a rose. Ex: "rose:".
xc*
Specify a color name after the xc: prefix. For example, "xc:red". This format is simply an image of the specified color.