read_ds {gdalraster}

Convenience wrapper for GDALRaster$read()

Description

read_ds() will read from a raster dataset that is already open in a GDALRaster object. By default, it attempts to read the full raster extent from all bands at full resolution. read_ds() is sometimes more convenient than GDALRaster$read(), e.g., to read specific multiple bands for display with plot_raster(), or simply for the argument defaults to read an entire raster into memory (see Note).

Usage

read_ds(
  ds,
  bands = NULL,
  xoff = 0,
  yoff = 0,
  xsize = ds$getRasterXSize(),
  ysize = ds$getRasterYSize(),
  out_xsize = xsize,
  out_ysize = ysize,
  as_list = FALSE,
  as_raw = FALSE
)

Arguments

ds

An object of class GDALRaster in open state.

bands

Integer vector of band numbers to read. By default all bands will be read.

xoff

Integer. The pixel (column) offset to the top left corner of the raster region to be read (zero to start from the left side).

yoff

Integer. The line (row) offset to the top left corner of the raster region to be read (zero to start from the top).

xsize

Integer. The width in pixels of the region to be read.

ysize

Integer. The height in pixels of the region to be read.

out_xsize

Integer. The width in pixels of the output buffer into which the desired region will be read (e.g., to read a reduced resolution overview).

out_ysize

Integer. The height in pixels of the output buffer into which the desired region will be read (e.g., to read a reduced resolution overview).

as_list

Logical. If TRUE, return output as a list of band vectors. If FALSE (the default), output is a vector of pixel data interleaved by band.

as_raw

Logical. If TRUE and the underlying data type is Byte, return output as R's raw vector type. This maps to the setting ⁠$readByteAsRaw⁠ on the GDALRaster object, which is used to temporarily update that field in this function. To control this behaviour in a persistent way on a data set see $readByteAsRaw in GDALRaster-class.

Details

NA will be returned in place of the nodata value if the raster dataset has a nodata value defined for the band. Data are read as R integer type when possible for the raster data type (Byte, Int8, Int16, UInt16, Int32), otherwise as type double (UInt32, Float32, Float64).

The output object has attribute gis, a list containing:

  $type = "raster"
  $bbox = c(xmin, ymin, xmax, ymax)
  $dim = c(xsize, ysize, nbands)
  $srs = <projection as WKT2 string>

The WKT version used for the projection string can be overridden by setting the OSR_WKT_FORMAT configuration option. See srs_to_wkt() for a list of supported values.

Value

If as_list = FALSE (the default), a numeric or complex vector containing the values that were read. It is organized in left to right, top to bottom pixel order, interleaved by band. If as_list = TRUE, a list with number of elements equal to the number of bands read. Each element contains a numeric or complex vector containing the pixel data read for the band.

Note

There is small overhead in calling read_ds() compared with calling GDALRaster$read() directly. This would only matter if calling the function repeatedly to read a raster in chunks. For the case of reading a large raster in many chunks, it will be optimal performance-wise to call GDALRaster$read() directly.

By default, this function will attempt to read the full raster into memory. It generally should not be called on large raster datasets using the default argument values. The memory size in bytes of the returned vector will be approximately (xsize * ysize * number of bands * 4) for data read as integer, and (xsize * ysize * number of bands * 8) for data read as double (plus small object overhead for the vector).

See Also

GDALRaster$read()

Examples

# read three bands from a multi-band dataset
lcp_file <- system.file("extdata/storm_lake.lcp", package="gdalraster")
ds <- new(GDALRaster, lcp_file)

# as a vector of pixel data interleaved by band
r <- read_ds(ds, bands=c(6,5,4))
typeof(r)
length(r)
object.size(r)

# as a list of band vectors
r <- read_ds(ds, bands=c(6,5,4), as_list=TRUE)
typeof(r)
length(r)
object.size(r)

# gis attribute list
attr(r, "gis")

ds$close()