README.Rmd

---
output: github_document
---

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

TileManager: Tools for creating and detecting tiling schemes for geospatial datasets
---------------

**Authors:** Andrew Plowright<br/>
**License:** GPL 3

[![Build Status](https://travis-ci.org/andrew-plowright/TileManager.svg?branch=master)](https://travis-ci.org/andrew-plowright/TileManager)

```{r global_options, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/",
  fig.height = 4,
  fig.width = 6
)

knitr::opts_knit$set(
  global.par = TRUE
  )
```

```{r, echo = FALSE}
par(mar = c(3,3,1,0.1))
```

This package provides tools for working with tiled geospatial datasets.

# News

## 2024-03-08, v.1.0.0

The latest release of `TileManager` is a complete refactor of the old library, which used the obsolete `raster` and `sp` packages. The new version uses `terra` and `sf` instead. Although the structure of the `tileScheme` class remains similar, any spatial outputs from this library now use `sf` formats.

Furthermore, `tileScheme` objects are now saved to the Geopackage format instead of SHP files.


# Introduction

Use the `tileScheme` function to create a set of tiles from a Raster or Extent object.
```{r demo1}
library(TileManager)
library(terra)

# Load a test raster
chm <- rast(system.file("ex/chm.tif", package="TileManager"))

# Generate a tile scheme
ts <- tileScheme(chm, dim = c(30,30), buffer = 5)

plot(chm)
plot(ts, add = T)

```

Use the `remove_empty` argument to drop tiles with no Raster values.
```{r demo2}
ts <- tileScheme(chm, dim = c(20,20), buffer = 2.5, remove_empty = TRUE)

plot(chm)
plot(ts, add = T)

```

Other handy features:

* The `origin` argument can be used to force the tile scheme to snap to a pair of coordinates.
* The `spill` argument controls whether or not the buffers extent beyond the input's original extent.
* By default, tile dimensions are in map units. Using the `cells` argument, they can be defined by a number of Raster cells.

# Non-overlapping buffers

Non-overlapping buffers (often abbreviated to **nbuffs**) are useful for re-assembling tiled data. Essentially, they preserve buffers only where they _do not overlap onto neighboring tiles_ (i.e.: along the edge of the tile scheme). This allows you to recombine tiles without worrying about overlapping areas _and_ without losing any information along the data edges.

In the example below:

* The __solid blue__ is the tile
* The __dashed red__ is the buffer
* The __solid purple__ is the non-overlapping buffer
```{r nbuff-sample, echo = FALSE}
plot(chm, xlim = c(439871, 439960), ylim = c(5526705, 5526756), xlab = "", ylab = "", legend = FALSE)

plot(ts, add = T)
```

# Methods

Some useful methods are provided for subsetting the tile scheme, or for converting it into other formats.

Get buffers as a `sf` object:

```{r}
ts[["buffs"]]
```

Subset a specific tile by name, number or row/col:

```{r}
# By name
ts["R2C2"]

# By number
ts[7]

# By row/col
ts[2,3]
```

Subset entire rows or columns:

```{r}
# One row
ts[4,]

# Multiple columns
ts[,2:3]
```

# Saving and loading

The tile scheme can be saved as a single Geopackage. In this case, `tiles`, `buffs` and `nbuffs` will all be written to separate tables. Other metadata (such as the buffer size) are written to a `metadata` table.

```{r, eval = FALSE}
# Create tile scheme
ts <- tileScheme(chm, dim = c(30,30), buffer = 5)

# Save tile scheme
tileSave(ts, "C:/myfiles/tilescheme.gpkg")

# Load tile scheme
ts <- tileLoad("C:/myfiles/tilescheme.gpkg")
```