% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gdalraster.R
\name{GDALRaster-class}
\alias{GDALRaster-class}
\alias{Rcpp_GDALRaster}
\alias{Rcpp_GDALRaster-class}
\alias{GDALRaster}
\title{Class encapsulating a raster dataset and associated band objects}
\arguments{
\item{filename}{Character string containing the file name of a raster
dataset to open, as full path or relative to the current working directory.
In some cases, \code{filename} may not refer to a local file system, but instead
contain format-specific information on how to access a dataset such
as database connection string, URL, /vsiPREFIX/, etc. (see GDAL
raster format descriptions:
\url{https://gdal.org/en/stable/drivers/raster/index.html}).}

\item{read_only}{Logical. \code{TRUE} to open the dataset read-only (the default),
or \code{FALSE} to open with write access.}

\item{open_options}{Optional character vector of \code{NAME=VALUE} pairs
specifying dataset open options.}

\item{shared}{Logical. \code{FALSE} to open the dataset without using shared
mode. Default is \code{TRUE} (see Note).}

\item{allowed_drivers}{Optional character vector of driver short names that
must be considered. By default, all known raster drivers are considered.}
}
\value{
An object of class \code{GDALRaster}, which contains a pointer to the
opened dataset.
Class methods that operate on the dataset are described in Details, along
with a set of writable fields for per-object settings. Values may be
assigned to the class fields as needed during the lifetime of the object
(i.e., by regular \code{<-} or \code{=} assignment).
}
\description{
\code{GDALRaster} provides an interface for accessing a raster dataset via GDAL
and calling methods on the underlying \code{GDALDataset}, \code{GDALDriver} and
\code{GDALRasterBand} objects. See \url{https://gdal.org/en/stable/api/index.html}
for details of the GDAL Raster API.

\code{GDALRaster} is a C++ class exposed directly to \R (via
\code{RCPP_EXPOSED_CLASS}). Fields and methods of the class are accessed using
the \code{$} operator. \strong{Note that all arguments to class methods are required
and must be given in the order documented.} Naming the arguments is
optional but may be preferred for readability.
}
\note{
If a dataset object is opened with update access (\code{read_only = FALSE}), it
is not recommended to open a new dataset on the same underlying \code{filename}.

Datasets are opened in shared mode by default. This allows the sharing of
\code{GDALDataset} handles for a dataset with other callers that open shared on
the same \code{filename}, if the dataset is opened from the same thread.
Functions in \code{gdalraster} that do processing will open input datasets in
shared mode. This provides potential efficiency for cases when an object of
class \code{GDALRaster} is already open in read-only mode on the same \code{filename}
(avoids overhead associated with initial dataset opening by using the
existing handle, and potentially makes use of existing data in the GDAL
block cache). Opening in shared mode can be disabled by specifying the
optional \code{shared} parameter in the class constructor.

The \code{$read()} method will perform automatic resampling if the
specified output size (\code{out_xsize * out_ysize}) is different than
the size of the region being read (\code{xsize * ysize}). In that case, the
\code{GDAL_RASTERIO_RESAMPLING} configuration option could also be set to
override the default resampling to one of \code{BILINEAR}, \code{CUBIC},
\code{CUBICSPLINE}, \code{LANCZOS}, \code{AVERAGE} or \code{MODE} (see \code{\link[=set_config_option]{set_config_option()}}).
}
\section{Usage (see Details)}{


\if{html}{\out{<div class="sourceCode">}}\preformatted{## Constructors
# read-only by default:
ds <- new(GDALRaster, filename)
# for update access:
ds <- new(GDALRaster, filename, read_only = FALSE)
# to specify dataset open options:
ds <- new(GDALRaster, filename, read_only = TRUE|FALSE, open_options)
# to open without using shared mode:
new(GDALRaster, filename, read_only, open_options, shared = FALSE)
# to specify certain allowed driver(s):
new(GDALRaster, filename, read_only, open_options, shared, allowed_drivers)

## Read/write fields (per-object settings)
ds$infoOptions
ds$quiet
ds$readByteAsRaw

## Methods
ds$getFilename()
ds$setFilename(filename)
ds$open(read_only)
ds$isOpen()
ds$isReadOnly()
ds$getFileList()

ds$info()
ds$infoAsJSON()

ds$getDriverShortName()
ds$getDriverLongName()

ds$getRasterXSize()
ds$getRasterYSize()
ds$getRasterCount()

ds$addBand(dataType, options)

ds$getGeoTransform()
ds$setGeoTransform(transform)

ds$getProjection()
ds$getProjectionRef()
ds$getSpatialRef()
ds$setProjection(projection)

ds$bbox()
ds$res()
ds$dim()
ds$setBbox(bbox)

ds$apply_geotransform(col_row)
ds$get_pixel_line(xy)

ds$get_block_indexing(band)
ds$make_chunk_index(band, max_pixels)

ds$getDescription(band)
ds$setDescription(band, desc)
ds$getBlockSize(band)
ds$getActualBlockSize(band, xblockoff, yblockoff)
ds$getOverviewCount(band)
ds$buildOverviews(resampling, levels, bands)
ds$getDataTypeName(band)
ds$getNoDataValue(band)
ds$setNoDataValue(band, nodata_value)
ds$deleteNoDataValue(band)
ds$getMaskFlags(band)
ds$getMaskBand(band)
ds$getUnitType(band)
ds$setUnitType(band, unit_type)
ds$getScale(band)
ds$setScale(band, scale)
ds$getOffset(band)
ds$setOffset(band, offset)
ds$getRasterColorInterp(band)
ds$setRasterColorInterp(band, col_interp)

ds$getMinMax(band, approx_ok)
ds$getMinMaxLocation(band)
ds$getStatistics(band, approx_ok, force)
ds$clearStatistics()

ds$getHistogram(band, min, max, num_buckets, incl_out_of_range, approx_ok)
ds$getDefaultHistogram(band, force)

ds$getInterBandCovMatrix(bands, approx_ok, force, write_in_metadata,
                         df_correction)

ds$getMetadata(band, domain)
ds$setMetadata(band, metadata, domain)
ds$getMetadataItem(band, mdi_name, domain)
ds$setMetadataItem(band, mdi_name, mdi_value, domain)
ds$getMetadataDomainList(band)

ds$read(band, xoff, yoff, xsize, ysize, out_xsize, out_ysize)
ds$readBlock(band, xblockoff, yblockoff)
ds$readChunk(band, chunk_def)
ds$readToNativeRaster(xoff, yoff, xsize, ysize, out_xsize, out_ysize)

ds$write(band, xoff, yoff, xsize, ysize, rasterData)
ds$writeBlock(band, xblockoff, yblockoff, rasterData)
ds$writeChunk(band, chunk_def, rasterData)
ds$fillRaster(band, value, ivalue)

ds$getColorTable(band)
ds$getPaletteInterp(band)
ds$setColorTable(band, col_tbl, palette_interp)
ds$clearColorTable(band)

ds$getDefaultRAT(band)
ds$setDefaultRAT(band, df)

ds$flushCache()

ds$getChecksum(band, xoff, yoff, xsize, ysize)

ds$close()
}\if{html}{\out{</div>}}
}

\section{Details}{

\subsection{Constructors}{

\code{new(GDALRaster, filename, read_only)}\cr
Returns an object of class \code{GDALRaster}. The \code{read_only} argument defaults
to \code{TRUE} if not specified.

\code{new(GDALRaster, filename, read_only, open_options)}\cr
Alternate constructor for passing dataset \code{open_options}, a character
vector of \code{NAME=VALUE} pairs.
\code{read_only} is required for this form of the constructor, \code{TRUE} for
read-only access, or \code{FALSE} to open with write access.
Returns an object of class \code{GDALRaster}.

\code{new(GDALRaster, filename, read_only, open_options, shared)}\cr
Alternate constructor for specifying the \code{shared} mode for dataset opening.
The \code{shared} argument defaults to \code{TRUE} but can be set to \code{FALSE} with this
constructor (see Note).
All arguments are required with this form of the constructor, but
\code{open_options} can be \code{NULL}. Returns an object of class \code{GDALRaster}.

\code{new(GDALRaster, filename, read_only, open_options, shared, allowed_drivers)}\cr
Alternate constructor for specifying the driver(s) allowed for dataset
opening as a character vector of driver short names.
All arguments are required with this form of the constructor, but
\code{open_options} and/or \code{allowed_drivers} can be \code{NULL}. Returns an object of class
\code{GDALRaster}.
}

\subsection{Read/write fields}{

\code{$infoOptions}\cr
A character vector of command-line arguments to control the output of
\code{$info()} and \code{$infoAsJSON()} (see below).
Defaults to \code{character(0)}. Can be set to a vector of strings specifying
arguments to the \command{gdalinfo} command-line utility, e.g.,
\code{c("-nomd", "-norat", "-noct")}.
Restore the default by setting to empty string (\code{""}) or \code{character(0)}.

\code{$quiet}\cr
A logical value, \code{FALSE} by default. This field can be set to \code{TRUE} which
will suppress various messages as well as progress reporting for potentially
long-running processes such as building overviews and computation of
statistics and histograms.

\code{$readByteAsRaw}\cr
A logical value, \code{FALSE} by default. This field can be set to \code{TRUE} which
will affect the data type returned by the \code{$read()} method and the
\code{\link[=read_ds]{read_ds()}} convenience function. When the underlying band data type is
Byte/UInt8 and \code{readByteAsRaw} is \code{TRUE} the output type will be raw rather
than integer. See also the \code{as_raw} argument to \code{\link[=read_ds]{read_ds()}} to control this
in a non-persistent setting. If the underlying band data type is not
Byte/UInt8 setting has no effect. (Note Byte = UInt8 in GDAL >= 3.13.)
}

\subsection{Methods}{

\code{$getFilename()}\cr
Returns a character string containing the \code{filename} associated with this
\code{GDALRaster} object (\code{filename} originally used to open the dataset). May
be a regular filename, database connection string, URL, etc.

\code{$setFilename(filename)}\cr
Sets the \code{filename} if the underlying dataset does not already have an
associated filename. Explicitly setting the filename is an advanced
setting that should only be used when the user has determined that it is
needed. Writing certain virtual datasets to file is one potential use case
(e.g., a dataset returned by \code{autoCreateWarpedVRT()}).

\code{$open(read_only)}\cr
(Re-)opens the raster dataset on the existing filename. Use this method to
open a dataset that has been closed using \code{$close()}. May be used to
re-open a dataset with a different read/write access (\code{read_only} set to
\code{TRUE} or \code{FALSE}). The method will first close an open dataset, so it is
not required to call \code{$close()} explicitly in this case.
No return value, called for side effects.

\code{$isOpen()}\cr
Returns a logical value, \code{TRUE} if the raster dataset is open.

\code{$isReadOnly()}\cr
Returns a logical value, \code{TRUE} if the raster dataset has read-only access
or \code{FALSE} if it is writable.

\code{$getFileList()}\cr
Returns a character vector of files believed to be part of this dataset.
If it returns an empty string (\code{""}) it means there is believed to be no
local file system files associated with the dataset (e.g., a virtual file
system). The returned filenames will normally be relative or absolute
paths depending on the path used to originally open the dataset.

\code{$info()}\cr
Prints various information about the raster dataset to the console (no
return value, called for that side effect only).
Equivalent to the output of the \command{gdalinfo} command-line utility
(\command{gdalinfo filename}, if using the default \code{infoOptions}).
See the field \code{$infoOptions} above for setting the arguments to
\code{gdalinfo}.

\code{$infoAsJSON()}\cr
Returns information about the raster dataset as a JSON-formatted string.
Equivalent to the output of the \command{gdalinfo} command-line utility
(\command{gdalinfo -json filename}, if using the default \code{infoOptions}).
See the field \code{$infoOptions} above for setting the arguments to
\code{gdalinfo}.

\code{$getDriverShortName()}\cr
Returns the short name of the raster format driver.

\code{$getDriverLongName()}\cr
Returns the long name of the raster format driver.

\code{$getRasterXSize()}\cr
Returns the number of pixels along the x dimension.

\code{$getRasterYSize()}\cr
Returns the number of pixels along the y dimension.

\code{$getRasterCount()}\cr
Returns the number of raster bands on this dataset. For the methods
described below that operate on individual bands, the \code{band}
argument is the integer band number (1-based).

\code{$addBand(dataType, options)}\cr
Adds a band to a dataset if the underlying format supports this action.
Most formats do not, but MEM and VRT are notable exceptions that support
adding bands. The added band will always be the last band.
\code{dataType} is a character string containing the data type name
(e.g., \code{"Byte"}, \code{"UInt8"} (GDAL >= 3.13), \code{"Int16"}, \code{"UInt16"}, \code{"Int32"},
\code{"Float32"}, etc).
The \code{options} argument is a character vector of format specific \code{NAME=VALUE}
strings (may be \code{NULL}). For a MEM dataset, \code{options} can also be a vector
of \code{"numeric"}, \code{"integer"}, \code{"raw"} or \code{"complex"} values to be exposed as
a MEM band. In that case, the vector must have length equal to the raster
\code{xsize * ysize}, with values in left to right, top to bottom pixel order.
See also \code{rvector_to_MEM()}. Returns logical \code{TRUE} on success or
\code{FALSE} if a band could not be added.

\code{$getGeoTransform()}\cr
Returns the affine transformation coefficients for transforming between
pixel/line raster space (column/row) and projection coordinate space
(geospatial x/y). The return value is a numeric vector of length six.
See \url{https://gdal.org/en/stable/tutorials/geotransforms_tut.html}
for details of the affine transformation. \emph{With 1-based indexing
in \R}, the geotransform vector contains (in map units of the raster spatial
reference system):
\tabular{rl}{
GT[1] \tab x-coordinate of upper-left corner of the upper-left pixel\cr
GT[2] \tab x-component of pixel width\cr
GT[3] \tab row rotation (zero for north-up raster)\cr
GT[4] \tab y-coordinate of upper-left corner of the upper-left pixel\cr
GT[5] \tab column rotation (zero for north-up raster)\cr
GT[6] \tab y-component of pixel height (negative for north-up raster)
}

\code{$setGeoTransform(transform)}\cr
Sets the affine transformation coefficients on this dataset.
\code{transform} is a numeric vector of length six.
Returns logical \code{TRUE} on success or \code{FALSE} if the geotransform
could not be set.

\code{$getProjection()}\cr
Returns the coordinate reference system of the raster as an OGC WKT
format string. Equivalent to \code{ds$getProjectionRef()}.

\code{$getProjectionRef()}\cr
Returns the coordinate reference system of the raster as an OGC WKT
format string.
An empty string is returned when a projection definition is not available.

\code{$setProjection(projection)}\cr
Sets the projection reference for this dataset.
\code{projection} is a string in OGC WKT format.
Returns logical \code{TRUE} on success or \code{FALSE} if the projection
could not be set.

\code{$getSpatialRef()}\cr
Returns the coordinate reference system of the raster as an OGC WKT
format string. Equivalent to \code{ds$getProjectionRef()}.

\code{$bbox()}\cr
Returns a numeric vector of length four containing the bounding box
(xmin, ymin, xmax, ymax).

\code{$setBbox(bbox)}\cr
Sets the bounding box on this dataset.
\code{bbox} is a numeric vector of length four.
Returns logical \code{TRUE} on success or \code{FALSE} if the bbox
could not be set.

\code{$res()}\cr
Returns a numeric vector of length two containing the resolution
(pixel width, pixel height as positive values) for a non-rotated raster.
A warning is emitted and \code{NA} values returned if the raster has a rotated
geotransform (see method \code{$getGeoTransform()} above).

\code{$dim()}\cr
Returns an integer vector of length three containing the raster dimensions
(xsize, ysize, number of bands).
Equivalent to:

\if{html}{\out{<div class="sourceCode">}}\preformatted{c(ds$getRasterXSize(), ds$getRasterYSize(), ds$getRasterCount())
}\if{html}{\out{</div>}}

\code{$apply_geotransform(col_row)}\cr
Applies geotransform coefficients to raster coordinates in pixel/line space
(column/row), converting into georeferenced (x/y) coordinates.
\code{col_row} is a numeric matrix of raster col/row coordinates (or two-column
data frame that will be coerced to numeric matrix).
Returns a numeric matrix of geospatial x/y coordinates.
See the stand-alone function of the same name (\code{\link[=apply_geotransform]{apply_geotransform()}}) for
more info and examples.

\code{$get_pixel_line(xy)}\cr
Converts geospatial coordinates to pixel/line (raster column/row numbers).
\code{xy} is a numeric matrix of geospatial x,y coordinates in the same spatial
reference system as the raster (or two-column data frame that will be
coerced to numeric matrix). Returns an integer matrix of raster pixel/line.
See the stand-alone function of the same name (\code{\link[=get_pixel_line]{get_pixel_line()}}) for more
info and examples.

\code{$get_block_indexing(band)}\cr
Helper method returning a numeric matrix with named columns: \code{xblockoff},
\code{yblockoff}, \code{xoff}, \code{yoff}, \code{xsize}, \code{ysize}, \code{xmin}, \code{xmax}, \code{ymin},
\code{ymax}. This method provides indexing values for the block layout of the
given \code{band} number. See also the class methods:
\code{$getBlockSize()}, \code{$getActualBlockSize()} and \code{$read()}.
The returned matrix has number of rows equal to the number of blocks for the
given \code{band} number, with blocks ordered left to right, top to bottom. All
offsets are zero-based. The \code{xoff}/\code{yoff} values are pixel offsets to the
start of a block. The \code{xsize}/\code{ysize} values give the actual block sizes
accounting for potentially incomplete blocks along the right and bottom
edges. The columns \code{xmin}, \code{xmax}, \code{ymin} and \code{ymax} give the extent of each
block in geospatial coordinates.

\code{$make_chunk_index(band, max_pixels)}\cr
Helper method returning a numeric matrix with named columns: \code{xchunkoff},
\code{ychunkoff}, \code{xoff}, \code{yoff}, \code{xsize}, \code{ysize}, \code{xmin}, \code{xmax}, \code{ymin},
\code{ymax}. This method generates indexing information (offsets, sizes and
geospatial bounding boxes) for potentially multi-block chunks, defined on
block boundaries for efficient I/O. The output of this method can be used
with the \code{$readChunk()}/\code{$writeChunk()} methods to iterate I/O
operations conveniently on user-defined chunk sizes. The chunks will contain
at most \code{max_pixels} given as a numeric value optionally carrying the
\code{bit64::integer64} class attribute (numeric values will be coerced to 64-bit
integer internally by truncation). A value of \code{max_pixels = 0} (or any value
less than raster block xsize * block ysize, see \code{$getBlockSize()}
below), will return output equivalent to \code{$get_block_indexing()}.
The returned matrix has number of rows equal to the number of chunks for the
given \code{band} number, with chunks ordered left to right, top to bottom. All
offsets are zero-based. The \code{xoff}/\code{yoff} values are pixel offsets to the
start of a chunk. The \code{xsize}/\code{ysize} values give the actual chunk sizes
accounting for potentially incomplete chunks along the right and bottom
edges. The columns \code{xmin}, \code{xmax}, \code{ymin} and \code{ymax} give the extent of each
chunk in geospatial coordinates.

\code{$getDescription(band)}\cr
Returns a string containing the description for \code{band}. An empty
string is returned if no description is set for the band.
Passing \code{band = 0} will return the dataset-level description.

\code{$setDescription(band, desc)}\cr
Sets a description for \code{band}. \code{desc} is the character string
to set. No return value. (Passing \code{band = 0} can be used to set the
dataset-level description. Note that the dataset description is generally
the filename that was used to open the dataset. It usually should not be
changed by calling this method on an existing dataset.)

\code{$getBlockSize(band)}\cr
Returns a numeric vector of length two (xsize, ysize) containing the
"natural" block size of \code{band}. GDAL has a concept of the natural block
size of rasters so that applications can organize data access efficiently
for some file formats. The natural block size is the block size that is
most efficient for accessing the format. For many formats this is simply a
whole row in which case block xsize is the same as \code{$getRasterXSize()}
and block ysize is 1. However, for tiled images block size will typically
be the tile size. Note that the X and Y block sizes don't have to divide
the image size evenly, meaning that right and bottom edge blocks may be
incomplete.

\code{$getActualBlockSize(band, xblockoff, yblockoff)}\cr
Returns a numeric vector of length two (xvalid, yvalid) containing the
actual block size for a given block offset in \code{band}. Handles partial
blocks at the edges of the raster and returns the true number of pixels.
\code{xblockoff} is an integer value, the horizontal block offset for which to
calculate the number of valid pixels, with zero indicating the left most
block, 1 the next block, etc. \code{yblockoff} is likewise the vertical block
offset, with zero indicating the top most block, 1 the next block, etc.

\code{$getOverviewCount(band)}\cr
Returns the number of overview layers (a.k.a. pyramids) available for
\code{band}.

\code{$buildOverviews(resampling, levels, bands)}\cr
Build one or more raster overview images using the specified downsampling
algorithm.
\code{resampling} is a character string, one of \code{AVERAGE},
\code{AVERAGE_MAGPHASE}, \code{RMS}, \code{BILINEAR}, \code{CUBIC}, \code{CUBICSPLINE}, \code{GAUSS},
\code{LANCZOS}, \code{MODE}, \code{NEAREST} or \code{NONE}.
\code{levels} is an integer vector giving the list of overview decimation
factors to build (e.g., \code{c(2, 4, 8)}), or \code{0} to delete all overviews
(at least for external overviews (.ovr) and GTiff internal overviews).
\code{bands} is an integer vector giving a list of band numbers to build
overviews for, or \code{0} to build for all bands.
Note that for GTiff, overviews will be created internally if the dataset is
open in update mode, while external overviews (.ovr) will be created if the
dataset is open read-only.
External overviews created in GTiff format may be compressed using the
\code{COMPRESS_OVERVIEW} configuration option. All compression methods supported
by the GTiff driver are available
(e.g., \code{set_config_option("COMPRESS_OVERVIEW", "LZW")}).
Since GDAL 3.6, \code{COMPRESS_OVERVIEW} is honored when creating internal
overviews of GTiff files. The \href{https://gdal.org/en/stable/programs/gdaladdo.html}{GDAL documentation for \code{gdaladdo}} command-line
utility describes additional configuration for overview building.
See also \code{\link[=set_config_option]{set_config_option()}}. No return value, called for side effects.

\code{$getDataTypeName(band)}\cr
Returns the name of the pixel data type for \code{band}. The possible data
types are:
\tabular{rl}{
Unknown   \tab  Unknown or unspecified type\cr
Byte      \tab  8-bit unsigned integer\cr
Int8      \tab  8-bit signed integer (GDAL >= 3.7)\cr
UInt16    \tab  16-bit unsigned integer\cr
Int16     \tab  16-bit signed integer\cr
UInt32    \tab  32-bit unsigned integer\cr
Int32     \tab  32-bit signed integer\cr
UInt64    \tab  64-bit unsigned integer (GDAL >= 3.5)\cr
Int64     \tab  64-bit signed integer (GDAL >= 3.5)\cr
Float32   \tab  32-bit floating point\cr
Float64   \tab  64-bit floating point\cr
CInt16    \tab  Complex Int16\cr
CInt32    \tab  Complex Int32\cr
CFloat32  \tab  Complex Float32\cr
CFloat64  \tab  Complex Float64
}
Some raster formats including GeoTIFF ("GTiff") and Erdas Imagine .img
("HFA") support sub-byte data types. Rasters can be created with these
data types by specifying the "NBITS=n" creation option where n=1...7 for
GTiff or n=1/2/4 for HFA. In these cases, \code{$getDataTypeName()} reports
the apparent type \code{"Byte"}. GTiff also supports n=9...15 (UInt16 type) and
n=17...31 (UInt32 type), and n=16 is accepted for Float32 to generate
half-precision floating point values.

\code{$getNoDataValue(band)}\cr
Returns the nodata value for \code{band} if one exists.
This is generally a special value defined to mark pixels that are not
valid data. \code{NA} is returned if a nodata value is not defined for
\code{band}. Not all raster formats support a designated nodata value.

\code{$setNoDataValue(band, nodata_value)}\cr
Sets the nodata value for \code{band}.
\code{nodata_value} is a numeric value to be defined as the nodata marker.
Depending on the format, changing the nodata value may or may not have an
effect on the pixel values of a raster that has just been created (often
not). It is thus advised to call \code{$fillRaster()} explicitly if the
intent is to initialize the raster to the nodata value. In any case,
changing an existing nodata value, when one already exists on an initialized
dataset, has no effect on the pixels whose values matched the previous
nodata value.
Returns logical \code{TRUE} on success or \code{FALSE} if the nodata value
could not be set.

\code{$deleteNoDataValue(band)}\cr
Removes the nodata value for \code{band}.
This affects only the definition of the nodata value for raster formats
that support one (does not modify pixel values). No return value.
An error is raised if the nodata value cannot be removed.

\code{$getMaskFlags(band)}\cr
Returns the status flags of the mask band associated with \code{band}.
Masks are represented as Byte bands with a value of zero indicating nodata
and non-zero values indicating valid data. Normally the value \code{255} will be
used for valid data pixels. GDAL supports external (.msk) mask bands, and
normal Byte alpha (transparency) band as mask (any value other than \code{0} to
be treated as valid data). But masks may not be regular raster bands on the
datasource, such as an implied mask from a band nodata value or the
\code{ALL_VALID} mask. See RFC 15: Band Masks for more details
(\url{https://gdal.org/en/stable/development/rfc/rfc15_nodatabitmask.html}.

Returns a named list of GDAL mask flags and their logical values, with the
following definitions:
\itemize{
\item \code{ALL_VALID}: There are no invalid pixels, all mask values will be \code{255}.
When used this will normally be the only flag set.
\item \code{PER_DATASET}: The mask band is shared between all bands on the dataset.
\item \code{ALPHA}: The mask band is actually an alpha band and may have values other
than \code{0} and \code{255}.
\item \code{NODATA}: Indicates the mask is actually being generated from nodata
values (mutually exclusive of \code{ALPHA}).
}

\code{$getMaskBand(band)}\cr
Returns the mask filename and band number associated with \code{band}.
The return value is a named list with two elements. The \code{MaskFile} element
gives the filename where the mask band is located, e.g., a file with the
same name as the main dataset but suffixed with .msk in the case of a GDAL
external mask file. \code{MaskFile} will be an empty string for the derived
\code{ALL_VALID} and \code{NODATA} masks, which internally are freestanding bands not
considered to be a part of a dataset. The \code{MaskBand} element gives the band
number for a mask that is a regular alpha band in the main dataset or
external mask file. \code{BandNumber} will be \code{0} for the \code{ALL_VALID} and \code{NODATA}
masks.

\code{$getUnitType(band)}\cr
Returns the name of the unit type of the pixel values for \code{band}
(e.g., "m" or "ft").
An empty string (\code{""}) is returned if no units are available.

\code{$setUnitType(band, unit_type)}\cr
Sets the name of the unit type of the pixel values for \code{band}.
\code{unit_type} should be one of empty string \code{""} (the default indicating it is
unknown), "m" indicating meters, or "ft" indicating feet, though other
nonstandard values are allowed.
Returns logical \code{TRUE} on success or \code{FALSE} if the unit type
could not be set.

\code{$getScale(band)}\cr
Returns the pixel value scale (units value = (raw value * scale) + offset)
for \code{band}.
This value (in combination with the \code{$getOffset()} value) can be used to
transform raw pixel values into the units returned by \code{$getUnitType()}.
Returns \code{NA} if a scale value is not defined for this \code{band}.

\code{$setScale(band, scale)}\cr
Sets the pixel value scale (units value = (raw value * scale) + offset)
for \code{band}. Many raster formats do not implement this method.
Returns logical \code{TRUE} on success or \code{FALSE} if the scale could
not be set.

\code{$getOffset(band)}\cr
Returns the pixel value offset (units value = (raw value * scale) + offset)
for \code{band}.
This value (in combination with the \code{$getScale()} value) can be used to
transform raw pixel values into the units returned by \code{$getUnitType()}.
Returns \code{NA} if an offset value is not defined for this \code{band}.

\code{$setOffset(band, offset)}\cr
Sets the pixel value offset (units value = (raw value * scale) + offset)
for \code{band}. Many raster formats do not implement this method.
Returns logical \code{TRUE} on success or \code{FALSE} if the offset could
not be set.

\code{$getRasterColorInterp(band)}\cr
Returns a string describing the color interpretation for \code{band}.
The color interpretation values and their meanings, with several additions
in GDAL 3.10:
\tabular{ll}{
Undefined  \tab Undefined\cr
Gray       \tab Grayscale\cr
Palette    \tab Paletted (see associated color table)\cr
Red        \tab Red band of RGBA image\cr
Green      \tab Green band of RGBA image\cr
Blue       \tab Blue band of RGBA image\cr
Alpha      \tab Alpha (0 = transparent, 255 = opaque)\cr
Hue        \tab Hue band of HLS image\cr
Saturation \tab Saturation band of HLS image\cr
Lightness  \tab Lightness band of HLS image\cr
Cyan       \tab Cyan band of CMYK image\cr
Magenta    \tab Magenta band of CMYK image\cr
Yellow     \tab Yellow band of CMYK image\cr
Black      \tab Black band of CMYK image\cr
YCbCr_Y    \tab Y Luminance\cr
YCbCr_Cb   \tab Cb Chroma\cr
YCbCr_Cr   \tab Cr Chroma\cr
\emph{GDAL >= 3.10}: \tab \cr
PanBand    \tab Panchromatic band (0.40 - 1.00 micrometre)\cr
CoastalBand \tab Coastal band (0.40 - 0.45 micrometre)\cr
RedEdgeBand \tab Red-edge band (0.69 - 0.79 micrometre)\cr
NIRBand    \tab Near-InfraRed (NIR) band (0.75 - 1.40 micrometre)\cr
SWIRBand   \tab Short-Wavelength InfraRed (SWIR) band (1.40 - 3.00 micrometres)\cr
MWIRBand   \tab Mid-Wavelength InfraRed (MWIR) band (3.00 - 8.00 micrometres)\cr
LWIRBand   \tab Long-Wavelength InfraRed (LWIR) band (8.00 - 15 micrometres)\cr
TIRBand    \tab Thermal InfraRed (TIR) band (MWIR or LWIR) (3 - 15 micrometres)\cr
OtherIRBand \tab Other infrared band (0.75 - 1000 micrometres)\cr
SAR_Ka_Band \tab SAR Ka band (0.8 - 1.1 cm / 27 - 40 GHz)\cr
SAR_K_Band  \tab SAR K band (1.1 - 1.7 cm / 18 - 27 GHz)\cr
SAR_Ku_Band \tab SAR Ku band (1.7 - 2.4 cm / 12 - 18 GHz)\cr
SAR_X_Band  \tab SAR X band (2.4 - 3.8 cm / 8 - 12 GHz)\cr
SAR_C_Band  \tab SAR C band (3.8 - 7.5 cm / 4 - 8 GHz)\cr
SAR_S_Band  \tab SAR S band (7.5 - 15 cm / 2 - 4 GHz)\cr
SAR_L_Band  \tab SAR L band (15 - 30 cm / 1 - 2 GHz)\cr
SAR_P_Band  \tab SAR P band (30 - 100 cm / 0.3 - 1 GHz)
}

\code{$setRasterColorInterp(band, col_interp)}\cr
Sets the color interpretation for \code{band}. See above for the list of
valid values for \code{col_interp} (passed as a string).

\code{$getMinMax(band, approx_ok)}\cr
Returns a numeric vector of length two containing the min/max values for
\code{band}. If \code{approx_ok} is \code{TRUE} and the raster format knows these
values intrinsically then those values will be returned. If that doesn't
work, a subsample of blocks will be read to get an approximate min/max. If
the band has a nodata value it will be excluded from the minimum and
maximum. If \code{approx_ok} is \code{FALSE}, then all pixels will be read and
used to compute an exact range.

\code{$getMinMaxLocation(band)}\cr
Computes the min/max values for a band, and their locations. Pixels with
value matching the nodata value or masked by the mask band are ignored. If
the minimum or maximum value is hit in several locations, it is not
specified which location will be returned. The locations are returned as
column/row number (0-based), geospatial x/y in the coordinate system of the
raster, and WGS84 longitude/latitude. Returns a numeric vector with the
following named values: \code{min}, \code{min_col}, \code{min_row}, \code{min_geo_x},
\code{min_geo_y}, \code{min_wgs84_lon}, \code{min_wgs84_lat}, \code{max}, \code{max_col}, \code{max_row},
\code{max_geo_x}, \code{max_geo_y}, \code{max_wgs84_lon}, \code{max_wgs84_lat}. This method wraps
\code{GDALComputeRasterMinMaxLocation()} in the GDAL C API requiring GDAL >= 3.11.

\code{$getStatistics(band, approx_ok, force)}\cr
Returns a numeric vector of length four containing the minimum, maximum,
mean and standard deviation of pixel values in \code{band} (excluding
nodata pixels). Some raster formats will cache statistics allowing fast
retrieval after the first request.

\code{approx_ok}:
\itemize{
\item \code{TRUE}: Approximate statistics are sufficient, in which case overviews
or a subset of raster tiles may be used in computing the statistics.
\item \code{FALSE}: All pixels will be read and used to compute statistics (if
computation is forced).
}

\code{force}:
\itemize{
\item \code{TRUE}: The raster will be scanned to compute statistics. Once computed,
statistics will generally be "set" back on the raster band if the format
supports caching statistics.
(Note: \code{ComputeStatistics()} in the GDAL API is called automatically here.
This is a change in the behavior of \code{GetStatistics()} in the API, to a
definitive \code{force}.)
\item \code{FALSE}: Results will only be returned if it can be done quickly (i.e.,
without scanning the raster, typically by using pre-existing
STATISTICS_xxx metadata items). \code{NA}s will be returned if statistics
cannot be obtained quickly.
}

\code{$clearStatistics()}\cr
Clear statistics. Only implemented for now in PAM supported datasets
(Persistable Auxiliary Metadata via .aux.xml file). GDAL >= 3.2.

\code{$getHistogram(band, min, max, num_buckets, incl_out_of_range, approx_ok)}\cr
Computes raster histogram for \code{band}. \code{min} is the lower bound of
the histogram. \code{max} is the upper bound of the histogram.
\code{num_buckets} is the number of buckets to use (bucket size is
\code{(max - min) / num_buckets}).
\code{incl_out_of_range} is a logical scalar: if \code{TRUE} values below the
histogram range will be mapped into the first bucket and values above will
be mapped into the last bucket, if \code{FALSE} out of range values are discarded.
\code{approx_ok} is a logical scalar: \code{TRUE} if an approximate histogram is
OK (generally faster), or \code{FALSE} for an exactly computed histogram.
Returns the histogram as a numeric vector of length \code{num_buckets}.

\code{$getDefaultHistogram(band, force)}\cr
Returns a default raster histogram for \code{band}. In the GDAL API, this
method is overridden by derived classes (such as GDALPamRasterBand,
VRTDataset, HFADataset...) that may be able to fetch efficiently an already
stored histogram. \code{force} is a logical scalar: \code{TRUE} to force the
computation of a default histogram; or if \code{FALSE} and no default histogram
is available, a warning is emitted and the returned list has a 0-length
histogram vector.
Returns a list of length four containing named elements \code{min} (lower
bound), \code{max} (upper bound), \code{num_buckets} (number of buckets), and
\code{histogram} (a numeric vector of length \code{num_buckets}).

\code{$getInterBandCovMatrix(bands, approx_ok, force, write_in_metadata,
                             df_correction)}\cr
Fetch or compute the covariance matrix between bands of this dataset. The
covariance indicates the level to which two bands vary together. Requires
GDAL >= 3.13. See \code{GDALDatasetGetInterBandCovarianceMatrix()} in:
\url{https://gdal.org/en/latest/api/raster_c_api.html}. Returns a square
matrix with dimension equal to the number of bands. \code{bands} may be given as
\code{0} meaning all bands, or may be an integer vector of specific band numbers.
\code{approx_ok} specifies whether it is acceptable to use a subsample of values
(\code{TRUE}), or all pixel values should be used (\code{FALSE}).

\code{force}:
\itemize{
\item \code{TRUE}: The raster will be scanned to compute covariances.
(Note: \code{ComputeInterBandCovarianceMatrix()} in the GDAL API is called
automatically here. This is a change in the behavior of
\code{GetInterBandCovarianceMatrix()} in the API, to a definitive \code{force}.)
\item \code{FALSE}: Results will only be returned if it can be done quickly (i.e.,
without scanning the raster, by using pre-existing
\code{STATISTICS_COVARIANCES} metadata items). \code{NA} will be returned if
inter-band covariances cannot be obtained quickly.
}

\code{write_in_metadata} specifies whether \code{STATISTICS_COVARIANCES} band metadata
items should be written if covariances are computed new. \code{df_correction}
specifies a correction term to subtract in the final averaging phase of the
covariance computation, often will be \code{1}. A value of \code{df_correction = 1}
will return an unbiased estimate if the pixels in bands are considered to be
a sample of the whole population. Otherwise a value of \code{df_correction = 0}
can be used if they are considered to be the whole population.

\code{$getMetadata(band, domain)}\cr
Returns a character vector of all metadata \code{NAME=VALUE} pairs that exist in
the specified \code{domain}, or empty string (\code{""}) if there are no
metadata items in \code{domain} (metadata in the context of the GDAL
Raster Data Model
\url{https://gdal.org/en/stable/user/raster_data_model.html}).
Set \code{band = 0} to retrieve dataset-level metadata, or to an integer
band number to retrieve band-level metadata.
Set \code{domain = ""} (empty string) to retrieve metadata in the
default domain.

\code{$setMetadata(band, metadata, domain)}\cr
Sets metadata in the specified \code{domain}. The \code{metadata} argument
is given as a character vector of \code{NAME=VALUE} pairs.
Pass \code{band = 0} to set dataset-level metadata, or pass an integer
band number to set band-level metadata.
Use \code{domain = ""} (empty string) to set an item in the default domain.
Returns logical \code{TRUE} on success or \code{FALSE} if metadata could
not be set.

\code{$getMetadataItem(band, mdi_name, domain)}\cr
Returns the value of a specific metadata item named \code{mdi_name} in the
specified \code{domain}, or empty string (\code{""}) if no matching item
is found.
Set \code{band = 0} to retrieve dataset-level metadata, or to an integer
band number to retrieve band-level metadata.
Set \code{domain = ""} (empty string) to retrieve an item in the
default domain.

\code{$setMetadataItem(band, mdi_name, mdi_value, domain)}\cr
Sets the value (\code{mdi_value}) of a specific metadata item named
\code{mdi_name} in the specified \code{domain}.
Pass \code{band = 0} to set dataset-level metadata, or pass an integer
band number to set band-level metadata.
Use \code{domain = ""} (empty string) to set an item in the default domain.
Returns logical \code{TRUE} on success or \code{FALSE} if metadata could
not be set.

\code{$getMetadataDomainList(band)}\cr
Returns a character vector of metadata domains or empty string (\code{""}).
Set \code{band = 0} to retrieve dataset-level domains, or to an integer
band number to retrieve band-level domains.

\code{$read(band, xoff, yoff, xsize, ysize, out_xsize, out_ysize)}\cr
Reads a region of raster data from \code{band}. The method takes care of
pixel decimation / replication if the output size
(\code{out_xsize * out_ysize}) is different than the size of the region
being accessed (\code{xsize * ysize}).
\code{xoff} is the pixel (column) offset to the top left corner of the
region of the band to be accessed (zero to start from the left side).
\code{yoff} is the line (row) offset to the top left corner of the region of
the band to be accessed (zero to start from the top).
\emph{Note that raster row/column offsets use 0-based indexing.}
\code{xsize} is the width in pixels of the region to be accessed.
\code{ysize} is the height in pixels of the region to be accessed.
\code{out_xsize} is the width of the output array into which the desired
region will be read (typically the same value as xsize).
\code{out_ysize} is the height of the output array into which the desired
region will be read (typically the same value as ysize).
Returns a numeric or complex vector containing the values that were read.
It is organized in left to right, top to bottom pixel order.
\code{NA} will be returned in place of the nodata value if the
raster dataset has a nodata value defined for this band.
Data are read as \R integer type when possible for the raster data type
(\code{Byte}, \code{Int8}, \code{Int16}, \code{UInt16}, \code{Int32}), otherwise as type double
(\code{UInt32}, \code{Float32}, \code{Float64}).
No rescaling of the data is performed (see \code{$getScale()} and
\code{$getOffset()} above).
An error is raised if the read operation fails. See also the setting
\code{$readByteAsRaw} above.

\code{$readBlock(band, xblockoff, yblockoff)}\cr
Reads a block of raster data, without resampling. See the class methods
\code{$getBlockSize()} and \code{$getActualBlockSize()} above for a
description of raster blocks. This is a convenience method to read by block
offsets. Returns a vector of pixel values with length equal to the actual
block \code{xsize * ysize}, otherwise as described above for \code{$read()}.

\code{$readChunk(band, chunk_def)}\cr
Reads a potentially multi-block chunk of raster data, without resampling.
This is a convenience method that can be used with the output of
\code{$make_chunk_index()} (see above). The matrix of chunk offsets and sizes
returned by \code{$make_chunk_index()} (or \code{$get_block_indexing()} to
operate on blocks) can be used to iterate I/O over the raster in user-defined
chunk sizes, i.e., a row of that matrix can be passed for the \code{chunk_def}
argument. \code{chunk_def} can also be given as an numeric vector of length 4
containing the 0-based pixel offsets and pixel sizes for a chunk (xoff, yoff,
xsize, ysize). Returns a vector of pixel values with length equal to the
chunk \code{xsize * ysize}, otherwise as described above for \code{$read()}.

\code{$readToNativeRaster(xoff, yoff, xsize, ysize, out_xsize, out_ysize)}\cr
Reads a region of raster data from \code{band}. The method takes care of
pixel decimation / replication if the output size
(\code{out_xsize * out_ysize}) is different than the size of the region
being accessed (\code{xsize * ysize}).
\code{xoff} is the pixel (column) offset to the top left corner of the
region of the band to be accessed (zero to start from the left side).
\code{yoff} is the line (row) offset to the top left corner of the region of
the band to be accessed (zero to start from the top).
\emph{Note that raster row/column offsets use 0-based indexing.}
\code{xsize} is the width in pixels of the region to be accessed.
\code{ysize} is the height in pixels of the region to be accessed.
\code{out_xsize} is the width of the output array into which the desired
region will be read (typically the same value as xsize).
\code{out_ysize} is the height of the output array into which the desired
region will be read (typically the same value as ysize).
Returns an object of class \code{nativeRaster} with attributes 'dim', and
'channels'  containing the values that were read in R's native RGB/A encoding.

\code{$write(band, xoff, yoff, xsize, ysize, rasterData)}\cr
Writes a region of raster data to \code{band}.
\code{xoff} is the pixel (column) offset to the top left corner of the
region of the band to be accessed (zero to start from the left side).
\code{yoff} is the line (row) offset to the top left corner of the region of
the band to be accessed (zero to start from the top).
\emph{Note that raster row/column offsets use 0-based indexing.}
\code{xsize} is the width in pixels of the region to write.
\code{ysize} is the height in pixels of the region to write.
\code{rasterData} is a numeric or complex vector containing values to write.
It is organized in left to right, top to bottom pixel order. \code{NA} in
\code{rasterData} should be replaced with a suitable nodata value prior to
writing (see \code{$getNoDataValue()} and \code{$setNoDataValue()} above).
An error is raised if the operation fails (no return value).

\code{$writeBlock(band, xblockoff, yblockoff, rasterData)}\cr
Writes a block of raster data. See the class methods \code{$getBlockSize()}
and \code{$getActualBlockSize()} above for a description of raster blocks.
This is a convenience method to write by block offsets.. Otherwise, this
method operates like \code{$write()}. The length of \code{rasterData} must be the
same as the actual \code{xsize * ysize} of the destination block.

\code{$writeChunk(band, chunk_def, rasterData)}\cr
Writes a potentially multi-block chunk of raster data. This is a convenience
method that can be used to iterate I/O over the raster in user-defined chunk
sizes, see method \code{$readChunk()} above. Otherwise, this method operates
like \code{$write()}. The length of \code{rasterData} must be the same as
\code{xsize * ysize} of the destination chunk.

\code{$fillRaster(band, value, ivalue)}\cr
Fills \code{band} with a constant value. GDAL makes no guarantees about what
values the pixels in newly created files are set to, so this method can be
used to clear a band to a specified "default" value. The fill \code{value} is
passed as \code{numeric}, but this will be converted to the underlying raster
data type before writing to the file. The \code{ivalue} argument allows setting
the imaginary component of a complex value. Note that \code{ivalue} is a required
argument but can be set to \code{0} for real data types. No return value. An
error is raised if the operation fails.

\code{$getColorTable(band)}\cr
Returns the color table associated with \code{band}, or \code{NULL} if
there is no associated color table. The color table is returned as an
integer matrix with five columns. To associate a color with a raster pixel,
the pixel value is used as a subscript into the color table. This means that
the colors are always applied starting at zero and ascending
(see
\href{https://gdal.org/en/stable/user/raster_data_model.html#color-table}{GDAL Color Table}).
Column 1 contains the pixel values. Interpretation of columns 2:5 depends
on the value of \code{$getPaletteInterp()} (see below).
For "RGB", columns 2:5 contain red, green, blue, alpha as 0-255 integer
values.

\code{$getPaletteInterp(band)}\cr
If \code{band} has an associated color table, this method returns a
character string with the palette interpretation for columns 2:5 of the
table. An empty string (\code{""}) is returned if \code{band} does not have
an associated color table. The palette interpretation values and their
meanings are:
\itemize{
\item Gray: column 2 contains grayscale values (columns 3:5 unused)
\item RGB: columns 2:5 contain red, green, blue, alpha
\item CMYK: columns 2:5 contain cyan, magenta, yellow, black
\item HLS: columns 2:4 contain hue, lightness, saturation (column 5 unused)
}

\code{$setColorTable(band, col_tbl, palette_interp)}\cr
Sets the raster color table for \code{band}.
\code{col_tbl} is an integer matrix or data frame with either four or five
columns (see \code{$getColorTable()} above). Column 1 contains the pixel
values. Valid values are integers 0 and larger (note that GTiff format
supports color tables only for Byte and UInt16 bands). Negative values
will be skipped with a warning emitted. Interpretation of columns 2:5
depends on the value of \code{$getPaletteInterp()} (see above). For RGB,
columns 2:4 contain red, green, blue as 0-255 integer values, and an
optional column 5 contains alpha transparency values (defaults to 255
opaque).
\code{palette_interp} is a string, one of \code{Gray}, \code{RGB}, \code{CMYK} or \code{HLS}
(see \code{$getPaletteInterp()} above).
Returns logical \code{TRUE} on success or \code{FALSE} if the color table
could not be set.

\code{$clearColorTable(band)}\cr
Clears the raster color table for \code{band}.
Returns logical \code{TRUE} on success or \code{FALSE} if the color table
could not be cleared, e.g., if this action is not supported by the driver.

\code{$getDefaultRAT(band)}\cr
Returns the Raster Attribute Table for \code{band} as a data frame,
or \code{NULL} if there is no associated Raster Attribute Table. See the
stand-alone function \code{\link[=buildRAT]{buildRAT()}} for details of the Raster Attribute Table
format.

\code{$setDefaultRAT(band, df)}\cr
Sets a default Raster Attribute Table for \code{band} from data frame \code{df}.
The input data frame will be checked for attribute \code{"GDALRATTableType"}
which can have values of \code{"thematic"} or \code{"athematic"} (for continuous data).
Columns of the data frame will be checked for attribute \code{"GFU"} (for "GDAL
field usage"). If the \code{"GFU"} attribute is missing, a value of \code{"Generic"}
will be used (corresponding to \code{GFU_Generic} in the GDAL API, for general
purpose field). Columns with other, specific field usage values should
generally be present in \code{df}, such as fields containing the set of unique
(discrete) pixel values (GFU \code{"MinMax"}), pixel counts (GFU \code{"PixelCount"}),
class names (GFU \code{"Name"}), color values (GFUs \code{"Red"}, "\verb{Green"}, \code{"Blue"}),
etc. The data frame will also be checked for attributes \code{"Row0Min"} and
\code{"BinSize"} which can have numeric values that describe linear binning.
See the stand-alone function \code{\link[=buildRAT]{buildRAT()}} for details of the GDAL Raster
Attribute Table format and its representation as data frame.

\code{$flushCache()}\cr
Flush all write cached data to disk. Any raster data written via GDAL calls,
but buffered internally will be written to disk. Using this method does not
preclude calling \code{$close()} to properly close the dataset and ensure
that important data not addressed by \code{$flushCache()} is written in the
file (see also \code{$open()} above). No return value, called for side
effects.

\code{$getChecksum(band, xoff, yoff, xsize, ysize)}\cr
Returns a 16-bit integer (0-65535) checksum from a region of raster data
on \code{band}.
Floating point data are converted to 32-bit integer so decimal portions of
such raster data will not affect the checksum. Real and imaginary
components of complex bands influence the result.
\code{xoff} is the pixel (column) offset of the window to read.
\code{yoff} is the line (row) offset of the window to read.
\emph{Raster row/column offsets use 0-based indexing.}
\code{xsize} is the width in pixels of the window to read.
\code{ysize} is the height in pixels of the window to read.

\code{$close()}\cr
Closes the GDAL dataset (no return value, called for side effects).
Calling \code{$close()} results in proper cleanup, and flushing of any
pending writes. Forgetting to close a dataset opened in update mode on some
formats such as GTiff could result in being unable to open it afterwards.
The \code{GDALRaster} object is still available after calling \code{$close()}.
The dataset can be re-opened on the existing \code{filename} with
\code{$open(read_only=TRUE)} or \code{$open(read_only=FALSE)}.
}
}

\examples{
lcp_file <- system.file("extdata/storm_lake.lcp", package="gdalraster")
ds <- new(GDALRaster, lcp_file)
ds

## print information about the dataset to the console
ds$info()

## retrieve the raster format name
ds$getDriverShortName()
ds$getDriverLongName()

## retrieve a list of files composing the dataset
ds$getFileList()

## retrieve dataset parameters
ds$getRasterXSize()
ds$getRasterYSize()
ds$getGeoTransform()
ds$getProjection()
ds$getRasterCount()
ds$bbox()
ds$res()
ds$dim()

## retrieve some band-level parameters
ds$getDescription(band = 1)
ds$getBlockSize(band = 1)
ds$getOverviewCount(band = 1)
ds$getDataTypeName(band = 1)
# LCP format does not support an intrinsic nodata value so this returns NA:
ds$getNoDataValue(band = 1)

## LCP driver reports several dataset- and band-level metadata
## (format description at https://gdal.org/en/stable/drivers/raster/lcp.html)
## set band = 0 to retrieve dataset-level metadata
## set domain = "" (empty string) for the default metadata domain
ds$getMetadata(band = 0, domain = "")

## retrieve metadata for a band as a vector of name=value pairs
ds$getMetadata(band = 4, domain = "")

## retrieve the value of a specific metadata item
ds$getMetadataItem(band = 2, mdi_name = "SLOPE_UNIT_NAME", domain = "")

## read one row of pixel values from band 1 (elevation)
## raster row/column index are 0-based
## the upper left corner is the origin
## read the tenth row:
ncols <- ds$getRasterXSize()
rowdata <- ds$read(band = 1, xoff = 0, yoff = 9,
                   xsize = ncols, ysize = 1,
                   out_xsize = ncols, out_ysize = 1)
head(rowdata)

ds$close()

## create a new raster using lcp_file as a template
new_file <- file.path(tempdir(), "storml_newdata.tif")
rasterFromRaster(srcfile = lcp_file,
                 dstfile = new_file,
                 nbands = 1,
                 dtName = "Byte",
                 init = -9999)

ds_new <- new(GDALRaster, new_file, read_only = FALSE)

## write random values to all pixels
set.seed(42)
ncols <- ds_new$getRasterXSize()
nrows <- ds_new$getRasterYSize()
for (row in 0:(nrows - 1)) {
    rowdata <- round(runif(ncols, 0, 100))
    ds_new$write(band = 1,
                 xoff = 0,
                 yoff = row,
                 xsize = ncols,
                 ysize = 1,
                 rowdata)
}

## re-open in read-only mode when done writing
## this will ensure flushing of any pending writes (implicit $close)
ds_new$open(read_only = TRUE)

## getStatistics returns min, max, mean, sd, and sets stats in the metadata
ds_new$getStatistics(band = 1, approx_ok = FALSE, force = TRUE)
ds_new$getMetadataItem(band = 1, "STATISTICS_MEAN", "")

## close the dataset for proper cleanup
ds_new$close()
\dontshow{deleteDataset(new_file)}
\donttest{
## using a GDAL Virtual File System handler '/vsicurl/'
## see: https://gdal.org/en/stable/user/virtual_file_systems.html
url <- "/vsicurl/https://raw.githubusercontent.com/"
url <- paste0(url, "firelab/gdalraster/main/sample-data/")
url <- paste0(url, "lf_elev_220_mt_hood_utm.tif")

set_config_option("GDAL_HTTP_CONNECTTIMEOUT", "20")
set_config_option("GDAL_HTTP_TIMEOUT", "20")
if (http_enabled() && vsi_stat(url)) {
  ds <- new(GDALRaster, url)
  plot_raster(ds, legend = TRUE, main = "Mount Hood elevation (m)")
  ds$close()
}
set_config_option("GDAL_HTTP_CONNECTTIMEOUT", "")
set_config_option("GDAL_HTTP_TIMEOUT", "")
}
}
\seealso{
Package overview in \code{\link[=gdalraster-package]{help("gdalraster-package")}}

\code{vignette("raster-api-tutorial")}

\code{\link[=read_ds]{read_ds()}} is a convenience wrapper for \code{GDALRaster$read()}
}
