vapour_vrt: Virtual raster

View source: R/vapour_vrt.R

vapour_vrtR Documentation

Virtual raster


Simple VRT creation of a GDAL virtual raster. The data source string is augmented by input of other optional arguments. That means it overrides their values provided by the source data, or stands in place of this information if it is missing.


  extent = NULL,
  projection = NULL,
  sds = 1L,
  bands = NULL,
  geolocation = NULL,
  relative_to_vrt = FALSE,
  nomd = FALSE,
  overview = -1L,
  options = character()



data source name, filepath, url, database connection string, or VRT text


(optional) numeric extent, xmin,xmax,ymin,ymax


(optional) character string, projection string ("auth:code", proj4, or WKT, or anything understood by PROJ, see Details)


which subdataset to select from a source with more than one


(optional) which band/s to include from the source


vector of 2 dsn to longitude, latitude geolocation array sources




default FALSE, if TRUE input strings that identify as files on the system are left as-is (by default they are made absolute at the R level)


if TRUE the Metadata tag is removed from the resulting VRT (it can be quite substantial)


pick an integer overview from the source (0L is highest resolution, default -1L does nothing)


pass in options to the VRT creation, like 'c("-expand", "rgb", "-ot", "Byte"('


Create a GDAL data source string (to be used like a filename) with various helpers. VRT stands for 'ViRTual'. A VRT string then acts as a representative of a data source for further use (to read or warp it).

An input string will be converted to a single subdataset, use 'sds' argument to select.

If 'extent', 'projection' is provided this is applied to override the source's extent and/or projection. (These might be invalid, or missing, so we facilitate correcting this).

If 'bands' is provided this is used to select a set of bands (numbered from 1), which might be repeated, or in any order and contain repetitions.

vapour_vrt() is vectorized, it will return multiple VRT strings for multiple inputs in a "length > 1" character vector. These are all independent, this is different to the function vapour_warp_raster() where multiple inputs are merged (possibly by sequential overlapping).

If geolocation is set the 'GeoTransform' element is forcibly removed from the vrt output, in order to avoid (there might be a better fix).


VRT character string (for use by GDAL-capable tools, i.e. reading raster)


For a raster, the basic essentials we can specify or modify for a source are

  1. the source, 2) the extent, 3) the projection 4) what subdataset (these are variables from NetCDF and the like that contain multiple datasets) and 5) which band/s to provided. For extent and projection we are simply providing or correcting complete information about how to interpret the georeferencing, with subdatasets and bands this is more like a query of which ones we want. If we only wanted band 5, then the output data would have one band only (and we we read it we need band = 1).

We don't provide ability override the dimension, but that is possible as well. More features may come with a 'VRTBuilder' interface.


Common inputs for projection are WKT variants, "AUTH:CODE"s e.g. "EPSG:3031", the "OGC:CRS84" for long,lat WGS84, "ESRI:code" and other authority variants, and datum names such as 'WGS84','NAD27' recognized by PROJ itself.

See the following links to GDAL and PROJ documentation:

PROJ documentation: c.proj_create_crs_to_crs

PROJ documentation: c.proj_create

GDAL documentation: SetFromUserInput


tif <- system.file("extdata", "sst.tif", package = "vapour")

vapour_vrt(tif, bands = c(1, 1))

vapour documentation built on June 22, 2024, 10:01 a.m.