% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/display.R
\name{plot_raster}
\alias{plot_raster}
\title{Display raster data}
\usage{
plot_raster(
  data,
  xsize = NULL,
  ysize = NULL,
  nbands = NULL,
  max_pixels = 2.5e+07,
  col_tbl = NULL,
  maxColorValue = 1,
  normalize = TRUE,
  minmax_def = NULL,
  minmax_pct_cut = NULL,
  col_map_fn = NULL,
  pixel_fn = NULL,
  xlim = NULL,
  ylim = NULL,
  interpolate = TRUE,
  asp = 1,
  axes = TRUE,
  main = "",
  xlab = "x",
  ylab = "y",
  xaxs = "i",
  yaxs = "i",
  legend = FALSE,
  digits = 2,
  na_col = rgb(0, 0, 0, 0),
  ...
)
}
\arguments{
\item{data}{Either a \code{GDALRaster} object from which data will be read, or
a numeric vector of pixel values arranged in left to right, top to
bottom order, or a list of band vectors. If input is vector or list,
the information in attribute \code{gis} will be used if present (see \code{\link[=read_ds]{read_ds()}}),
potentially ignoring values below for \code{xsize}, \code{ysize}, \code{nbands}.}

\item{xsize}{The number of pixels along the x dimension in \code{data}. If \code{data}
is a \code{GDALRaster} object, specifies the size at which the raster will be
read (used for argument \code{out_xsize} in \code{GDALRaster$read()}). By default,
the entire raster will be read at full resolution.}

\item{ysize}{The number of pixels along the y dimension in \code{data}. If \code{data}
is a \code{GDALRaster} object, specifies the size at which the raster will be
read (used for argument \code{out_ysize} in \code{GDALRaster$read()}). By default,
the entire raster will be read at full resolution.}

\item{nbands}{The number of bands in \code{data}. Must be either 1 (grayscale) or
3 (RGB). For RGB, \code{data} are interleaved by band. If \code{nbands} is \code{NULL} (the
default), then \code{nbands = 3} is assumed if the input data contain 3 bands,
otherwise band 1 is used.}

\item{max_pixels}{The maximum number of pixels that the function will
attempt to display (per band). An error is raised if \code{(xsize * ysize)}
exceeds this value. Setting to \code{NULL} turns off this check.}

\item{col_tbl}{A color table as a matrix or data frame with four or five
columns. Column 1 contains the numeric pixel values. Columns 2:4 contain
the intensities of the red, green and blue primaries (\code{0:1} by default,
or use integer \code{0:255} by setting \code{maxColorValue = 255}).
An optional column 5 may contain alpha transparency values, \code{0} for fully
transparent to \code{1} (or \code{maxColorValue}) for opaque (the default if column 5
is missing). If \code{data} is a \code{GDALRaster} object, a built-in color table will
be used automatically if one exists in the dataset.}

\item{maxColorValue}{A number giving the maximum of the color values range
in \code{col_tbl} (see above). The default is \code{1}.}

\item{normalize}{Logical. \code{TRUE} to rescale pixel values so that their
range is \verb{[0,1]}, normalized to the full range of the pixel data by default
(\code{min(data)}, \code{max(data)}, per band). Ignored if \code{col_tbl} is used.
Set \code{normalize} to \code{FALSE} if a color map function is used that
operates on raw pixel values (see \code{col_map_fn} below).}

\item{minmax_def}{Normalize to user-defined min/max values (in terms of
the pixel data, per band). For single-band grayscale, a numeric vector of
length two containing min, max. For 3-band RGB, a numeric vector of length
six containing b1_min, b2_min, b3_min, b1_max, b2_max, b3_max.}

\item{minmax_pct_cut}{Normalize to a truncated range of the pixel data using
percentile cutoffs (removes outliers). A numeric vector of length two giving
the percentiles to use (e.g., \code{c(2, 98)}). Applied per band. Ignored if
\code{minmax_def} is used.}

\item{col_map_fn}{An optional color map function that maps input pixel values
to colors in "#RRGGBB" (or "#RRGGBBAA") character form (default is
\code{grDevices::gray} for single-band data or \code{grDevices::rgb} for 3-band).
Ignored if \code{col_tbl} is used. Set \code{normalize = FALSE} if using a color
map function that operates on raw pixel values. This argument can also be
given as a color palette, in which case a color-ramp function is assumed.
The color palette can be a character vector of \code{"#RRGGBB"} or \code{"#RRGGBBAA"},
color names from \code{grDevices::colors()}, or a positive integer that indexes
into \code{grDevices::palette()} (i.e., must be a valid argument to
\code{grDevices::col2rgb()}).}

\item{pixel_fn}{An optional function that will be applied to the input
pixel data. Must accept vector input and return a numeric vector of the same
length as its input.}

\item{xlim}{Numeric vector of length two giving the x coordinate range.
If \code{data} is a \code{GDALRaster} object, the default is the raster xmin, xmax in
georeferenced coordinates, otherwise the default uses pixel/line
coordinates (\code{c(0, xsize)}).}

\item{ylim}{Numeric vector of length two giving the y coordinate range.
If \code{data} is a \code{GDALRaster} object, the default is the raster ymin, ymax in
georeferenced coordinates, otherwise the default uses pixel/line
coordinates (\code{c(ysize, 0)}).}

\item{interpolate}{Logical indicating whether to apply linear interpolation
to the image when drawing (default \code{TRUE}).}

\item{asp}{Numeric. The aspect ratio y/x (see \code{?plot.window}).}

\item{axes}{Logical. \code{TRUE} to draw axes (the default).}

\item{main}{The main title (on top).}

\item{xlab}{Title for the x axis (see \code{?title}).}

\item{ylab}{Title for the y axis (see \code{?title}).}

\item{xaxs}{The style of axis interval calculation to be used for the x axis
(see \code{?par}).}

\item{yaxs}{The style of axis interval calculation to be used for the y axis
(see \code{?par}).}

\item{legend}{Logical indicating whether to include a legend on the plot.
Currently, legends are only supported for continuous data. A color table
will be used if one is specified or the raster has a built-in color table,
otherwise the value for \code{col_map_fn} will be used.}

\item{digits}{The number of digits to display after the decimal point in
the legend labels when raster data are floating point.}

\item{na_col}{Color to use for \code{NA} as a 7- or 9-character hexadecimal code.
The default is transparent (\code{"#00000000"}, the return value of
\code{rgb(0,0,0,0)}).}

\item{...}{Other parameters to be passed to \code{plot.default()}.}
}
\description{
\code{plot_raster()} displays raster data using base \code{graphics}.
}
\details{
By default, contrast enhancement by stretch to min/max is applied when
the input data are single-band grayscale with any raster data type, or
three-band RGB with raster data type larger than Byte (=UInt8 in
GDAL >= 3.13). The minimum/maximum of the input data are used by default
(i.e., no outlier removal). No stretch is applied by default when the input
is an RGB byte raster. These defaults can be overridden by specifying either
the \code{minmax_def} argument (user-defined min/max per band), or the
\code{minmax_pct_cut} argument (ignore outlier pixels based on a percentile range
per band). These settings (and the \code{normalize} argument) are ignored if a
color table is used.
}
\note{
\code{plot_raster()} uses the function \code{graphics::rasterImage()} for plotting
which is not supported on some devices (see \code{?rasterImage}).

If \code{data} is an object of class \code{GDALRaster}, then \code{plot_raster()} will
attempt to read the entire raster into memory by default (unless the number
of pixels per band would exceed \code{max_pixels}).
A reduced resolution overview can be read by setting \code{xsize}, \code{ysize}
smaller than the raster size on disk.
(If \code{data} is instead specified as a vector of pixel values, a reduced
resolution overview would be read by setting \code{out_xsize} and \code{out_ysize}
smaller than the raster region defined by \code{xsize}, \code{ysize} in a call to
\code{GDALRaster$read()}).
The GDAL_RASTERIO_RESAMPLING configuration option can be
defined to override the default resampling (NEAREST) to one of BILINEAR,
CUBIC, CUBICSPLINE, LANCZOS, AVERAGE or MODE, for example:
\preformatted{
set_config_option("GDAL_RASTERIO_RESAMPLING", "BILINEAR")
}
}
\examples{
## Elevation
elev_file <- system.file("extdata/storml_elev.tif", package="gdalraster")
ds <- new(GDALRaster, elev_file)

# all other arguments are optional when passing a GDALRaster object
# grayscale
plot_raster(ds, legend = TRUE, main = "Storm Lake elevation (m)")

# color ramp from a user-defined palette: the `col_map_fn` can optionally
# be given as a color palette, for which a color ramp function is assumed
pal <- c("#00A60E", "#63C600", "#E6E600", "#E9BD3B", "#ECB176", "#EFC2B3",
         "#F2F2F2")

plot_raster(ds, col_map_fn = pal, legend = TRUE,
            main = "Storm Lake elevation (m)")

ds$close()

## Landsat band combination
b4_file <- system.file("extdata/sr_b4_20200829.tif", package="gdalraster")
b5_file <- system.file("extdata/sr_b5_20200829.tif", package="gdalraster")
b6_file <- system.file("extdata/sr_b6_20200829.tif", package="gdalraster")
band_files <- c(b6_file, b5_file, b4_file)

vrt_file <- file.path(tempdir(), "storml_b6_b5_b4.vrt")
buildVRT(vrt_file, band_files, cl_arg = "-separate")

ds <- new(GDALRaster, vrt_file)

plot_raster(ds, main = "Landsat 6-5-4 (vegetative analysis)")

ds$close()
\dontshow{vsi_unlink(vrt_file)}

## LANDFIRE Existing Vegetation Cover (EVC) with color map
evc_file <- system.file("extdata/storml_evc.tif", package="gdalraster")

# colors from the CSV attribute table distributed by LANDFIRE
evc_csv <- system.file("extdata/LF20_EVC_220.csv", package="gdalraster")
vat <- read.csv(evc_csv)
head(vat)
vat <- vat[, c(1, 6:8)]

ds <- new(GDALRaster, evc_file)
plot_raster(ds, col_tbl = vat, interpolate = FALSE,
            main = "Storm Lake LANDFIRE EVC")

ds$close()

## Apply a pixel function
if (requireNamespace("scales")) {
  f <- system.file("extdata/complex.tif", package="gdalraster")
  ds <- new(GDALRaster, f)
  ds$getDataTypeName(band = 1)  # complex floating point

  plot_raster(ds,
              pixel_fn = Arg,
              col_map_fn = scales::pal_viridis(option = "plasma")(6),
              interpolate = FALSE,
              legend = TRUE,
              main = "Arg(complex.tif)")

  ds$close()
}
}
\seealso{
\code{\link[=GDALRaster]{GDALRaster$read()}}, \code{\link[=read_ds]{read_ds()}}, \code{\link[=set_config_option]{set_config_option()}}
}
