Skip to contents

Get started

Source: vignettes/rasterpic.qmd

Getting started with rasterpic is straightforward: you need an image file (png, jpeg/jpg or tiff/tif) and an object of a supported spatial class, such as those from the sf, terra or stars packages.

Basic usage

This example geotags an image using the shape of Austria:

library(sf)
library(terra)
library(rasterpic)

# Load plotting packages.
library(tidyterra)
library(ggplot2)

# Set the spatial object and image.
x <- read_sf(system.file("gpkg/austria.gpkg", package = "rasterpic"))
img <- system.file("img/vertical.png", package = "rasterpic")

# Geotag the image.
default <- rasterpic_img(x, img)

autoplot(default) +
  geom_sf(data = x)
Map with longitude on the horizontal axis and latitude on the vertical axis. A portrait photograph of a one-way sign is centered behind the gray silhouette of Austria. The photograph extends above and below the country to preserve its proportions.
Figure 1: Image geotagged with the coordinates of Austria.

Options

rasterpic_img() provides options for expansion, alignment, cropping and masking.

Expansion

The expand argument expands the raster extent beyond the spatial object:

expand <- rasterpic_img(x, img, expand = 1)

autoplot(expand) +
  geom_sf(data = x)
Map with longitude on the horizontal axis and latitude on the vertical axis. A portrait photograph of a one-way sign is centered behind the gray silhouette of Austria. The expanded photograph extends beyond the country on all four sides.
Figure 2: Example image expansion.

Alignment

The halign and valign arguments control the alignment of the image relative to the spatial extent:

bottom <- rasterpic_img(x, img, valign = 0)

autoplot(bottom) +
  geom_sf(data = x)
Map with longitude on the horizontal axis and latitude on the vertical axis. A portrait photograph of a one-way sign sits behind the gray silhouette of Austria. The bottom edge of the photograph aligns with the southern edge of the country, leaving the extra image height above it.
Figure 3: Example image alignment.

Crop and mask

The crop, mask and inverse arguments control whether the raster is cropped to the object’s extent, masked to its shape or inversely masked:

mask <- rasterpic_img(x, img, crop = TRUE, mask = TRUE)

autoplot(mask)

maskinverse <- rasterpic_img(x, img, crop = TRUE, mask = TRUE, inverse = TRUE)

autoplot(maskinverse)
Map with longitude and latitude axes. A photograph of a one-way sign is visible only inside the silhouette of Austria, with the area outside the country left blank.
Figure 4: Example masked image.
Map with longitude and latitude axes. A photograph of a one-way sign fills the rectangular extent around Austria, while the country silhouette is blank. The inverse mask retains the image outside the country.
Figure 5: Example inversely masked image.

Supported spatial input classes

rasterpic_img() supports the following spatial input classes:

  • sf classes: sf, sfc, sfg and bbox.
  • terra classes: SpatRaster, SpatVector and SpatExtent.
  • stars class: stars.
  • A numeric coordinate vector of the form c(xmin, ymin, xmax, ymax).

rasterpic_img() is an S3 generic. Methods for extent-like inputs use the object’s extent, and vector methods can also mask the image to its shape.

Supported image formats

rasterpic can read the following image formats:

  • PNG files (png).
  • JPEG files (jpeg/jpg).
  • TIFF files (tiff/tif).