XX-options.qmd

```{r}
#| echo: false
source("code/before_script.R")
```

# tmap options {#sec-options}

<!-- tmap_options -->

```{r}
#| message: false
library(tmap)
library(stars)
worldelevation = read_stars("data/worldelevation.tif")
```

## Raster resolution

<!-- 2/resolution -->
Raster data is represented by a grid of cells (@sec-raster-data-model), and the number of cells impacts the time to render a map.
Rasters with hundreds of cells will be plotted quickly, while rasters with hundreds of millions or billions of cells will take a lot of time (and RAM) to be shown.
<!-- ... some info about screen resolution -->
Therefore, the **tmap** package downsamples large rasters by default to be below 10,000,000 cells in the plot mode and 1,000,000 cells in the view mode.
<!-- c(plot = 1e7, view = 1e6) -->
This values can be adjusted with the `raster.max_cells` argument of `tmap_options()`, which expects a named vector with two elements - `plot` and `view` (@fig-rasterdown).
<!-- btw - downsampling cont vs cat -->
<!-- when and why -->

```{r}
#| label: fig-rasterdown
#| message: false
#| fig-cap: A raster map with the decreased resolution
tmap_options(raster.max_cells = c(plot = 5000, view = 2000))
tm_shape(worldelevation) +
  tm_raster("worldelevation.tif")
```

## Resetting the options

Any **tmap** options can be reset (set to default) with `tmap_options_reset()`.

```{r}
#| message: false
tmap_options_reset()
```