Package {rasterpic}

Title:	Convert Digital Images to Spatially Referenced 'SpatRaster' Objects
Version:	0.5.1
Description:	Convert digital images to spatially referenced 'SpatRaster' objects, as defined by the 'terra' package, using coordinates from supported spatial input classes. Supported inputs include numeric coordinate vectors and objects from the 'sf', 'terra' and 'stars' packages. The main function is an S3 generic, allowing other packages to extend support to additional spatial classes.
License:	MIT + file LICENSE
URL:	https://dieghernan.github.io/rasterpic/, https://github.com/dieghernan/rasterpic
BugReports:	https://github.com/dieghernan/rasterpic/issues
Depends:	R (≥ 4.1.0)
Imports:	cli, png, sf (≥ 1.0.0), terra (≥ 1.8-21), tools, utils
Suggests:	ggplot2, knitr, quarto, stars, testthat (≥ 3.0.0), tidyterra
VignetteBuilder:	quarto
Config/Needs/check:	curl
Config/Needs/coverage:	curl
Config/Needs/website:	cpp11, curl, devtools, dieghernan/gitdevr, mapsf, maptiles, remotes, tmap
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
X-schema.org-keywords:	cran, jpeg, jpg, maps, png, r, r-package, r-stats, raster, rstats, sf, stars, terra, tif, tiff, cran-r
NeedsCompilation:	no
Packaged:	2026-06-23 08:34:07 UTC; diego
Author:	Diego Hernangómez [aut, cre, cph]
Maintainer:	Diego Hernangómez <diego.hernangomezherrero@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-23 10:00:02 UTC

rasterpic: Convert Digital Images to Spatially Referenced 'SpatRaster' Objects

Description

Convert digital images to spatially referenced 'SpatRaster' objects, as defined by the 'terra' package, using coordinates from supported spatial input classes. Supported inputs include numeric coordinate vectors and objects from the 'sf', 'terra' and 'stars' packages. The main function is an S3 generic, allowing other packages to extend support to additional spatial classes.

Author(s)

Maintainer: Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Authors:

• Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://dieghernan.github.io/rasterpic/

• https://github.com/dieghernan/rasterpic

• Report bugs at https://github.com/dieghernan/rasterpic/issues

Compute aspect ratio for spatial input

Description

Compute the aspect ratio as width divided by height, or columns divided by rows.

Usage

asp_ratio(x)

Arguments

Value

A numeric scalar giving the aspect ratio.

Examples

library(terra)

x <- rast(system.file("tiff/elev.tiff", package = "rasterpic"))
plot(x)
asp_ratio(x)

Geotag an image as a SpatRaster

Description

Geotag an image and return a SpatRaster based on coordinates from a supported spatial input class.

rasterpic_img() is an S3 generic. See S3 methods for supported input classes.

Usage

rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...
)

## S3 method for class 'sf'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  mask = FALSE,
  inverse = FALSE
)

## S3 method for class 'sfc'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  mask = FALSE,
  inverse = FALSE
)

## S3 method for class 'sfg'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  mask = FALSE,
  inverse = FALSE,
  crs = NULL
)

## S3 method for class 'stars'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...
)

## S3 method for class 'bbox'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  crs = NULL
)

## S3 method for class 'numeric'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  crs = NULL
)

## S3 method for class 'SpatRaster'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...
)

## S3 method for class 'SpatVector'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  mask = FALSE,
  inverse = FALSE
)

## S3 method for class 'SpatExtent'
rasterpic_img(
  x,
  img,
  halign = 0.5,
  valign = 0.5,
  expand = 0,
  crop = FALSE,
  ...,
  crs = NULL
)

Arguments

Details

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

S3 methods

rasterpic supports these 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).

Other packages can provide methods for additional spatial classes.

Methods for extent-like inputs use the object extent. Methods for vector inputs can also mask the image to the object shape.

CRS

This function preserves the CRS of x when applicable. For optimal results, do not use geographic coordinates (longitude/latitude).

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

• sf::st_crs(25830)$wkt.

• terra::crs().

• tidyterra::pull_crs().

See the Value and Notes sections in terra::crs().

Value

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

• If img has at least 3 layers, the result records layers 1 to 3 as the red, green and blue channels with names "r", "g" and "b" and alpha if applicable.

• If img already has an RGB specification (this may be the case for tif/tiff files), the result keeps that specification.

The resulting SpatRaster will have an RGB specification as explained in terra::RGB().

See Also

vignette("rasterpic", package = "rasterpic") for examples.

From sf:

• sf::st_crs().

• sf::st_bbox().

• vignette("sf1", package = "sf") to understand how sf organizes R objects.

From stars:

• stars::st_as_stars().

From terra:

• terra::vect(), terra::rast() and terra::ext().

• terra::mask().

• terra::crs().

• terra::RGB().

For plotting:

• terra::plot() and terra::plotRGB().

• tidyterra::autoplot.SpatRaster() and tidyterra::geom_spatraster_rgb() with ggplot2.

• tmap, mapsf and maptiles.

Examples

library(sf)
library(terra)
library(ggplot2)
library(tidyterra)

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

# Use the default configuration.
ex1 <- rasterpic_img(x, img)

ex1

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

# Expand the bounding box.
ex2 <- rasterpic_img(x, img, expand = 0.5)

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

# Align the image to the left edge.
ex3 <- rasterpic_img(x, img, halign = 0)

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

# Crop to the bounding box.
ex4 <- rasterpic_img(x, img, crop = TRUE)

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

# Mask to the vector shape.
ex5 <- rasterpic_img(x, img, mask = TRUE)

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

# Mask outside the vector shape.
ex6 <- rasterpic_img(x, img, mask = TRUE, inverse = TRUE)

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

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

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