Create an image collection from a set of GDAL datasets or files
Description
This function iterates over files or GDAL dataset identifiers and extracts datetime, image identifiers, and band information according to a given collection format.
character vector with paths to image files on disk or any GDAL dataset identifiers (including virtual file systems and higher level drivers or GDAL subdatasets)
format
collection format, can be either a name to use predefined formats (as output from collection_formats) or a path to a custom JSON format description file
out_file
optional name of the output SQLite database file, defaults to a temporary file
date_time
vector with date/ time for files; can be of class character, Date, or POSIXct (argument is only applicable for image collections without collection format)
band_names
character vector with band names, length must match the number of bands in provided files (argument is only applicable for image collections without collection format)
use_subdatasets
logical; use GDAL subdatasets of provided files (argument is only applicable for image collections without collection format)
unroll_archives
automatically convert .zip, .tar archives and .gz compressed files to GDAL virtual file system dataset identifiers (e.g. by prepending /vsizip/) and add contained files to the list of considered files
quiet
logical; if TRUE, do not print resulting image collection if return value is not assigned to a variable
one_band_per_file
logical; if TRUE, assume that band_names are given for all files (argument is only applicable for image collections without collection format, see Details)
Details
An image collection is a simple index (a SQLite database) containing references to existing image files / GDAL dataset identifiers.
Collections can be created in two different ways: First, if a collection format is specified (argument format), date/time, bands, and metadata are automatically extracted from provided files. This is the most general approach but requires a collection format for the specific dataset.
Second, image collections can sometimes be created without collection format by manually specifying date/time of images (argument date_time) and names of bands (argument band_names). This is possible if either each image file contains all bands of the collection or only a single band. In the former case band_names simply contains the names of the bands or can be NULL to use default names. In the latter case (image files contain a single band only), the lengths of band_names and date_time must be identical. By default, the function assumes one band per file if length(band_names) == length(files). In the unlikely situation that this is not desired, it can be explicitly set using one_band_per_file.
Value
image collection proxy object, which can be used to create a data cube using raster_cube
Examples
# 1. create image collection using a collection format L8_files <-list.files(system.file("L8NY18", package ="gdalcubes"),".TIF", recursive =TRUE, full.names =TRUE)x =create_image_collection(L8_files, "L8_L1TP")x
# create_image_collectionCreate an image collection from a set of GDAL datasets or files```{r include=FALSE}library(gdalcubes)```## DescriptionThis function iterates over files or GDAL dataset identifiers and extracts datetime, image identifiers, and band information according to a givencollection format.## Usage```rcreate_image_collection( files,format =NULL,out_file =tempfile(fileext =".sqlite"),date_time =NULL,band_names =NULL,use_subdatasets =FALSE,unroll_archives =TRUE,quiet =FALSE,one_band_per_file =NULL)```## Arguments| Argument | Description ||:------------|:----------------------------------|| files | character vector with paths to image files on disk or any GDAL dataset identifiers (including virtual file systems and higher level drivers or GDAL subdatasets) || format | collection format, can be either a name to use predefined formats (as output from [`collection_formats`](collection_formats.Rmd)) or a path to a custom JSON format description file || out_file | optional name of the output SQLite database file, defaults to a temporary file || date_time | vector with date/ time for files; can be of class character, Date, or POSIXct (argument is only applicable for image collections without collection format) || band_names | character vector with band names, length must match the number of bands in provided files (argument is only applicable for image collections without collection format) || use_subdatasets | logical; use GDAL subdatasets of provided files (argument is only applicable for image collections without collection format) || unroll_archives | automatically convert .zip, .tar archives and .gz compressed files to GDAL virtual file system dataset identifiers (e.g. by prepending /vsizip/) and add contained files to the list of considered files || quiet | logical; if TRUE, do not print resulting image collection if return value is not assigned to a variable || one_band_per_file | logical; if TRUE, assume that band_names are given for all files (argument is only applicable for image collections without collection format, see Details) |## DetailsAn image collection is a simple index (a SQLite database) containing references to existing image files / GDAL dataset identifiers.Collections can be created in two different ways: First, if a collection format is specified (argument `format`), date/time, bands, and metadata are automatically extracted from provided files. This is the most general approach but requires a collection format forthe specific dataset. Second, image collections can sometimes be created without collection format by manually specifying date/time of images (argument `date_time`) and names of bands (argument `band_names`). This is possible if either each image file contains _all_ bands of the collection or only a single band. In the former case `band_names` simply contains the names of the bands or can be NULL to use default names. In the latter case (image files contain a single band only), the lengths of `band_names` and `date_time` must be identical.By default, the function assumes one band per file if `length(band_names) == length(files)`. In the unlikely situation that this is not desired, it can be explicitly set using `one_band_per_file`.## Valueimage collection proxy object, which can be used to create a data cube using [`raster_cube`](raster_cube.Rmd)## Examples```{r}# 1. create image collection using a collection format L8_files <-list.files(system.file("L8NY18", package ="gdalcubes"),".TIF", recursive =TRUE, full.names =TRUE)x =create_image_collection(L8_files, "L8_L1TP")x # 2. create image collection without format for a single bandL8_files_B4 <-list.files(system.file("L8NY18", package ="gdalcubes"),"_B4.TIF", recursive =TRUE, full.names =TRUE)d =as.Date(substr(basename(L8_files_B4), 18, 25), "%Y%m%d")y =create_image_collection(L8_files_B4, date_time = d, band_names ="B4")y# 3. create image collection without format for all bandsd =as.Date(substr(basename(L8_files), 18, 25), "%Y%m%d")fname =basename(tools::file_path_sans_ext(L8_files))b =substr(fname, 27, nchar(fname))z =create_image_collection(L8_files, date_time = d, band_names = b)z```