% File src/library/grid/man/as.raster.Rd
% Part of the R package, https://www.R-project.org
% Copyright 2009-2015 R Core Team
% Distributed under GPL 2 or later

\name{as.raster}
\alias{is.raster}
\alias{as.raster}
\alias{as.raster.logical}
\alias{as.raster.numeric}
\alias{as.raster.raw}
\alias{as.raster.character}
\alias{as.raster.matrix}
\alias{as.raster.array}

\title{Create a Raster Object}
\description{
  Functions to create a raster object (representing a bitmap
  image) and coerce other objects to a raster object.
}
\usage{
is.raster(x)
as.raster(x, \dots)

\method{as.raster}{matrix}(x, max = 1, \dots)
\method{as.raster}{array}(x, max = 1, \dots)

\method{as.raster}{logical}(x, max = 1, \dots)
\method{as.raster}{numeric}(x, max = 1, \dots)
\method{as.raster}{character}(x, max = 1, \dots)
\method{as.raster}{raw}(x, max = 255L, \dots)
}
\arguments{
  \item{x}{any \R object.}
  \item{max}{number giving the maximum of the color values range.}
  \item{\dots}{further arguments passed to or from other methods.}
}
\details{
  An object of class \code{"raster"} is a matrix of colour values as
  given by \code{\link{rgb}} representing a bitmap image.

  It is not expected that the user will need to call these functions
  directly; functions to render bitmap images in graphics packages will
  make use of the \code{as.raster()} function to generate a raster
  object from their input.

  The \code{as.raster()} function is (S3) generic so methods can be
  written to convert other \R objects to a raster object.

  The default implementation for numeric matrices interprets scalar
  values on black-to-white scale.

  Raster objects can be subsetted like a matrix and it is
  possible to assign to a subset of a raster object.

  There is a method for converting a raster object to a
  \code{\link{matrix}} (of colour strings).

  Raster objects can be compared for equality or inequality (with each
  other or with a colour string).

  There is a \code{\link{is.na}} method which returns a logical matrix
  of the same dimensions as the raster object.  Note that \code{NA}
  values are interpreted as the fully transparent colour by some (but
  not all) graphics devices.
}
\note{
  Raster images are internally represented row-first, which can cause
  confusion when trying to manipulate a raster object.  The recommended
  approach is to coerce a raster to a matrix, perform the manipulation,
  then convert back to a raster.
}
\value{
  For \code{as.raster()}, a raster object.

  For \code{is.raster()}, a logical indicating whether
  \code{x} is a raster object.
}
\examples{
# A red gradient
as.raster(matrix(hcl(0, 80, seq(50, 80, 10)),
                 nrow = 4, ncol = 5))

# Vectors are 1-column matrices ...
#   character vectors are color names ...
as.raster(hcl(0, 80, seq(50, 80, 10)))
#   numeric vectors are greyscale ...
as.raster(1:5, max = 5)
#   logical vectors are black and white ...
as.raster(1:10 \%\% 2 == 0)

# ... unless nrow/ncol are supplied ...
as.raster(1:10 \%\% 2 == 0, nrow = 1)

# Matrix can also be logical or numeric (or raw) ...
as.raster(matrix(c(TRUE, FALSE), nrow = 3, ncol = 2))
as.raster(matrix(1:3/4, nrow = 3, ncol = 4))

# An array can be 3-plane numeric (R, G, B planes) ...
as.raster(array(c(0:1, rep(0.5, 4)), c(2, 1, 3)))

# ... or 4-plane numeric (R, G, B, A planes)
as.raster(array(c(0:1, rep(0.5, 6)), c(2, 1, 4)))

# subsetting
r <- as.raster(matrix(colors()[1:100], ncol = 10))
r[, 2]
r[2:4, 2:5]

# assigning to subset
r[2:4, 2:5] <- "white"

# comparison
r == "white"

\dontshow{% regression tests
stopifnot(r[] == r,
          identical(r[3:5], colors()[3:5]))
r[2:4] <- "black"
stopifnot(identical(r[1:4, 1], as.raster(c("white", rep("black", 3)))))
}% end{tests}
}
\keyword{ dplot }