raster_cube

Create a data cube from an image collection

Description

Create a proxy data cube, which loads data from a given image collection according to a data cube view

Usage

raster_cube(
  image_collection,
  view,
  mask = NULL,
  chunking = .pkgenv$default_chunksize,
  incomplete_ok = TRUE
)

Arguments

Argument Description
image_collection Source image collection as from image_collection or create_image_collection
view A data cube view defining the shape (spatiotemporal extent, resolution, and spatial reference), if missing, a default overview is used
mask mask pixels of images based on band values, see image_mask
chunking length-3 vector or a function returning a vector of length 3, defining the size of data cube chunks in the order time, y, x.
incomplete_ok logical, if TRUE (the default), chunks will ignore IO failures and simply use as much images as possible, otherwise the result will contain empty chunks if IO errors or similar occur.

Details

The following steps will be performed when the data cube is requested to read data of a chunk:

  1. Find images from the input collection that intersect with the spatiotemporal extent of the chunk
  2. For all resulting images, apply gdalwarp to reproject, resize, and resample to an in-memory GDAL dataset
  3. Read the resulting data to the chunk buffer and optionally apply a mask on the result
  4. Update pixel-wise aggregator (as defined in the data cube view) to combine values of multiple images within the same data cube pixels

If chunking is provided as a function, it must accept exactly three arguments for the total size of the cube in t, y, and x axes (in this order).

Value

A proxy data cube object

Note

This function returns a proxy object, i.e., it will not start any computations besides deriving the shape of the result.

Examples

# create image collection from example Landsat data only 
# if not already done in other examples
if (!file.exists(file.path(tempdir(), "L8.db"))) {
  L8_files <- list.files(system.file("L8NY18", package = "gdalcubes"),
                         ".TIF", recursive = TRUE, full.names = TRUE)
  create_image_collection(L8_files, "L8_L1TP", file.path(tempdir(), "L8.db"), quiet = TRUE) 
}

L8.col = image_collection(file.path(tempdir(), "L8.db"))
v = cube_view(extent=list(left=388941.2, right=766552.4, 
              bottom=4345299, top=4744931, t0="2018-01", t1="2018-12"),
              srs="EPSG:32618", nx = 497, ny=526, dt="P1M")
raster_cube(L8.col, v)
A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-01-01 2018-12-31    12              P1M          1
y    4345299    4744931   526 759.756653992395        384
x   388941.2   766552.4   497 759.781086519115        384

Bands:
   name offset scale nodata unit
1   B01      0     1    NaN     
2   B02      0     1    NaN     
3   B03      0     1    NaN     
4   B04      0     1    NaN     
5   B05      0     1    NaN     
6   B06      0     1    NaN     
7   B07      0     1    NaN     
8   B08      0     1    NaN     
9   B09      0     1    NaN     
10  B10      0     1    NaN     
11  B11      0     1    NaN     
12  BQA      0     1    NaN     
 # using a mask on the Landsat quality bit band to filter out clouds
 raster_cube(L8.col, v, mask=image_mask("BQA", bits=4, values=16))
A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-01-01 2018-12-31    12              P1M          1
y    4345299    4744931   526 759.756653992395        384
x   388941.2   766552.4   497 759.781086519115        384

Bands:
   name offset scale nodata unit
1   B01      0     1    NaN     
2   B02      0     1    NaN     
3   B03      0     1    NaN     
4   B04      0     1    NaN     
5   B05      0     1    NaN     
6   B06      0     1    NaN     
7   B07      0     1    NaN     
8   B08      0     1    NaN     
9   B09      0     1    NaN     
10  B10      0     1    NaN     
11  B11      0     1    NaN     
12  BQA      0     1    NaN