---
title: "Get started"
description: Introduction to the rasterpic package.
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    warning: false
    message: false
    out.width: "100%"
---

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

## Basic usage

This example geotags an image using the shape of Austria:

```{r}
#| label: fig-setup
#| fig-cap: Image geotagged with the coordinates 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)
```

## Options

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

### Expand

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

```{r}
#| label: fig-expand
#| fig-cap: Example image expansion.
expand <- rasterpic_img(x, img, expand = 1)

autoplot(expand) +
  geom_sf(data = x)
```

### Alignment

The `halign` and `valign` arguments control the alignment of the image within
the spatial extent:

```{r}
#| label: fig-bottom
#| fig-cap: Example image alignment.
bottom <- rasterpic_img(x, img, valign = 0)

autoplot(bottom) +
  geom_sf(data = x)
```

### Crop and mask

The `crop`, `mask` and `inverse` arguments control whether the raster is cropped
to the object extent and masked to the object shape:

```{r}
#| label: fig-mask
#| fig-cap:
#|   - Example masked image.
#|   - Example inverse masked image.
mask <- rasterpic_img(x, img, crop = TRUE, mask = TRUE)

autoplot(mask)

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

autoplot(maskinverse)
```

## 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 extent, and vector methods can also mask the image to the object shape.

## Supported image formats

**rasterpic** can read the following image formats:

- `png` files.
- `jpeg`/`jpg` files.
- `tiff`/`tif` files.