# eval.im

##### Evaluate Expression Involving Pixel Images

Evaluates any expression involving one or more pixel images, and returns a pixel image.

- Keywords
- manip, spatial, programming

##### Usage

`eval.im(expr, envir, harmonize=TRUE)`

##### Arguments

- expr
An expression.

- envir
Optional. The environment in which to evaluate the expression, or a named list containing pixel images to be used in the expression.

- harmonize
Logical. Whether to resolve inconsistencies between the pixel grids.

##### Details

This function is a wrapper to make it easier to perform pixel-by-pixel calculations in an image.

Pixel images in spatstat
are represented by objects of class `"im"`

(see `im.object`

). These are essentially matrices of
pixel values, with extra attributes recording the pixel dimensions,
etc.

Suppose `X`

is a pixel image. Then `eval.im(X+3)`

will add 3 to the value of every pixel in `X`

, and return
the resulting pixel image.

Suppose `X`

and `Y`

are two pixel images with compatible
dimensions: they have the same number of pixels, the same physical
size of pixels, and the same bounding box. Then
`eval.im(X + Y)`

will add the corresponding pixel values in
`X`

and `Y`

, and return the resulting pixel image.

In general, `expr`

can be any expression in the R language involving
(a) the *names* of pixel images, (b) scalar
constants, and (c) functions which are vectorised.
See the Examples.

First `eval.im`

determines which of the *variable names*
in the expression `expr`

refer to pixel images. Each such name
is replaced by a matrix containing the pixel values. The expression is
then evaluated. The result should be a matrix; it is taken as
the matrix of pixel values.

The expression `expr`

must be vectorised.
There must be at least one pixel image in the expression.

All images must have compatible dimensions.
If `harmonize=TRUE`

, images that have incompatible dimensions
will be resampled so that they are compatible.
If `harmonize=FALSE`

, images that are incompatible will cause an error.

##### Value

An image object of class `"im"`

.

##### See Also

##### Examples

```
# NOT RUN {
# test images
X <- as.im(function(x,y) { x^2 - y^2 }, unit.square())
Y <- as.im(function(x,y) { 3 * x + y }, unit.square())
eval.im(X + 3)
eval.im(X - Y)
eval.im(abs(X - Y))
Z <- eval.im(sin(X * pi) + Y)
## Use of 'envir'
W <- eval.im(sin(U), list(U=density(cells)))
# }
```

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