create_image_collection: Create an image collection from a set of GDAL datasets or...

In gdalcubes: Earth Observation Data Cubes from Satellite Image Collections

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.

Usage

create_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

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) 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 


# 2. create image collection without format for a single band
L8_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 bands
d = 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

gdalcubes documentation built on May 29, 2024, 5:11 a.m.