Extract a subset or subregion of a pixel image.

```
# S3 method for im
[(x, i, j, …, drop=TRUE, tight=FALSE,
raster=NULL, rescue=is.owin(i))
```

x

A two-dimensional pixel image.
An object of class `"im"`

.

i

Object defining the subregion or subset to be extracted.
Either a spatial window (an object of class `"owin"`

), or a
pixel image with logical values, or a linear network (object of
class `"linnet"`

) or a point pattern (an object
of class `"ppp"`

), or any type of index that applies to a
matrix, or something that can be converted to a point pattern
by `as.ppp`

(using the window of `x`

).

j

An integer or logical vector serving as the column index if
matrix indexing is being used. Ignored if `i`

is a spatial object.

…

Ignored.

drop

Logical value, specifying whether to return a vector containing
the selected pixel values (`drop=TRUE`

, the default)
or to return a pixel image containing
these values in their original spatial positions
(`drop=FALSE`

).
The exception is that if `i`

is a point pattern,
then `drop`

specifies whether to delete `NA`

values.
See Details.

tight

Logical value. If `tight=TRUE`

, and if the result of the
subset operation is an image, the image will be trimmed
to the smallest possible rectangle.

raster

Optional. An object of class `"owin"`

or `"im"`

determining a pixel grid.

rescue

Logical value indicating whether rectangular blocks of data should always be returned as pixel images.

Either a pixel image or a vector of pixel values. See Details.

If you have a 2-column matrix containing the \(x,y\) coordinates
of point locations, then to prevent this being interpreted as an
array index, you should convert it to a `data.frame`

or to a point pattern.

If `W`

is a window or a pixel image, then `x[W, drop=FALSE]`

will return an image defined on the same pixel array
as the original image `x`

. If you want to obtain an image
whose pixel dimensions agree with those of `W`

, use the
`raster`

argument, `x[W, raster=W, drop=FALSE]`

.

This function extracts a subset of the pixel values in a
pixel image. (To reassign the pixel values, see `[<-.im`

).

The image `x`

must be an object of class
`"im"`

representing a pixel image defined inside a
rectangle in two-dimensional space (see `im.object`

).

The subset to be extracted is determined by the arguments `i,j`

according to the following rules (which are checked in this order):

`i`

is a spatial object such as a window, a pixel image with logical values, a linear network, or a point pattern; or`i,j`

are indices for the matrix`as.matrix(x)`

; or`i`

can be converted to a point pattern by`as.ppp(i, W=Window(x))`

, and`i`

is not a matrix.

If `i`

is a spatial window (an object of class `"owin"`

),
the pixels inside this window are selected.

If

`drop=TRUE`

(the default) and either`is.rectangle(i)=FALSE`

or`rescue=FALSE`

, the pixel values are extracted; the result is a vector, with one entry for each pixel of`x`

that lies inside the window`i`

. Pixel values may be`NA`

, indicating that the selected pixel lies outside the spatial domain of the image.if

`drop=FALSE`

, the result is another pixel image, obtained by setting the pixel values to`NA`

outside the window`i`

. The effect is that the pixel image`x`

is clipped to the window`i`

.if

`i`

is a rectangle and`rescue=TRUE`

, the result is a pixel image as described above.To ensure that an image is produced in all circumstances, set

`drop=FALSE`

. To ensure that pixel values are extracted as a vector in all circumstances, set`drop=TRUE, rescue=FALSE`

.

If `i`

is a pixel image with logical values,
it is interpreted as a spatial window (with `TRUE`

values
inside the window and `FALSE`

outside).

If `i`

is a linear network (object of class `"linnet"`

),
the pixels which lie on this network are selected.

If

`drop=TRUE`

(the default), the pixel values are extracted; the result is a vector, with one entry for each pixel of`x`

that lies along the network`i`

. Pixel values may be`NA`

, indicating that the selected pixel lies outside the spatial domain of the image.if

`drop=FALSE`

, the result is a pixel image on a linear network (object of class`"linim"`

), obtained by setting the pixel values of`x`

to`NA`

except for those which lie on the network`i`

. The effect is that the pixel image`x`

is restricted to the network`i`

.

If `i`

is a point pattern (an object of class
`"ppp"`

) or something that can be converted to a point pattern,
then the values of the pixel image at the points of
this pattern are extracted.
The result is a vector of pixel values.
This is a simple way to read the
pixel values at a given spatial location.

if

`drop=FALSE`

the length of the result is equal to the number of points in the pattern. It may contain`NA`

values which indicate that the corresponding point lies outside the spatial domain of the image.if

`drop=TRUE`

(the default),`NA`

values are deleted. The result is a vector whose length may be shorter than the number of points of the pattern.

If the optional argument `raster`

is given, then it should
be a binary image mask or a pixel image. Then
`x`

will first be converted to an image defined on the
pixel grid implied by `raster`

, before the subset operation
is carried out.
In particular, `x[i, raster=i, drop=FALSE]`

will return
an image defined on the same pixel array as the object `i`

.

If `i`

does not satisfy any of the conditions above, then
the algorithm attempts to interpret `i`

and `j`

as indices for the matrix `as.matrix(x)`

.
Either `i`

or `j`

may be missing or blank.
The result is usually a vector or matrix of pixel values.
Exceptionally the result is a pixel image if `i,j`

determines
a rectangular subset of the pixel grid, and if the user specifies
`rescue=TRUE`

.

Finally, if none of the above conditions is met,
the object `i`

may also be a data frame or list of `x,y`

coordinates which will be converted to a point pattern, taking the
observation window to be `Window(x)`

. Then the pixel values
at these points will be extracted as a vector.

# NOT RUN { # make up an image X <- setcov(unit.square()) plot(X) # a rectangular subset W <- owin(c(0,0.5),c(0.2,0.8)) Y <- X[W] plot(Y) # a polygonal subset R <- affine(letterR, diag(c(1,1)/2), c(-2,-0.7)) plot(X[R, drop=FALSE]) plot(X[R, drop=FALSE, tight=TRUE]) # a point pattern Y <- X[cells] # look up a specified location X[list(x=0.1,y=0.2)] # 10 x 10 pixel array X <- as.im(function(x,y) { x + y }, owin(c(-1,1),c(-1,1)), dimyx=10) # 100 x 100 W <- as.mask(disc(1, c(0,0)), dimyx=100) # 10 x 10 raster X[W,drop=FALSE] # 100 x 100 raster X[W, raster=W, drop=FALSE] # }