README.qmd

---
format: gfm
default-image-extension: ''
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    warning: false
    message: false
    dpi: 150
    fig.path: "man/figures/README-"
    tidy: "styler"
    dev: "ragg_png"
    out.width: "100%"
---

<!-- README.md is generated from README.qmd. Please edit that file -->

# rasterpic <a href="https://dieghernan.github.io/rasterpic/"><img src="man/figures/logo.png" alt="rasterpic website" align="right" height="139"/></a>

<!-- badges: start -->

[![CRAN
status](https://www.r-pkg.org/badges/version/rasterpic)](https://CRAN.R-project.org/package=rasterpic)
[![CRAN
results](https://badges.cranchecks.info/worst/rasterpic.svg)](https://cran.r-project.org/web/checks/check_results_rasterpic.html)
[![R-CMD-check](https://github.com/dieghernan/rasterpic/actions/workflows/check-full.yaml/badge.svg)](https://github.com/dieghernan/rasterpic/actions/workflows/check-full.yaml)
[![codecov](https://codecov.io/gh/dieghernan/rasterpic/branch/main/graph/badge.svg?token=jSZ4RIsj91)](https://app.codecov.io/gh/dieghernan/rasterpic)
[![r-universe](https://dieghernan.r-universe.dev/badges/rasterpic)](https://dieghernan.r-universe.dev/rasterpic)
[![CodeFactor](https://www.codefactor.io/repository/github/dieghernan/rasterpic/badge)](https://www.codefactor.io/repository/github/dieghernan/rasterpic)
[![DOI](https://img.shields.io/badge/DOI-10.32614/CRAN.package.rasterpic-blue)](https://doi.org/10.32614/CRAN.package.rasterpic)
[![Project Status: Inactive – The project has reached a stable, usable state but
is no longer being actively developed; support/maintenance will be provided as
time
allows.](https://www.repostatus.org/badges/latest/inactive.svg)](https://www.repostatus.org/#inactive)
[![status](https://tinyverse.netlify.app/status/rasterpic)](https://CRAN.R-project.org/package=rasterpic)

<!-- badges: end -->

**rasterpic** is a tiny package with a single goal: geotag an image and return a
**terra** `SpatRaster` object using coordinates from supported spatial input
classes (see `?terra::SpatRaster`).

::: callout-note
This package is stable and maintained on a best-effort basis. I currently
prioritize CRAN compatibility, bug fixes and regressions over new features.
:::

## Installation

::: pkgdown-release
Install **rasterpic** from
[**CRAN**](https://CRAN.R-project.org/package=rasterpic):

```{r}
#| eval: false
install.packages("rasterpic")
```
:::

::: pkgdown-devel
Check the documentation for the development version at
<https://dieghernan.github.io/rasterpic/dev/>.

You can install the development version of **rasterpic** with:

```{r}
#| eval: false
# install.packages("pak")
pak::pak("dieghernan/rasterpic")
```

Alternatively, you can install **rasterpic** using the
[r-universe](https://dieghernan.r-universe.dev/rasterpic):

```{r}
#| eval: false
# Install rasterpic in R.
install.packages(
  "rasterpic",
  repos = c(
    "https://dieghernan.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```
:::

## Example

`rasterpic_img()` can geotag an image from several 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.

This example uses an `sf` object:

```{r}
#| label: example-basic
#| fig-cap: Example using **rasterpic** with the UK flag.
library(rasterpic)
library(sf)
library(terra)

# Use the flag of the United Kingdom.
img <- system.file("img/UK_flag.png", package = "rasterpic")
uk <- read_sf(system.file("gpkg/UK.gpkg", package = "rasterpic"))

class(uk)

# Geotag the image.
uk_flag <- rasterpic_img(uk, img)

uk_flag

# Plot with ggplot2 and tidyterra.
library(tidyterra)
library(ggplot2)

autoplot(uk_flag) +
  geom_sf(data = uk, color = alpha("blue", 0.5))
```

You can also adjust the expansion, alignment, cropping and masking options:

```{r}
#| label: align-crop-mask
#| fig-cap: Example using **rasterpic** with the UK flag cropped to the shape.

# Align, crop and mask the image.
uk_flag2 <- rasterpic_img(uk, img, halign = 0.2, crop = TRUE, mask = TRUE)

autoplot(uk_flag2) +
  geom_sf(data = uk, fill = NA)
```

## Supported image formats

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

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

## Citation

```{r}
#| echo: false
#| results: asis
print(citation("rasterpic"), style = "html")
```

A BibTeX entry for LaTeX users is:

```{r}
#| echo: false
#| comment: ''
toBibtex(citation("rasterpic"))
```