---
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 (`png`,
`jpeg/jpg`, or `tif/tiff`) and a spatial object from the **sf** or **terra**
package to begin.

## Basic usage

Here we use the shape of Austria as an example:

```{r}
#| label: fig-setup
#| fig-cap: Raster map geolocated with the coordinates of Austria
library(sf)
library(terra)
library(rasterpic)

# Plot
library(tidyterra)
library(ggplot2)

# Shape 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

The function provides several options for expansion, alignment, and cropping.

### Expand

With this option, the raster extent is expanded beyond the spatial object:

```{r}
#| label: fig-expand
#| fig-cap: Example of expansion of image
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 of alignment of image
bottom <- rasterpic_img(x, img, valign = 0)

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

### Crop and mask

Crop and mask the image:

```{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 objects for geotagging

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

## Supported image formats

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

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