R: A wrapper for the 'convert' utility of ImageMagick or...

im.convert {animation}

R Documentation

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

Description

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

Usage

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

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

Arguments

`files`	either a character vector of file names, or a single string containing wildcards (e.g. ‘Rplot*.png’)
`output`	the file name of the output (with proper extensions, e.g. `gif`)
`convert`	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
`cmd.fun`	a function to invoke the OS command; by default `system`
`extra.opts`	additional options to be passed to `convert` (or `gm convert`)
`clean`	logical: delete the input `files` or not
`...`	arguments to be passed to `im.convert`

Details

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.

Value

The command for the conversion.

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

Note

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 http://www.imagemagick.org, 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 cmd.fun = shell might not work under Windows but cmd.fun = system works fine. Try this option in case of failures.

Author(s)

Yihui Xie

References

Examples at https://yihui.org/animation/example/im-convert/

ImageMagick: http://www.imagemagick.org/script/convert.php

GraphicsMagick: http://www.graphicsmagick.org