Package 'rasterpic'

Title: Convert Digital Images into 'SpatRaster' Objects
Description: Generate 'SpatRaster' objects, as defined by the 'terra' package, from digital images, using a specified spatial object as a geographical reference.
Authors: Diego Hernangómez [aut, cre, cph]
Maintainer: Diego Hernangómez <[email protected]>
License: MIT + file LICENSE
Version: 0.2.5
Built: 2024-06-10 16:29:29 UTC

Help Index

Convert an image to a geo-tagged SpatRaster


Geotags an image based on the coordinates of a given spatial object.


  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  mask = FALSE,
  inverse = FALSE,
  crs = NULL



R object that may be:

  • An object created with sf of class sf, sfc, sfg or bbox).

  • An object created with terra of class SpatRaster, SpatVector or SpatExtent.

  • A numeric vector of length 4 with the extent to be used for geotagging ( i.e. c(xmin, ymin, xmax, ymax)).


An image to be geotagged. It can be a local file or an online file (e.g. ""). The following image extensions are accepted:

  • png.

  • jpeg/jpg.

  • tiff/tif.

halign, valign

Horizontal and vertical alignment of img with respect to x. It should be a value between 0 and 1:

  • ⁠halign = 0, valign = 0⁠ assumes that x should be in the bottom left corner of the SpatRaster.

  • ⁠halign = 1, valign = 1⁠ assumes that x should be in the top right corner of the SpatRaster.

  • The default ⁠halign = .5, valign = .5⁠ assumes that x is the center of img. See vignette("rasterpic", package = "rasterpic") for examples.


An expansion factor of the bounding box of x. 0 means that no expansion is added, 1 means that the bounding box is expanded to double the original size. See Details.


Logical. Should the raster be cropped to the (expanded) bounding box of x? See Details.


Logical, applicable only if x is a sf, sfc or SpatVector object. Should the raster be masked to x? See Details.


Logical. It affects only if mask = TRUE. If TRUE, areas on the raster that do not overlap with x are masked.


Character string describing a coordinate reference system. This parameter would only affect if x is a SpatExtent, sfg, bbox or a vector of coordinates. See CRS section.


vignette("rasterpic", package = "rasterpic") explains with examples the effect of parameters halign, valign, expand, crop and mask.


The function preserves the Coordinate Reference System of x if applicable. For optimal results do not use geographic coordinates (longitude/latitude).

crs can be in a WKT format, as a "authority:number" code such as "EPSG:4326", or a PROJ-string format such as "+proj=utm +zone=12". It can be also retrieved with:

See Value and Notes on terra::crs().


A SpatRaster object (see terra::rast()) where each layer corresponds to a color channel of img:

  • If img has at least 3 channels (e.g. layers), the result would have an additional property setting the layers 1 to 3 as the Red, Green and Blue channels.

  • If img already has a definition or RGB values (this may be the case for tiff/tif files) the result would keep that channel definition.

See Also

From sf:

From terra:

For plotting:



x_path <- system.file("gpkg/UK.gpkg", package = "rasterpic")
x <- st_read(x_path, quiet = TRUE)
img <- system.file("img/vertical.png", package = "rasterpic")

# Default config
ex1 <- rasterpic_img(x, img)


autoplot(ex1) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5)

# Expand
ex2 <- rasterpic_img(x, img, expand = 0.5)

autoplot(ex2) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5)

# Align
ex3 <- rasterpic_img(x, img, halign = 0)

autoplot(ex3) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5)
labs(title = "Align")

# Crop
ex4 <- rasterpic_img(x, img, crop = TRUE)

autoplot(ex4) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5) +
  labs(title = "Crop")

# Mask
ex5 <- rasterpic_img(x, img, mask = TRUE)

autoplot(ex5) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5) +
  labs(title = "Mask")

# Mask inverse
ex6 <- rasterpic_img(x, img, mask = TRUE, inverse = TRUE)

autoplot(ex6) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5) +
  labs(title = "Mask Inverse")

# Combine Mask inverse and crop
ex7 <- rasterpic_img(x, img, crop = TRUE, mask = TRUE, inverse = TRUE)

autoplot(ex7) +
  geom_sf(data = x, fill = NA, color = "white", linewidth = .5) +
  labs(title = "Combine")

# RGB channels ------
ex_rgb <- ex1

# Modify RGB channels
RGB(ex_rgb) <- c(2, 3, 1)


# Remove RGB channels
RGB(ex_rgb) <- NULL

# Note the difference with terra::plot