---
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 easy: you need an image file (`png`,
`jpeg`/`jpg` or `tiff`/`tif`) and a spatial object from the **sf**, **terra**
or **stars** packages.

## Basic usage

This example uses the shape of Austria:

```{r}
#| label: fig-setup
#| fig-cap: Raster map 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")

# Create the raster.
default <- rasterpic_img(x, img)

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

## Options

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

### Expand

This option 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

Choose 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

Crop the raster and mask it to the object shape:

```{r}
#| label: fig-mask
#| fig-cap:
#|   - Example of masked image
#|   - Example of 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 input classes:

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

`rasterpic_img()` is an S3 generic. The 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 parse the following image formats:

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