Package {dsn}

dsn: Data Source Name and Description Helpers for Use with 'GDAL'

Description

Simple helpers for 'GDAL' data source names ('DSN'), prefix and suffix and other handling. 'GDAL' is the Geospatial Data Abstraction Library https://gdal.org/, not used by this package directly.

Author(s)

Maintainer: Michael Sumner mdsumner@gmail.com

Authors:

• Michael Sumner mdsumner@gmail.com

Other contributors:

• Matt Dowle (original idea for C_addr, from data.table::address) [contributor]

See Also

Useful links:

• https://github.com/hypertidy/dsn

• https://hypertidy.github.io/dsn/

• Report bugs at https://github.com/hypertidy/dsn/issues

Return the type name of the GDAL data type.

Description

Return the type name of the GDAL data type.

Usage

gdal_datatypes()

datatype(x)

Arguments

Value

character string of the type name (the name of the constant in GDAL, e.g. GDT_Byte)

Examples

datatype(1)
names(gdal_datatypes())

Create a set of GCPs (ground control points) from dimension, extent

Description

Create a set of GCPs (ground control points) from dimension, extent

Usage

gcp_extent(dimension, extent = NULL)

gcp_extent_arg(gcp)

Arguments

Value

gcp_extent returns the col,row,x,y values, gcp_extent_arg returns formatted as a GDAL 'vrt://' connection string

Examples

gcp_extent(c(10, 20))
dsn <- sprintf("vrt://%s?%s", mem(volcano), gcp_extent_arg(gcp_extent(dim(volcano))))
gcp <- gcp_extent(dim(volcano), c(-180, 180, -90, 90))
gcp_extent_arg(gcp)

Generate a data source name (DSN) for the GDAL MEM driver

Description

An array in memory can be referenced by a GDAL data source. The DSN points directly at the memory of x, no copy is made.

Usage

mem(
  x,
  extent = NULL,
  projection = "",
  dimension = NULL,
  PIXELOFFSET = NULL,
  LINEOFFSET = NULL,
  BANDOFFSET = NULL
)

Arguments

Details

The DSN is only valid while x is alive and unmodified: keep a reference to x for as long as the DSN is in use, or R's garbage collector may free or reuse that memory. For the same reason x must already be a double array (storage.mode(x) <- "double" to convert beforehand); mem() will not convert it for you, because converting makes a temporary copy whose memory does not survive this function returning.

This DSN only works in the current R session, with GDAL read and query tools (terra, sf, gdalcubes, vapour, gdalraster, etc.). Since GDAL 3.10, opening a MEM:::DATAPOINTER DSN is disabled by default for security reasons: set the configuration option GDAL_MEM_ENABLE_OPEN=YES (e.g. Sys.setenv(GDAL_MEM_ENABLE_OPEN = "YES")) to allow it.

dimension defaults to dim(x); for an R matrix that is ⁠(nrow, ncol)⁠ used as ⁠(PIXELS, LINES)⁠, so GDAL scanlines run down the columns of the R matrix (memory order is preserved, orientation is transposed relative to the on-screen orientation of graphics::image()).

Value

character string, a DSN for use by GDAL

Examples

mem(volcano)

m <- matrix(c(0, 0, 0, 1), 5L, 4L)
mem(m)

Prefix handlers for GDAL data source names

Description

Add required prefixes, or remove them. The ⁠/vsiXXX/⁠ prefixes chain, exactly as GDAL's virtual filesystem chains, so they compose by nesting, e.g. vsizip(vsicurl(x)) gives "/vsizip//vsicurl/<x>".

Usage

vsicurl(x, sign = FALSE)

vsizip(x)

vsis3(x)

vsitar(x)

vsigzip(x)

driver(x, driver = "")

netcdf(x)

unprefix(x)

unvsicurl(x)

Arguments

Value

character vector

Examples

vsicurl("https://netcdf-r-us.org/f.nc")

driver("somefile.h5", "HDF5")

unvsicurl("/vsicurl/https://netcdf-r-us.org/f.nc")

unprefix("NETCDF:/u/user/somefile.nc")

## chaining virtual filesystems
vsizip(vsicurl("https://host/data.zip/inner/layer.shp"))

## MPC signing
mpc <- "https://sentinel2l2a01.blob.core.windows.net/sentinel2-l2/.../T43DFE_B04_10m.tif"
vsicurl(mpc , sign = TRUE)

Wrapping handlers for GDAL data source names

Description

Subdataset and VRT connection strings.

Usage

sds(x, varname, driver, quote = TRUE)

Arguments

Value

character string of the form "DRIVER:%s:varname"

Examples

f <- "myfile.nc"
sds(f, "variable", "NETCDF", quote = FALSE)

VRT connection

Description

Create a vrt connection from an input string and named arguments.

Usage

vrtcon(x, ...)

Arguments

Details

As of writing (GDAL 3.7.0DEV 2022-12-12) the only available named arguments are 'a_srs', 'bands', 'a_ullr' but that doesn't stop this function.

Value

character string in the form "vrt://%s?arg1&arg2"

Examples

vrtcon("myfile.nc", a_ullr = "0,90,360,-90", bands="1,2,1")