19.19 Viewing Image Files

Visiting image files automatically selects Image mode. In this major mode, you can type C-c C-c (image-toggle-display) to toggle between displaying the file as an image in the Emacs buffer, and displaying its underlying text (or raw byte) representation. Additionally you can type C-c C-x (image-toggle-hex-display) to toggle between displaying the file as an image in the Emacs buffer, and displaying it in hex representation. Displaying the file as an image works only if Emacs is compiled with support for displaying such images.

If the displayed image is wider or taller than the window in which it is displayed, the usual point motion keys (C-f, C-p, and so forth) cause different parts of the image to be displayed. However, by default images are resized automatically to fit the window, so this is only necessary if you customize the default behavior by using the options image-auto-resize and image-auto-resize-on-window-resize.

To resize the image manually you can use the command image-transform-fit-to-window bound to s w that fits the image to both the window height and width. To scale the image to a percentage of its original size, use the command image-transform-set-percent bound to s p. To scale the image specifying a scale factor, use the command image-transform-set-scale bound to s s. To reset all transformations to the initial state, use image-transform-reset-to-initial bound to s 0, or image-transform-reset-to-original bound to s o.

You can press n (image-next-file) and p (image-previous-file) to visit the next image file and the previous image file in the same directory, respectively. These commands will consult the “parent” dired buffer to determine what the next/previous image file is. These commands also work when opening a file from archive files (like zip or tar files), and will then instead consult the archive mode buffer. If neither an archive nor a dired “parent” buffer can be found, a dired buffer is opened.

When looking through images, it’s sometimes convenient to be able to mark the files for later processing (for instance, if you want to select a group of images to copy somewhere else). The m (image-mode-mark-file) command will mark the current file in any Dired buffer(s) that display the current file’s directory. If no such buffer is open, the directory is opened in a new buffer. To unmark files, use the u (image-mode-mark-file) command. Finally, if you just want to copy the current buffers file name to the kill ring, you can use the w (image-mode-copy-file-name-as-kill) command.

If the image can be animated, the command RET (image-toggle-animation) starts or stops the animation. Animation plays once, unless the option image-animate-loop is non-nil. With f (image-next-frame) and b (image-previous-frame) you can step through the individual frames. Both commands accept a numeric prefix to step through several frames at once. You can go to a specific frame with F (image-goto-frame). Frames are indexed from 1. Typing a + (image-increase-speed) increases the speed of the animation, a - (image-decrease-speed) decreases it, and a r (image-reverse-speed) reverses it. The command a 0 (image-reset-speed) resets the speed to the original value.

In addition to the above key bindings, which are specific to Image mode, images shown in any Emacs buffer have special key bindings when point is at or inside the image:

i +

Increase the image size (image-increase-size) by 20%. Prefix numeric argument controls the increment; the value of n means to multiply the size by the factor of 1 + n / 10, so C-u 5 i + means to increase the size by 50%.

i -

Decrease the image size (image-increase-size) by 20%. Prefix numeric argument controls the decrement; the value of n means to multiply the size by the factor of - n / 10, so C-u 3 i - means to decrease the size by 30%.

i r

Rotate the image by 90 degrees clockwise (image-rotate). With the prefix argument, rotate by 90 degrees counter-clockwise instead. Note that this command is not available for sliced images.

i h

Flip the image horizontally (image-flip-horizontally). This presents the image as if reflected in a vertical mirror. Note that this command is not available for sliced images.

i v

Flip the image vertically (image-flip-vertically). This presents the image as if reflected in a horizontal mirror. Note that this command is not available for sliced images.

i o

Save the image to a file (image-save). This command prompts you for the name of the file to save the image.

i c

Crop the image (image-crop). This command is available only if your system has an external program installed that can be used for cropping and cutting of images; the user option image-crop-crop-command determines what program to use, and defaults to the ImageMagick’s convert program. The command displays the image with a rectangular frame superimposed on it, and lets you use the mouse to move and resize the frame. Type m to cause mouse movements to move the frame instead of resizing it; type s to move a square frame instead. When you are satisfied with the position and size of the cropping frame, type RET to actually crop the part under the frame; or type q to exit without cropping. You can then save the cropped image using i o or M-x image-save.

i x

Cut a rectangle from the image (image-cut). This works the same as image-crop (and also requires an external program, defined by the variable image-crop-cut-command, to perform the image cut), but instead of cropping the image, it removes the part inside the frame and fills that part with the color specified by image-cut-color. With prefix argument, the command prompts for the color to use.

The size and rotation commands are “repeating”, which means that you can continue adjusting the image without using the i prefix.

If Emacs was compiled with support for the ImageMagick library, it can use ImageMagick to render a wide variety of images. The variable imagemagick-enabled-types lists the image types that Emacs may render using ImageMagick; each element in the list should be an internal ImageMagick name for an image type, as a symbol or an equivalent string (e.g., BMP for .bmp images). To enable ImageMagick for all possible image types, change imagemagick-enabled-types to t. The variable imagemagick-types-inhibit lists the image types which should never be rendered using ImageMagick, regardless of the value of imagemagick-enabled-types (the default list includes types like C and HTML, which ImageMagick can render as an image but Emacs should not). To disable ImageMagick entirely, change imagemagick-types-inhibit to t.

If Emacs doesn’t have native support for the image format in question, and image-use-external-converter is non-nil, Emacs will try to determine whether there are external utilities that can be used to transform the image in question to PNG before displaying. GraphicsMagick, ImageMagick and ffmpeg are currently supported for image conversions.

In addition, you may wish to add special handlers for certain image formats. These can be added with the image-converter-add-handler function. For instance, to allow viewing Krita files as simple images, you could say something like:

(image-converter-add-handler
 "kra"
 (lambda (file data-p)
   (if data-p
       (error "Can't decode non-files")
     (call-process "unzip" nil t nil
                   "-qq" "-c" "-x" file "mergedimage.png"))))

The function takes two parameters, where the first is a file name suffix, and the second is a function to do the “conversion”. This function takes two parameters, where the first is the file name or a string with the data, and the second says whether the first parameter is data or not, and should output an image in image-convert-to-format format in the current buffer.

The Image-Dired package can also be used to view images as thumbnails. See Viewing Image Thumbnails in Dired.