R: Create a Raster Object

as.raster {grDevices} | R Documentation

## 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, ...)

    ## S3 method for class 'matrix'
    as.raster(x, max = 1, ...)
    ## S3 method for class 'array'
    as.raster(x, max = 1, ...)

    ## S3 method for class 'logical'
    as.raster(x, max = 1, ...)
    ## S3 method for class 'numeric'
    as.raster(x, max = 1, ...)
    ## S3 method for class 'character'
    as.raster(x, max = 1, ...)
    ## S3 method for class 'raw'
    as.raster(x, max = 255L, ...)

### Arguments

`x` | any R object.
`max` | number giving the maximum of the color values range.
`...` | further arguments passed to or from other methods.

### Details

An object of class `"raster"` is a matrix of colour values as given by `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 `as.raster()` function to generate a raster object from their input.

The `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 `matrix` (of colour strings).

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

There is a `is.na` method which returns a logical matrix of the same dimensions as the raster object. Note that `NA` values are interpreted as the fully transparent colour by some (but not all) graphics devices.

### Value

For `as.raster()`, a raster object.

For `is.raster()`, a logical indicating whether `x` is a raster object.

### 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.

### 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"

[Package grDevices version 4.0.5 Index]