spatstat.geom (version 2.1-0)

im: Create a Pixel Image Object

Description

Creates an object of class "im" representing a two-dimensional pixel image.

Usage

im(mat, xcol=seq_len(ncol(mat)), yrow=seq_len(nrow(mat)),
   xrange=NULL, yrange=NULL,
   unitname=NULL)

Arguments

mat

matrix or vector containing the pixel values of the image.

xcol

vector of \(x\) coordinates for the pixel grid

yrow

vector of \(y\) coordinates for the pixel grid

xrange,yrange

Optional. Vectors of length 2 giving the \(x\) and \(y\) limits of the enclosing rectangle. (Ignored if xcol, yrow are present.)

unitname

Optional. Name of unit of length. Either a single character string, or a vector of two character strings giving the singular and plural forms, respectively.

Warnings

The internal representation of images is likely to change in future releases of spatstat. The safe way to extract pixel values from an image object is to use as.matrix.im or [.im.

Details

This function creates an object of class "im" representing a ‘pixel image’ or two-dimensional array of values.

The pixel grid is rectangular and occupies a rectangular window in the spatial coordinate system. The pixel values are scalars: they can be real numbers, integers, complex numbers, single characters or strings, logical values, or categorical values. A pixel's value can also be NA, meaning that no value is defined at that location, and effectively that pixel is ‘outside’ the window. Although the pixel values must be scalar, photographic colour images (i.e., with red, green, and blue brightness channels) can be represented as character-valued images in spatstat, using R's standard encoding of colours as character strings.

The matrix mat contains the ‘greyscale’ values for a rectangular grid of pixels. Note carefully that the entry mat[i,j] gives the pixel value at the location (xcol[j],yrow[i]). That is, the row index of the matrix mat corresponds to increasing y coordinate, while the column index of mat corresponds to increasing x coordinate. Thus yrow has one entry for each row of mat and xcol has one entry for each column of mat. Under the usual convention in R, a correct display of the image would be obtained by transposing the matrix, e.g. image.default(xcol, yrow, t(mat)), if you wanted to do it by hand.

The entries of mat may be numeric (real or integer), complex, logical, character, or factor values. If mat is not a matrix, it will be converted into a matrix with nrow(mat) = length(yrow) and ncol(mat) = length(xcol).

To make a factor-valued image, note that R has a quirky way of handling matrices with factor-valued entries. The command matrix cannot be used directly, because it destroys factor information. To make a factor-valued image, do one of the following:

• Create a factor containing the pixel values, say mat <- factor(.....), and then assign matrix dimensions to it by dim(mat) <- c(nr, nc) where nr, nc are the numbers of rows and columns. The resulting object mat is both a factor and a vector.

• Supply mat as a one-dimensional factor and specify the arguments xcol and yrow to determine the dimensions of the image.

• Use the functions cut.im or eval.im to make factor-valued images from other images).

For a description of the methods available for pixel image objects, see im.object.

To convert other kinds of data to a pixel image (for example, functions or windows), use as.im.

See Also

im.object for details of the class.

as.im for converting other kinds of data to an image.

as.matrix.im, [.im, eval.im for manipulating images.

Examples

# NOT RUN {
   vec <- rnorm(1200)
   mat <- matrix(vec, nrow=30, ncol=40)
   whitenoise <- im(mat)
   whitenoise <- im(mat, xrange=c(0,1), yrange=c(0,1))
   whitenoise <- im(mat, xcol=seq(0,1,length=40), yrow=seq(0,1,length=30))
   whitenoise <- im(vec, xcol=seq(0,1,length=40), yrow=seq(0,1,length=30))
   plot(whitenoise)

   # Factor-valued images:
   f <- factor(letters[1:12])
   dim(f) <- c(3,4)
   Z <- im(f)

   # Factor image from other image:
   cutwhite <- cut(whitenoise, 3)
   plot(cutwhite)

   # Factor image from raw data
   cutmat <- cut(mat, 3)
   dim(cutmat) <- c(30,40)
   cutwhite <- im(cutmat)
   plot(cutwhite)
# }