# im

##### Create a Pixel Image Object

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.

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

.

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

.

##### 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)
# }
```

*Documentation reproduced from package spatstat, version 1.55-1, License: GPL (>= 2)*