terra (version 1.9-25)

makeTiles: Make tiles or get their extents

Description

Divide a SpatRaster into "tiles". The cells of another SpatRaster (normally with a much lower resolution) or a SpatVector with polygon geometry can be used to define the tiles. You can also provide one or two numbers to indicate the number of rows and columns per tile.

getTileExtents returns the extents of the (virtual) tiles, while makeTiles creates files for the tiles and returns their filenames.

Usage

# S4 method for SpatRaster
makeTiles(x, y, filename="tile_.tif", extend=FALSE,
		na.rm=FALSE, buffer=0, value="files", overwrite=FALSE, ...)

# S4 method for SpatRaster
getTileExtents(x, y, extend=FALSE, buffer=0, cores=1)

Value

makeTiles returns a character (filenames), SpatRaster or SpatRasterCollection value. getTileExtents returns a matrix with extents

Arguments

x

SpatRaster

y

SpatRaster or SpatVector defining the zones; or a positive integer specifying the number of rows and columns for each zone (or 2 numbers to differentiate the number of rows and columns). For getTileExtents, y may also be missing or NULL, in which case a tile size is computed automatically (see Details)

filename

character. Output filename template. Filenames will be altered by adding the tile number for each tile

extend

logical. If TRUE, the extent of y is expanded to assure that it covers all of x

na.rm

logical. If TRUE, tiles with only missing values are ignored

buffer

integer. The number of additional rows and columns added to each tile. Can be a single number, or two numbers to specify a separate number of rows and columns. This allows for creating overlapping tiles that can be used for computing spatial context dependent values with e.g. focal. The expansion is only inside x, no rows or columns outside of x are added

cores

integer (only used by getTileExtents when y is missing). The number of worker processes that will consume the tiles. Larger values lead to smaller per-worker tiles so that the concurrent peak memory stays within budget. See Details

value

character. The type of return value desired. Either "files" (for the filenames), "raster" (for a SpatRaster), or "collection" (for a SpatRasterCollection)

overwrite

logical. If TRUE, existing tiles are overwritten; otherwise they are skipped (without error or warning)

...

additional arguments for writing files as in writeRaster

Details

When y is missing in getTileExtents, the tile size is chosen so that

• tiles align to whole GDAL blocks of the source file(s) (as reported by fileBlocksize). When no source block size is reported, a default of 256 rows by 256 columns is used.

• the per-worker peak memory (cells per tile \(\times\) nlyr \(\times\) 8 bytes \(\times\) a small ncopies factor) stays within cores workers' share of terraOptions("memfrac") of free RAM (see free_RAM, terraOptions).

• there are at least a few tiles per worker, so the work load-balances.

• the result never exceeds the raster's own dimensions.

In practice this means that for a tiled GeoTIFF / COG, tiles are an integer multiple of the file block size; for an in-memory or non-tiled raster the result is roughly square.

See Also

vrt to create a SpatRaster from tiles; crop for sub-setting arbitrary parts of a SpatRaster; divide to divide a SpatRaster into parts.

Examples

r <- rast(ncols=100, nrows=100)
values(r) <- 1:ncell(r)
x <- rast(ncols=2, nrows=2)

getTileExtents(r, x)
getTileExtents(r, x, buffer=3)

# auto: tile size from GDAL block size and a per-worker memory budget
getTileExtents(r)            # cores = 1
getTileExtents(r, cores=4)   # smaller tiles, sized for 4 concurrent workers


filename <- paste0(tempfile(), "_.tif")
ff <- makeTiles(r, x, filename)
ff

vrt(ff)