Materialise a LazyRaster (or inspect its plan).

Executes the plan and returns the result in the R session, always. To stream the result to a file instead, use write_tif(); to checkpoint to local cubes and stay lazy, use materialise(). plan_only = TRUE runs the planner passes and returns the Plan without executing, for inspection.

Usage

collect(x, plan_only = FALSE, distributed = garry_daemons_set())

Arguments

x

A LazyRaster, a LazyDataset (its bands are assembled along the band axis via stack_bands() first), a named list of lazy rasters (multi-export: one plan, a named list of results), or a LazyDatasetGroups (one result per group).

plan_only

Return the Plan instead of executing?

distributed

Execute across the garry_daemons() pools? Defaults to garry_daemons_set(), so collect(x) uses the pools when they are running and runs single-threaded otherwise. Pass TRUE/FALSE to override; the distributed result is identical to the single-threaded one.

Value

With plan_only = TRUE, the Plan. Otherwise the materialised result in the R raster convention (spatial-first, layer-last): a scalar for global reductions, a [y, x] matrix for a single layer, or a (y, x, band) array for multiple bands (matching terra::as.array(); plots directly with rasterImage/ximage). A matrix/array result also carries a gis attribute in the style of gdalraster::read_ds() (type, bbox = c(xmin, ymin, xmax, ymax), dim = c(nx, ny, nbands), srs = WKT, datatype), so the array is self-describing and preview() can set real-world axes without the grid.

Examples

f <- system.file("extdata", "garry-example.tif", package = "garry")
red <- lazy_source(f, band = 1L)
nir <- lazy_source(f, band = 3L)
ndvi <- collect((nir - red) / (nir + red))
#> Error in confirm_plugin_install(platform, url): The "cpu" PJRT plugin needs to be downloaded for pjrt to work.
#> ℹ Automatic downloads are not performed in non-interactive sessions.
#> ℹ Set `PJRT_INSTALL` to "1" to allow the download, or set
#>   `PJRT_PLUGIN_PATH_CPU` to a local plugin file.
dim(ndvi)
#> Error: object 'ndvi' not found