im.convert {animation}R Documentation

A wrapper for the ‘convert’ utility of ImageMagick or GraphicsMagick


The main purpose of these two functions is to create GIF animations.


im.convert(files, output = "animation.gif", convert = c("magick", "convert", 
    "gm convert"), = if (.Platform$OS.type == "windows") shell else system, 
    extra.opts = "", clean = FALSE)

gm.convert(..., convert = "gm convert")



either a character vector of file names, or a single string containing wildcards (e.g. ‘Rplot*.png’)


the file name of the output (with proper extensions, e.g. gif)


the convert command; it must be 'magick', 'convert' or 'gm convert'; and it can be pre-specified as an option in ani.options('convert'), e.g. (Windows users) ani.options(convert = 'c:/program files/imagemagick/convert.exe'), or (Mac users) ani.options(convert = '/opt/local/bin/convert'); see the Note section for more details

a function to invoke the OS command; by default system


additional options to be passed to convert (or gm convert)


logical: delete the input files or not


arguments to be passed to im.convert


The function im.convert simply wraps the arguments of the convert utility of ImageMagick to make it easier to call ImageMagick in R;

The function gm.convert is a wrapper for the command gm convert of GraphicsMagick.


The command for the conversion.

If ani.options('autobrowse') == TRUE, this function will also try to open the output automatically.


If files is a character vector, please make sure the order of filenames is correct! The first animation frame will be files[1], the second frame will be files[2], ...

Both ImageMagick and GraphicsMagick may have a limit on the number of images to be converted. It is a known issue that this function can fail with more than (approximately) 9000 images. The function saveVideo is a better alternative in such a case.

Most Windows users do not have read the boring notes below after they have installed ImageMagick or GraphicsMagick. For the rest of Windows users:

ImageMagick users

Please install ImageMagick from, and make sure the the path to convert.exe is in your 'PATH' variable, in which case the command convert can be called without the full path. Windows users are often very confused about the ImageMagick and 'PATH' setting, so I'll try to search for ImageMagick in the Registry Hive by readRegistry('SOFTWARE\ImageMagick\Current')$BinPath, thus you might not really need to modify your 'PATH' variable.

For Windows users who have installed LyX, I will also try to find the convert utility in the LyX installation directory, so they do not really have to install ImageMagick if LyX exists in their system (of course, the LyX should be installed with ImageMagick).

Once the convert utility is found, the animation option 'convert' will be set (ani.options(convert = 'path/to/convert.exe')); this can save time for searching for convert in the operating system next time.

GraphicsMagick users

During the installation of GraphicsMagick, you will be asked if you allow it to change the PATH variable; please do check the option.

A reported problem is = shell might not work under Windows but = system works fine. Try this option in case of failures.


Yihui Xie


Examples at



See Also

Other utilities: saveGIF, saveHTML, saveLatex, saveSWF, saveVideo

[Package animation version 2.5 Index]