% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tmap_save.R
\name{tmap_save}
\alias{tmap_save}
\title{Save tmap}
\usage{
tmap_save(
  tm = NULL,
  filename = NA,
  device = NULL,
  width = NA,
  height = NA,
  units = NA,
  dpi = NA,
  outer.margins = NA,
  asp = NULL,
  scale = NA,
  insets_tm = NULL,
  insets_vp = NULL,
  add.titles = TRUE,
  in.iframe = FALSE,
  selfcontained = !in.iframe,
  verbose = NULL,
  ...
)
}
\arguments{
\item{tm}{tmap object}

\item{filename}{filename including extension, and optionally the path.
The extensions pdf, eps, svg, wmf (Windows only), png, jpg, bmp, tiff, and html are supported.
If the extension is missing, the file will be saved as a static plot in \code{"plot"}
mode and as an interactive map (html) in another mode.
The default format for static plots is png, but this can be changed using
the option \code{"output.format"} in \code{\link[=tmap_options]{tmap_options()}}. If \code{NA} (the default),
the file is saved as "tmap01" in the default format, and the number incremented
if the file already exists.}

\item{device}{graphic device to use. Either a device function
(e.g., \code{\link[grDevices:png]{png}} or \code{\link[grDevices:cairo_pdf]{cairo_pdf}})
or a text indicating selected graphic device: "pdf", "eps", "svg", "wmf" (Windows only), "png", "jpg", "bmp", "tiff".
If \code{NULL}, the graphic device is guessed based on the \code{filename} argument.}

\item{height, width}{The dimensions of the plot (not applicable for html files).
Units are set with the argument \code{units}. If one of them is not specified,
this is calculated using the formula asp = width / height, where asp is the
estimated aspect ratio of the map. If both are missing, they are set such
that \code{width * height} is equal to the option \code{"output.size"} in \code{\link[=tmap_options]{tmap_options()}}.
This is by default 49, meaning that is the map is a square (so aspect ratio of 1)
both width and height are set to 7.}

\item{units}{units for width and height (\code{"in"}, \code{"cm"}, or \code{"mm"}).
By default, pixels (\code{"px"}) are used if either width or height is set to a
value greater than 50. Else, the units are inches (\code{"in"}).}

\item{dpi}{dots per inch. Only applicable for raster graphics. By default it
is set to 300, but this can be changed using the option \code{"output.dpi"} in \code{\link[=tmap_options]{tmap_options()}}.}

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

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

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

\item{insets_tm}{tmap object of an inset map, or a list of tmap objects of
multiple inset maps. The number of tmap objects should be equal to the number
of viewports specified with \code{insets_vp}.}

\item{insets_vp}{\code{\link[grid:viewport]{viewport}} of an inset map, or a list
of \code{\link[grid:viewport]{viewport}}s of multiple inset maps. The number of
viewports should be equal to the number of tmap objects specified with \code{insets_tm}.}

\item{add.titles}{add titles to leaflet object.}

\item{in.iframe}{should an interactive map be saved as an iframe?
If so, two HTML files will be saved; one small parent HTML file with the
iframe container, and one large child HTML file with the actual widget.
See \code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}} for details. By default \code{FALSE},
which means that one large HTML file is saved (see \link[htmlwidgets:saveWidget]{saveWidget()}).}

\item{selfcontained}{when an interactive map is saved, should the resources
(e.g. JavaScript libraries) be contained in the HTML file? If \code{FALSE}, they
are placed in an adjacent directory (see also \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}).
Note that the HTML file will often still be large when \code{selfcontained = FALSE},
since the map data (polygons and popups), which are also contained in the HTML file,
usually take more space then the map resources.}

\item{verbose}{Deprecated. It is now controlled by the tmap option \code{show.messages}
(see \code{\link[=tmap_options]{tmap_options()}})}

\item{...}{additional arguments passed on to the underlying output function
(see Details). For interactive (html) maps these are passed to
\code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}} or \code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}}. For static
maps they are passed to the graphic device; the most useful are:
\describe{
\item{\code{colormodel} (pdf, eps)}{Color model of the output. The default is
\code{"srgb"}; use \code{colormodel = "cmyk"} for print workflows that require
CMYK. See \code{\link[grDevices:pdf]{grDevices::pdf()}}.}
\item{\code{compression} (tiff)}{Compression method, e.g. \code{"lzw"}, \code{"zip"}, or
\code{"jpeg"}. The default \code{"none"} can produce very large files; the
lossless \code{"lzw"} or \code{"zip"} is usually a good choice for publication.}
\item{\code{quality} (jpg)}{JPEG quality, from \code{0} to \code{100} (default \code{75}).}
\item{\code{bg} (all)}{Background color. Use \code{bg = "transparent"} for a
transparent background (png, tiff, and svg support transparency; jpg and
bmp do not).}
\item{\code{pointsize} (all)}{Default point size of text, which scales the text
drawn by the device.}
\item{\code{family} (pdf, eps, svg), \code{fonts} (pdf, eps)}{Font family, and fonts
to embed in the file.}
\item{\code{antialias} (png, jpg, bmp, tiff)}{Type of anti-aliasing, e.g.
\code{"default"}, \code{"none"}, \code{"gray"}, or \code{"subpixel"}. This only applies to
cairo-type devices. \code{png} always uses cairo (\code{type = "cairo-png"}), but
\code{jpg}, \code{bmp}, and \code{tiff} use the platform default device type, so on a
build without cairo support \code{antialias} is ignored for those formats.}
}}
}
\value{
the filename, invisibly, if export is successful.
}
\description{
Save tmap to a file. This can be either a static plot (e.g. png) or an interactive map (html).
}
\details{
Extra arguments (\code{...}) are passed on to the function that writes the
output. For interactive (html) maps this is \code{\link[htmlwidgets:saveWidget]{htmlwidgets::saveWidget()}}, or
\code{\link[widgetframe:saveWidgetframe]{widgetframe::saveWidgetframe()}} when \code{in.iframe = TRUE}. For static maps it
is the graphic device: the function supplied to \code{device}, or, when
\code{device = NULL}, the default device for the file extension:
\code{\link[grDevices:pdf]{grDevices::pdf()}} (\code{"pdf"}), \code{\link[grDevices:postscript]{grDevices::postscript()}} (\code{"eps"}),
\code{\link[grDevices:svg]{grDevices::svg()}} (\code{"svg"}), \code{\link[grDevices:png]{grDevices::png()}} (\code{"png"}),
\code{\link[grDevices:jpeg]{grDevices::jpeg()}} (\code{"jpg"}/\code{"jpeg"}), \code{\link[grDevices:bmp]{grDevices::bmp()}} (\code{"bmp"}), and
\code{\link[grDevices:tiff]{grDevices::tiff()}} (\code{"tiff"}). The most useful device arguments are listed
under \code{...}.

Note that \code{filename}, \code{width}, and \code{height} are always set by \code{tmap_save},
as are \code{res} and \code{units} for the raster formats (png, jpg, bmp, tiff); these
cannot be overridden through \code{...}. Use the \code{dpi}, \code{width}, \code{height}, and
\code{units} arguments of \code{tmap_save} instead.
}
\examples{
\dontrun{
	data(NLD_muni, NLD_prov)
	m <- tm_shape(NLD_muni) +
		     tm_fill(col="population", convert2density=TRUE,
                 style="kmeans",
                 title=expression("Population (per " * km^2 * ")")) +
		     tm_borders("black", alpha=.5) +
		 tm_shape(NLD_prov) +
		     tm_borders("grey25", lwd=2) +
		tm_style("classic") +
		tm_format("NLD", inner.margins = c(.02, .15, .06, .15)) +
	    tm_scalebar(position = c("left", "bottom")) +
	    tm_compass(position=c("right", "bottom"))

	tmap_save(m, "choropleth.png", height = 7) # height interpreted in inches
	tmap_save(m, "choropleth_icon.png", height = 100, scale = .1) # height interpreted in pixels

	data(World)
	m2 <- tm_shape(World) +
		tm_fill("well_being", id="name", title="Well-being") +
		tm_format("World")

	# save image
	tmap_save(m2, "World_map.png", width=1920, height=1080, asp=0)

	# cut left inner margin to make sure Antarctica is snapped to frame
	tmap_save(m2 + tm_layout(inner.margins = c(0, -.1, 0.05, 0.01)),
        "World_map2.png", width=1920, height=1080, asp=0)

	# save interactive plot
	tmap_save(m2, "World_map.html")
}
}
