% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gdal_helpers.R
\name{rvector_to_MEM}
\alias{rvector_to_MEM}
\alias{vector_to_MEM}
\title{Create a GDAL in-memory dataset from R data without copying}
\usage{
rvector_to_MEM(
  data,
  xsize,
  ysize,
  nbands = 1L,
  gt = NULL,
  bbox = NULL,
  srs = NULL
)

vector_to_MEM(
  data,
  xsize,
  ysize,
  nbands = 1L,
  gt = NULL,
  bbox = NULL,
  srs = NULL
)
}
\arguments{
\item{data}{An R vector of type \code{"double"}, \code{"integer"}, \code{"raw"} or
\code{"complex"}, containing pixel values to be exposed as a GDAL in-memory
raster. The pixels must be arranged in left-to-right, top-to-bottom order
interleaved by band. \code{length(data)} must equal \code{xsize * ysize * nbands}.}

\item{xsize}{Integer value giving the number of raster columns.}

\item{ysize}{Integer value giving the number of raster rows.}

\item{nbands}{Integer value giving the number of raster bands.}

\item{gt}{A numeric vector of length six containing the affine geotransform
for the raster. Defaults to \code{c(0, 1, 0, 0, 0, 1)} if neither \code{gt} nor \code{bbox}
are given.}

\item{bbox}{A numeric vector of length four containing the raster bounding
box geospatial coordinates (\code{c(xmin, ymin, xmax, ymax)}). Ignored if \code{gt} is
given.}

\item{srs}{Optional character string containing the raster spatial reference
coordinate system as a WKT string. \code{\link[=epsg_to_wkt]{epsg_to_wkt()}} or \code{\link[=srs_to_wkt]{srs_to_wkt()}} can be
used to convert from other formats to WKT if necessary.}
}
\value{
An object of class \code{GDALRaster} providing a GDAL MEM dataset with
write access pointing to the underlying C array for \code{data}. The R object
referenced by \code{data} is protected from garbage collection during the lifetime
of the returned dataset, i.e., until its \verb{$close()} is called or the dataset
object itself is garbage collected. An error is raised if creation of the
MEM dataset fails.
}
\description{
\code{rvector_to_MEM()} creates a GDAL MEM dataset that references pixel data in
an existing R vector. It returns an object of class \code{GDALRaster} for a
writable in-memory dataset without copying the source data. The underlying
R object is protected from garbage collection until the returned dataset is
closed. GDAL MEM datasets support most kinds of auxiliary information
including metadata, coordinate systems, georeferencing, color interpretation,
nodata, color tables and all pixel data types (see Details).
}
\details{
The returned dataset is open with write access. Methods of the \code{GDALRaster}
object can be called to modify dataset and band properties, e.g., to set
nodata values, metadata items, band descriptions, color tables, etc. The
original R vector will be modified in place if the object's \verb{$write()}
method is used.

The MEM dataset will have a GDAL data type matching the type of the
input vector:
\tabular{rl}{
\strong{R vector type}  \tab  \strong{GDAL raster type}\cr
double             \tab  Float64\cr
integer            \tab  Int32\cr
raw                \tab  UInt8 (Byte in GDAL < 3.13)\cr
complex            \tab  CFloat64
}

\code{vector_to_MEM()} is an alias of \code{rvector_to_MEM()} for backward
compatibility. It is a deprecated name of the function that will be removed
in a future version. Please use \code{rvector_to_MEM()} instead.
}
\note{
MEM datasets also support \code{addBand()} from existing R data without copying
(see Examples).

The \verb{$close()} method should be called when the \code{GDALRaster} object is no
longer needed so that resources can be freed. MEM datasets cannot be
re-opened once the object's \verb{$close()} method has been called.

\code{vector_to_MEM()} is a deprecated name for the function, currently set as
an alias of \code{rvector_to_MEM()}. \emph{The \code{vector_to_MEM()} alias will be removed
in a future version}.
}
\examples{
v <- sample(0:255, 20, replace = TRUE)
(ds_mem <- rvector_to_MEM(v, xsize = 5, ysize = 4))

all((ds_mem$read(1, 0, 0, 5, 4, 5, 4) == v))

ds_mem$write(1, 0, 0, 5, 4, (v * -1))
print(v)

ds_mem$close()

# MEM also supports no-copy addBand() from R data
xsize <- 400
ysize <- 300
r <- sample(0:255, xsize * ysize, replace = TRUE) |> as.raw()
ds_mem <- rvector_to_MEM(r, xsize, ysize)
ds_mem$setRasterColorInterp(1, "Red")

g <- sample(0:255, xsize * ysize, replace = TRUE) |> as.raw()
ds_mem$addBand("Byte", g)
ds_mem$setRasterColorInterp(2, "Green")

b <- sample(0:255, xsize * ysize, replace = TRUE) |> as.raw()
ds_mem$addBand("Byte", b)
ds_mem$setRasterColorInterp(3, "Blue")

ds_mem$info()

plot_raster(ds_mem, main = "random RGB")
ds_mem$close()
}
\seealso{
\code{\link[=GDALRaster]{GDALRaster-class}}
}
