stack_cube

Create a data cube from a set of images with the same spatial extent and spatial reference system

Description

Create a spatiotemporal data cube directly from images with identical spatial extent and spatial reference system, similar to a raster stack with an additional dimension supporting both, time and multiple bands / variables.

Usage

stack_cube(
  x,
  datetime_values,
  bands = NULL,
  band_names = NULL,
  chunking = c(1, 256, 256),
  dx = NULL,
  dy = NULL,
  incomplete_ok = TRUE
)

Arguments

Argument	Description
x	character vector where items point to image files
datetime_values	vector of type character, Date, or POSIXct with recording date of images
bands	optional character vector defining the band or spectral band of each item in x, if files relate to different spectral bands or variables
band_names	name of bands, only used if bands is NULL, i.e., if all files contain the same spectral band(s) / variable(s)
chunking	vector of length 3 defining the size of data cube chunks in the order time, y, x.
dx	optional target pixel size in x direction, by default (NULL) the original or highest resolution of images is used
dy	optional target pixel size in y direction, by default (NULL) the original or highest resolution of images is used
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

This function creates a four-dimensional (space, time, bands / variables) raster data cube from a set of provided files without the need to create an image collection before. This is possible if all images have the same spatial extent and spatial reference system and can be used for two different file organizations:

If all image files share the same bands / variables, the bands argument can be ignored (default NULL) can names of the bands can be specified using the band_names argument.
If image files represent different band / variable (e.g. individual files for red, green, and blue channels), the bands argument must be used to define the corresponding band / variable. Notice that in this case all files are expected to represent exactly one variable / band at one point in datetime. It is not possible to combine files with different numbers of variables / bands. If image files for different bands have different pixel sizes, the smallest size is used by default.

Notice that to avoid opening all image files in advance,no automatic check whether all images share the spatial extent and spatial reference system is performed.

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

# toy example, repeating the same image as a daily time series
L8_file_nir <- 
system.file("L8NY18/LC08_L1TP_014032_20181122_20181129_01_T1/LC08_L1TP_014032_20181122_B5.TIF",
            package = "gdalcubes")
files = rep(L8_file_nir, 10)
datetime = as.Date("2018-11-22") + 1:10
stack_cube(files, datetime, band_names = "B05")

A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-11-23 2018-12-02    10              P1D          1
y    4346085    4582215    78 3027.30769230769        256
x     394185     626415    77 3015.97402597403        256
                                                      values
t 2018-11-23,2018-11-24,2018-11-25,2018-11-26,2018-11-27,...
y                                                           
x                                                           

Bands:
  name offset scale nodata unit
1  B05      0     1 -1e+10

# using a second band from different files
L8_file_red <- 
system.file("L8NY18/LC08_L1TP_014032_20181122_20181129_01_T1/LC08_L1TP_014032_20181122_B4.TIF",
            package = "gdalcubes")
files = rep(c(L8_file_nir, L8_file_red), each = 10)
datetime = rep(as.Date("2018-11-22") + 1:10, 2)
bands = rep(c("B5","B4"), each = 10)
stack_cube(files, datetime, bands = bands)

A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-11-23 2018-12-02    10              P1D          1
y    4346085    4582215    78 3027.30769230769        256
x     394185     626415    77 3015.97402597403        256
                                                      values
t 2018-11-23,2018-11-24,2018-11-25,2018-11-26,2018-11-27,...
y                                                           
x                                                           

Bands:
  name offset scale nodata unit
1   B5      0     1 -1e+10     
2   B4      0     1 -1e+10

# stack_cube Create a data cube from a set of images with the same spatial extent and spatial reference system ```{r include=FALSE} library(gdalcubes) ``` ## Description Create a spatiotemporal data cube directly from images with identical spatial extent and spatial reference system, similar to a raster stack with an additional dimension supporting both, time and multiple bands / variables. ## Usage ```r stack_cube( x, datetime_values, bands = NULL, band_names = NULL, chunking = c(1, 256, 256), dx = NULL, dy = NULL, incomplete_ok = TRUE ) ``` ## Arguments | Argument | Description | |:------------|:----------------------------------| | x | character vector where items point to image files | | datetime_values | vector of type character, Date, or POSIXct with recording date of images | | bands | optional character vector defining the band or spectral band of each item in x, if files relate to different spectral bands or variables | | band_names | name of bands, only used if bands is NULL, i.e., if all files contain the same spectral band(s) / variable(s) | | chunking | vector of length 3 defining the size of data cube chunks in the order time, y, x. | | dx | optional target pixel size in x direction, by default (NULL) the original or highest resolution of images is used | | dy | optional target pixel size in y direction, by default (NULL) the original or highest resolution of images is used | | 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 This function creates a four-dimensional (space, time, bands / variables) raster data cube from a set of provided files without the need to create an image collection before. This is possible if all images have the same spatial extent and spatial reference system and can be used for two different file organizations: 1. If all image files share the same bands / variables, the `bands` argument can be ignored (default NULL) can names of the bands can be specified using the `band_names` argument. 2. If image files represent different band / variable (e.g. individual files for red, green, and blue channels), the `bands` argument must be used to define the corresponding band / variable. Notice that in this case all files are expected to represent exactly one variable / band at one point in datetime. It is not possible to combine files with different numbers of variables / bands. If image files for different bands have different pixel sizes, the smallest size is used by default. Notice that to avoid opening all image files in advance,no automatic check whether all images share the spatial extent and spatial reference system is performed. ## 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 ```{r} # toy example, repeating the same image as a daily time series L8_file_nir <- system.file("L8NY18/LC08_L1TP_014032_20181122_20181129_01_T1/LC08_L1TP_014032_20181122_B5.TIF", package = "gdalcubes") files = rep(L8_file_nir, 10) datetime = as.Date("2018-11-22") + 1:10 stack_cube(files, datetime, band_names = "B05") # using a second band from different files L8_file_red <- system.file("L8NY18/LC08_L1TP_014032_20181122_20181129_01_T1/LC08_L1TP_014032_20181122_B4.TIF", package = "gdalcubes") files = rep(c(L8_file_nir, L8_file_red), each = 10) datetime = rep(as.Date("2018-11-22") + 1:10, 2) bands = rep(c("B5","B4"), each = 10) stack_cube(files, datetime, bands = bands) ```