39.17.5 ImageMagick Images

If your Emacs build has ImageMagick support, you can use the ImageMagick library to load many image formats (see File Conveniences in The GNU Emacs Manual). The image type symbol for images loaded via ImageMagick is imagemagick, regardless of the actual underlying image format.

To check for ImageMagick support, use the following:

(image-type-available-p 'imagemagick)

Function: imagemagick-types

This function returns a list of image file extensions supported by the current ImageMagick installation. Each list element is a symbol representing an internal ImageMagick name for an image type, such as BMP for .bmp images.

User Option: imagemagick-enabled-types

The value of this variable is a list of ImageMagick image types which Emacs may attempt to render using ImageMagick. Each list element should be one of the symbols in the list returned by imagemagick-types, or an equivalent string. Alternatively, a value of t enables ImageMagick for all possible image types. Regardless of the value of this variable, imagemagick-types-inhibit (see below) takes precedence.

User Option: imagemagick-types-inhibit

The value of this variable lists the ImageMagick image types which should never be rendered using ImageMagick, regardless of the value of imagemagick-enabled-types. A value of t disables ImageMagick entirely.

Variable: image-format-suffixes

This variable is an alist mapping image types to file name extensions. Emacs uses this in conjunction with the :format image property (see below) to give a hint to the ImageMagick library as to the type of an image. Each element has the form (type extension), where type is a symbol specifying an image content-type, and extension is a string that specifies the associated file name extension.

Images loaded with ImageMagick support the following additional image descriptor properties:

:background background

background, if non-nil, should be a string specifying a color, which is used as the image’s background color if the image supports transparency. If the value is nil, it defaults to the frame’s background color.

:width width, :height height

The :width and :height keywords are used for scaling the image. If only one of them is specified, the other one will be calculated so as to preserve the aspect ratio. If both are specified, aspect ratio may not be preserved.

:max-width max-width, :max-height max-height

The :max-width and :max-height keywords are used for scaling if the size of the image of the image exceeds these values. If :width is set it will have precedence over max-width, and if :height is set it will have precedence over max-height, but you can otherwise mix these keywords as you wish. :max-width and :max-height will always preserve the aspect ratio.

If both :width and :max-height has been set (but :height has not been set), then :max-height will have precedence. The same is the case for the opposite combination: The “max” keyword has precedence. That is, if you have a 200x100 image and specify that :width should be 400 and :max-height should be 150, you’ll end up with an image that is 300x150: Preserving the aspect ratio and not exceeding the “max” setting. This combination of parameters is a useful way of saying “display this image as large as possible, but no larger than the available display area”.

:scale scale

This should be a number, where values higher than 1 means to increase the size, and lower means to decrease the size. For instance, a value of 0.25 will make the image a quarter size of what it originally was. If the scaling makes the image larger than specified by :max-width or :max-height, the resulting size will not exceed those two values. If both :scale and :height/:width are specified, the height/width will be adjusted by the specified scaling factor.

:format type

The value, type, should be a symbol specifying the type of the image data, as found in image-format-suffixes. This is used when the image does not have an associated file name, to provide a hint to ImageMagick to help it detect the image type.

:rotation angle

Specifies a rotation angle in degrees.

:index frame

See Multi-Frame Images.