% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tmap_animation.R
\name{tmap_animation}
\alias{tmap_animation}
\title{Create animation}
\usage{
tmap_animation(
  tm,
  filename = NULL,
  width = NA,
  height = NA,
  dpi = NA,
  outer.margins = NA,
  asp = NULL,
  scale = NA,
  ...
)
}
\arguments{
\item{tm}{tmap or a list of tmap objects. If \code{tm} is a tmap object,
animation frames should be created using either \code{\link[=tm_animate]{tm_animate()}} or
\code{\link[=tm_animate_fast]{tm_animate_fast()}}.}

\item{filename}{filename. If omitted (default), the animation will be shown
in the viewer or browser. If specified, it should be a gif file or a video
file (i.e. mp4). The package \code{gifski} is required to create a gif animation.
The package \code{av} (which uses the \code{FFmpeg} library) is required for video formats.
The mp4 format is recommended but many other video formats are supported,
such as wmv, avi, and mkv.}

\item{width, height}{Dimensions of the animation file (in pixels).
Required when \code{tm} is a list, and recommended to specify in advance when
\code{tm} is a \code{tmap} object. If not specified in the latter case, it will be
determined by the aspect ratio of the map.}

\item{dpi}{dots per inch. By default 100, but this can be set with the option
\code{animation.dpi} in \code{\link[=tmap_options]{tmap_options()}}.}

\item{outer.margins}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the outer.margins
argument of \code{tm_layout()} (unless set to \code{NA})}

\item{asp}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) if specified, it overrides the \code{asp}
argument of \code{tm_layout()}. Tip: set to \code{0} if map frame should be placed on
the edges of the image.}

\item{scale}{(passed on to \code{\link[=tmap_save]{tmap_save()}}) overrides the scale argument of
\code{\link[=tm_layout]{tm_layout()}} (unless set to \code{NA})}

\item{...}{arguments passed on to \code{\link[av:av_encode_video]{av::av_encode_video()}}}
}
\description{
Create a gif animation or video from an animated tmap plot. First use \code{\link[=tm_animate]{tm_animate()}} or \code{\link[=tm_animate_fast]{tm_animate_fast()}} to animate the plot, and then apply \code{\link[=tmap_animation]{tmap_animation()}} to save it as a gif or video file (e.g. mp4).
}
\note{
Not only tmap plots are supported, but any series of R plots.
}
\examples{
\donttest{
	if (interactive()) {
		m1 <- tm_shape(NLD_prov) +
			tm_polygons("yellow") +
			tm_animate(frames = "name")

		tmap_animation(m1, filename = "countries.gif")

		m2 <- tm_shape(metro) +
			tm_symbols(size = paste0("pop", seq(1950, 2030, by=10)),
					   size.free = FALSE,
					   size.legend = tm_legend("Population")) +
			tm_layout(panel.labels = seq(1970, 2030, by=10)) +
			tm_animate()

		tmap_animation(m2, filename = "cities.gif")
	}
}
}
\concept{animation}
