cube_view: Create or update a spatiotemporal data cube view

In gdalcubes: Earth Observation Data Cubes from Satellite Image Collections

Create or update a spatiotemporal data cube view

Description

Data cube views define the shape of a cube, i.e., the spatiotemporal extent, resolution, and spatial reference system (srs). They are used to access image collections as on-demand data cubes. The data cube will filter images based on the view's extent, read image data at the defined resolution, and warp / reproject images to the target srs automatically.

Usage

cube_view(
  view,
  extent,
  srs,
  nx,
  ny,
  nt,
  dx,
  dy,
  dt,
  aggregation,
  resampling,
  keep.asp = TRUE
)

Arguments

view	if provided, update this cube_view object instead of creating a new data cube view where fields that are already set will be overwritten
extent	spatioptemporal extent as a list e.g. from extent or an image collection object, see Details
srs	target spatial reference system as a string; can be a proj4 definition, WKT, or in the form "EPSG:XXXX"
nx	number of pixels in x-direction (longitude / easting)
ny	number of pixels in y-direction (latitude / northing)
nt	number of pixels in t-direction
dx	size of pixels in x-direction (longitude / easting)
dy	size of pixels in y-direction (latitude / northing)
dt	size of pixels in time-direction, expressed as ISO8601 period string (only 1 number and unit is allowed) such as "P16D"
aggregation	aggregation method as string, defining how to deal with pixels containing data from multiple images, can be "min", "max", "mean", "median", or "first"
resampling	resampling method used in gdalwarp when images are read, can be "near", "bilinear", "bicubic" or others as supported by gdalwarp (see https://gdal.org/programs/gdalwarp.html)
keep.asp	if TRUE, derive ny or dy automatically from nx or dx (or vice versa) based on the aspect ratio of the spatial extent

Details

The extent argument expects a simple list with elementes left, right, bottom, top, t0 (start date/time), t1 (end date/time) or an image collection object. In the latter case, the extent function is automatically called on the image collection object to get the full spatiotemporal extent of the collection. In the former case, datetimes are expressed as ISO8601 datetime strings.

The function can be used in two different ways. First, it can create data cube views from scratch by defining the extent, the spatial reference system, and for each dimension either the cell size (dx, dy, dt) or the total number of cells (nx, ny, nt). Second, the function can update an existing data cube view by overwriting specific fields. In this case, the extent or some elements of the extent may be missing.

In some cases, the extent of the view is automatically extended if the provided resolution would end within a pixel. For example, if the spatial extent covers an area of 1km x 1km and dx = dy = 300m, the extent would be enlarged to 1.2 km x 1.2km. The alignment will be reported to the user in a diagnostic message.

Value

A list with data cube view properties

Examples

 L8_files <- list.files(system.file("L8NY18", package = "gdalcubes"),
                        ".TIF", recursive = TRUE, full.names = TRUE)
 L8.col = create_image_collection(L8_files, "L8_L1TP")
 
 # 1. Create a new data cube view specification
 v = cube_view(extent=extent(L8.col,"EPSG:4326"), srs="EPSG:4326", dt="P1M", 
           nx=1000, ny=500, aggregation = "mean", resampling="bilinear")
 v

 # 2. overwrite parts of an existing data cube view
 vnew = cube_view(v, dt="P1M")

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