4  Save maps

Maps created programmatically can serve several purposes, from exploratory, through visualizations of the processing steps, to being the final outputs of a given project. Therefore, often we want just to see our map on the screen, but sometimes we also want to save our map results to an external file. tmap objects can be directly saved to output files with tmap_save()1. The tmap_save() function allows to save our map in three groups of file formats: (a) raster graphics (Section 4.1), (b) vector graphics (Section 4.2), and (c) interactive ones (Section 4.3).

For the examples in this section, we use a simple map of the Slovenia polygon with the country name superimposed , stored in the tm object (Figure 4.1).

library(tmap)
library(sf)
slo_borders = read_sf("data/slovenia/slo_border.gpkg")
tm = tm_shape(slo_borders) +
    tm_polygons() +
    tm_text("Name", fontface = "italic")
tm
Figure 4.1: A simple map of Slovenia with the country name superimposed.

4.1 Raster graphic formats

Raster graphics are non-spatial relatives of spatial rasters. The digital images are composed of many pixels – squares filled with specific colors. Main raster graphic file formats include PNG, JPEG, and TIFF. PNG and JPEG are the most common formats used for saving maps, with PNG being lossless and JPEG lossy2. The TIFF format is lossless, storing images without quality degradation, but often resulting in large file sizes. PNG is generally preferred for screen and websites, while TIFF is suggested for high-resolution printing.

One of the major parameters of the raster graphic images is DPI (Dots Per Inch, in this context, a more proper name probably should be PPI, Pixels Per Inch) – is a number of pixels per inch of the output image. For example, if the width and height of our image are 10 inches, then DPI of 300 would mean that our final image would have 3000 by 3000 pixels, and DPI of 72 would result in an image of 720 by 720 pixels. Therefore, an image with the same width and height but a larger value of DPI would occupy more space on the hard drive but also have better quality.

Saving tmap objects to a file can be done with the tmap_save(). It usually accepts two arguments3 – the first one, tm, is our map object, and the second one, filename, is the path to the created file.

tmap_save(tm, "my_map.png")
#> Map saved to my_map.png
#> Resolution: 2503 by 1762 pixels
#> Size: 8.34 by 5.87 inches (300 dpi)

By default, DPI is set to 300, and the image width and height is automatically adjusted based on the map aspect ratio. These parameters can be, however, changed with the dpi, width, and height arguments4.

tmap_save(tm, "my_map.png", width = 1000, height = 750, dpi = 300)
#> Map saved to /home/jn/Science/geocompx/tmap/my_map.png
#> Resolution: 1000 by 750 pixels
#> Size: 3.33 by 2.5 inches (300 dpi)

The units of width or height depend on the value you set: they are pixels ("px") when the value is greater than 50, and inches ("in") otherwise. Units can also be changed with the units argument.

The tmap_save() function also has several additional arguments, including outer.margins, scale, and asp. All of them override the arguments’ values set in tm_layout() (Chapter 12). Additionally, when set to 0, the asp argument has a side effect: it shifts the map frame to the edges of the output image.

By default, tmap uses graphic devices5 incorporated in R. However, it is also possible to use other, external devices with the device argument. For example, the ragg::agg_png device is usually faster and has better support for non-standard fonts than the regular grDevices::png.

tmap_save(tm, "my_map.png", device = ragg::agg_png)

4.2 Vector graphic formats

Vector graphics are quite distant counterparts of spatial vectors, with vector graphics consisting of sets of coordinates. Contrary to spatial vectors, however, their coordinates can be connected not only by straight lines (Section 2.2.1), but also using curves. This makes it possible to create polygons, circles, ellipses, and other shapes. They also allow text and other objects to be stored as vector graphics. Common vector graphic file formats are EPS, PDF, and SVG. EPS is an older format used for printing and publishing, while PDF is a more modern, general format that can contain vector and raster graphics, and more. SVG is a web standard for vector graphics, which can be used in web browsers and other applications. It is lightweight and allows for editing and manipulation of vector graphics.

To save a map to a vector graphic format, we still can use tmap_save() but either with a suitable file extension oor by explicitly setting the device argument (for example, device = svglite::svglite).

tmap_save(tm, "my_map.svg")
#> Map saved to /home/jn/Science/geocompx/tmap/my_map.svg
#> Size: 8.34 by 5.87 inches

Zooming in and out of vector graphics does not affect their quality. At the same time, the width, height, and scale arguments can still impact the output file. For example, a vector graphic file saved with a narrower width value has thicker lines and larger fonts than the one with a larger width value. You can check this effect by saving the tm object with width = 1 and then with width = 10.

Compared to raster graphics, vector graphics are not suitable for storing complex images or maps, and they are less supported by web browsers. They, however, also have many advantages. For example, vector graphics can also be easily edited in dedicated software (e.g., Inkscape or Adobe Illustrator), which allows for changing the style of map elements and moving them using a computer mouse outside of the R environment. This approach can be useful, for example, when you want to quickly adjust the position of map elements (e.g., labels) or collaborate with a graphic designer. Note, however, that this process is not fully reproducible.

4.3 Interactive format

tmap map objects can not only be viewed in the interactive mode (as shown in Section 3.6) but also saved as HTML files by adding the .html extension to the output file name.

tmap_save(tm, "my_map.html")
#> Interactive map saved to /home/jn/Science/geocompx/tmap/my_map.html

The tmap_save() function also has several additional arguments reserved for the interactive format, including selfcontained and in.iframe. The selfcontained argument – TRUE by default – saves our map together with additional resources (e.g., JavaScript libraries) into one HTML file. Otherwise, additional resources are saved in an adjacent directory. The in.iframe argument (FALSE by default) allows saving an interactive map as an iframe – when TRUE it creates two HTML files – a small HTML file with the iframe container and a large one with the actual map.

  1. Standard R approach of saving graphic files by opening a graphic device, e.g., png(), plotting the data, and then closing the device with dev.off() also works.↩︎

  2. Tit means that PNG preserves all the information about the image when saved, while JPEG compresses the image by removing some of the information, which may result in a loss of quality.↩︎

  3. In fact, one argument is enough – if you just provide a tmap object, then it is saved to a tmap01 file with some default format.↩︎

  4. You can even specify just one of width or height, and the value of the second one will be calculated using the formula asp = width / height.↩︎

  5. Short discussion about graphic devices can be found in section Section 12.3.2.↩︎