# Extract.im

##### Extract Subset of Image

Extract a subset or subregion of a pixel image.

##### Usage

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

##### Arguments

- 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. Locations in

`w`

that lie outside the spatial domain of the image`x`

return a pixel value of`NA`

if`drop=FALSE`

, and are omitted if`drop=TRUE`

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

##### Details

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 values of the image inside this window are extracted
(after first clipping the window to the spatial domain of the image
if necessary).

If `i`

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

),
the values of the image on this network are extracted.

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 point pattern (an object of class
`"ppp"`

), then the values of the pixel image at the points of
this pattern are extracted. This is a simple way to read the
pixel values at a given spatial location.

At locations outside the spatial domain of the image, the pixel
value is undefined, and is taken to be `NA`

. The logical
argument `drop`

determines whether such `NA`

values
will be returned or omitted. It also influences the format of
the return value.

If `i`

is a point pattern (or something that can be converted
to a point pattern), then `X[i, drop=FALSE]`

is a numeric
vector containing the pixel values at each of the points of
the pattern. Its length is equal to the number of points in the
pattern `i`

. It may contain `NA`

s corresponding to
points which lie outside the spatial domain of the image `x`

.
By contrast, `X[i]`

or `X[i, drop=TRUE]`

contains only
those pixel values which are not `NA`

. It may be shorter.

If `i`

is a spatial window then `X[i, drop=FALSE]`

is
another pixel image of the same dimensions as `X`

obtained
by setting all pixels outside the window `i`

to have value
`NA`

. When the result is displayed by `plot.im`

the effect is that the pixel image `x`

is clipped to the
window `i`

.

If `i`

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

)
then `X[i, drop=FALSE]`

is another pixel image of the same
dimensions as `X`

obtained by restricting the pixel image
`X`

to the linear network. The result also belongs to the
class `"linim"`

(pixel image on a linear network).

If `i`

is a spatial window then `X[i, drop=TRUE]`

is either:

a numeric vector containing the pixel values for all pixels that lie inside the window

`i`

. This happens if`i`

is*not*a rectangle (i.e.`i$type != "rectangle"`

) or if`rescue=FALSE`

.a pixel image. This happens only if

`i`

is a rectangle (`i$type = "rectangle"`

) and`rescue=TRUE`

(the default).

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.

##### Value

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

##### Warnings

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

.

##### See Also

##### Examples

```
# 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
P <- rpoispp(20)
Y <- X[P]
# 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]
# }
```

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