% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tm_layers_raster.R
\name{tm_raster}
\alias{tm_raster}
\alias{opt_tm_raster}
\title{Map layer: raster}
\usage{
tm_raster(
  col = tm_vars(),
  col.scale = tm_scale(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  col_alpha = tm_const(),
  col_alpha.scale = tm_scale(),
  col_alpha.legend = tm_legend(),
  col_alpha.chart = tm_chart_none(),
  col_alpha.free = NA,
  zindex = NA,
  group = NA,
  group.control = "check",
  blend = "over",
  options = opt_tm_raster(),
  ...
)

opt_tm_raster(interpolate = FALSE)
}
\arguments{
\item{col, col.scale, col.legend, col.chart, col.free}{Visual variable that determines the color. See details. \emph{Unit:} Color -- a color name, hex string.}

\item{col_alpha, col_alpha.scale, col_alpha.legend, col_alpha.chart, col_alpha.free}{Visual variable that determines the color transparency. See details. \emph{Unit:} Proportion -- numeric 0-1 (0 = fully transparent, 1 = fully opaque).}

\item{zindex}{Controls the stacking order of map layers. Should be set to a
value above 400. By default, layers are stacked in call order, starting
at 401. See details.}

\item{group}{Name of the group to which this layer belongs. This is only
relevant in view mode, where layer groups can be switched (see \code{group.control})}

\item{group.control}{In view mode, the group control determines how layer groups
can be switched on and off. Options: \code{"radio"} for radio buttons
(meaning only one group can be shown), \code{"check"} for check boxes
(so multiple groups can be shown), and \code{"none"} for no control
(the group cannot be (de)selected).}

\item{blend}{Compositing operator for layer blending. Default \code{"over"} applies
no blending. See the "Layer blending" section for the supported values.}

\item{options}{options passed on to the corresponding \verb{opt_<layer_function>} function}

\item{...}{to catch deprecated arguments from version < 4.0}

\item{interpolate}{Should the raster image be interpolated? Currently only applicable in view mode (passed on to \code{\link[grid:rasterGrob]{grid}})}
}
\description{
Map layer that draws rasters. Supported visual variable is: \code{col} (the  color).
}
\details{
The visual variable arguments (e.g. \code{col}) can be specified with a data
variable name (e.g., a spatial vector attribute or a raster layer of the object
specified in \code{\link[=tm_shape]{tm_shape()}}), with a visual value (for \code{col}, a color is expected), or with a geometry-derived variable (see below).
See vignette: \href{https://r-tmap.github.io/tmap/articles/basics_vv}{Visual variables}.

Multiple values can be specified: in that case facets are created.
These facets can be combined with other faceting data variables, specified with \code{\link[=tm_facets]{tm_facets()}}.
See vignette: \href{https://r-tmap.github.io/tmap/articles/basics_facets}{Facets}.
\itemize{
\item The \verb{*.scale} arguments determine the used scale to map the data values to
visual variable values. These can be specified with one of the available
\verb{tm_scale_*()} functions. The default is specified by the tmap option (\code{\link[=tm_options]{tm_options()}}) \code{scales.var}.
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_scales}{Scales}
\item The \verb{*.legend} arguments determine the used legend, specified with \code{\link[=tm_legend]{tm_legend()}}.
The default legend and its settings are determined by the tmap options (\code{\link[=tm_options]{tm_options()}}) \code{legend.} .
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_legends}{Legends}
\item The \verb{*.chart} arguments specify additional charts, specified with \code{tm_chart_}, e.g. \code{\link[=tm_chart_histogram]{tm_chart_histogram()}}.
See `rvignette: \href{https://r-tmap.github.io/tmap/articles/basics_charts}{Charts}
\item The \verb{*.free} arguments determine whether scales are applied freely across facets, or shared.
A logical value is required. They can also be specified with a vector of three
logical values; these determine whether scales are applied freely per facet dimension.
This is only useful when facets are applied (see \code{\link[=tm_facets]{tm_facets()}}).
There are maximally three facet dimensions: rows, columns, and pages. This only
applies for a facet grid (\code{\link[=tm_facets_grid]{tm_facets_grid()}}). For instance, \code{col.free = c(TRUE, FALSE, FALSE)}
means that for the visual variable \code{col}, each row of facets will have its own
scale, and therefore its own legend. For facet wraps and stacks
(\code{\link[=tm_facets_wrap]{tm_facets_wrap()}} and \code{\link[=tm_facets_stack]{tm_facets_stack()}}) there is only one facet dimension,
so the \verb{*.free} argument requires only one logical value.
}

Currently, three geometry-derived variables are implemented:
\itemize{
\item \code{"AREA"} (polygons only), which uses the feature area;
\item \code{"LENGTH"} (lines only), which uses the feature length; and
\item \code{"MAP_COLORS"}, which assigns values so that adjacent features receive
different values, making it particularly suitable for coloring
neighbouring polygons.
}

Note that geometry-derived variables do not generate a legend automatically.
If a legend is required, compute the corresponding variable explicitly,
for example with \code{\link[sf:st_area]{sf::st_area()}}, \code{\link[sf:st_length]{sf::st_length()}}, or
\code{\link[tmaptools:map_coloring]{tmaptools::map_coloring()}}, and use the resulting values instead.
\subsection{Visual variable units}{

Every visual variable maps data values to a specific output unit.
Knowing the unit matters when supplying constant values via \code{\link[=tm_const]{tm_const()}},
or output ranges via \code{values.range} / \code{values.scale} in the scale
functions.\tabular{lll}{
   Variable \tab Output unit \tab Notes \cr
   \code{fill}, \code{col}, \code{bgcol} \tab color \tab name, hex, or palette string \cr
   \code{fill_alpha}, \code{col_alpha}, \code{bgcol_alpha} \tab proportion 0-1 \tab 0 = transparent, 1 = opaque \cr
   \code{size} (symbols, bubbles, squares, dots) \tab typographic lines \tab 1 line approx. 1/6 inch; scaled by \code{values.scale} \cr
   \code{size} (circles) \tab meters \tab plain numeric or a \code{units} object \cr
   \code{size} (text, labels) \tab multiplier \tab 1 = 12 pt (plot) / 12 px (view) \cr
   \code{lwd} \tab lwd \tab base R units; 1 lwd approx. 0.75 pt at 96 dpi \cr
   \code{lty} \tab -- \tab integer 1-6 or name ("solid", "dashed", ...) \cr
   \code{shape} \tab -- \tab integer \code{pch} 1-25 or single character \cr
   \code{angle} \tab degrees \tab 0-360, clockwise from north \cr
   \code{fontface} \tab -- \tab "plain", "bold", "italic", "bold.italic" \cr
}

\subsection{Symbol size (\code{size} in \code{tm_symbols}, \code{tm_bubbles}, \code{tm_squares}, \code{tm_dots})}{

"Lines" is a typographic unit: one line is approximately 1/6 inch (the
default base line-height in R graphics). The global multiplier
\code{tmap_options(values.scale = list(size.bubbles = 1.5))} scales all symbol
sizes without changing the data mapping.
}

\subsection{Circle size (\code{size} in \code{tm_circles})}{

The value is a geographic radius in meters. A plain numeric vector is
interpreted as meters; a \code{units} object (from the \strong{units} package) is
automatically converted, so \code{units::as_units(1, "mi")} gives a 1-mile
radius. Because the radius is geographic, circles scale with zoom in
interactive (view) mode -- unlike bubble symbols which keep a fixed screen
size.
}

\subsection{Text size (\code{size} in \code{tm_text}, \code{tm_labels})}{

The value is a multiplier of the base font size. \code{size = 1} renders at
12 pt in plot mode (R's default \code{par("ps")}) and at 12 px in view
mode (\code{gp$cex * 12} px, see \code{tmapLeafletDataPlot.tm_data_text}); the two
modes are consistent by design.
}

}

\subsection{Layer blending (\code{blend})}{

Blend modes control how a layer's pixels are combined with the pixels
beneath it. For each pixel, let \eqn{S} be the source (top layer) RGB
value and \eqn{D} be the destination (bottom layer) RGB value, both
normalised to \eqn{[0, 1]}.\tabular{lll}{
   \code{blend} \tab Formula \tab Use case \cr
   \code{"over"} \tab \eqn{S \cdot \alpha + D \cdot (1 - \alpha)} \tab Standard alpha compositing (default) \cr
   \code{"multiply"} \tab \eqn{S \times D} \tab Hillshading over colour raster; both layers darken each other \cr
   \code{"screen"} \tab \eqn{1 - (1 - S)(1 - D)} \tab Inverse of multiply; brightens \cr
   \code{"overlay"} \tab multiply if \eqn{D < 0.5}, screen if \eqn{D \geq 0.5} \tab Boosts contrast; preserves midtones \cr
   \code{"darken"} \tab \eqn{\min(S, D)} \tab Keeps the darker of the two layers per channel \cr
   \code{"lighten"} \tab \eqn{\max(S, D)} \tab Keeps the lighter of the two layers per channel \cr
}


Requires R >= 4.2 and a compatible graphics device (e.g.
\code{png(type = "cairo")}, \code{svg()}). In view mode, blending is applied via
CSS \code{mix-blend-mode}. See \code{\link[grid:groupGrob]{grid::groupGrob()}} for the full list of
supported operators.
}

\subsection{zindex and pane names}{

In view mode, each layer is rendered in a Leaflet pane named \code{"tmap{zindex}"}
(e.g., \code{"tmap401"}, \code{"tmap402"}), with base tile layers placed in the
standard \code{"tile"} pane.
}
}
\examples{
\dontrun{
# load land data
data(land, World)

tm_shape(land) +
	tm_raster("cover")

tm_shape(land) +
	tm_raster("elevation", col.scale = tm_scale_continuous(values = terrain.colors(9))) +
	tm_shape(World) +
	tm_borders()
}
}
