spatstat (version 1.31-3)

Extract.im: Extract Subset of Image

Description

Extract a subset or subregion of a pixel image.

Usage

## S3 method for class 'im':
[(x, i, j, \dots, drop=TRUE, 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 point pattern (an object of class "ppp"), or any type of index t

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.

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.

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

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):

1. iis a spatial object such as a window, a pixel image with logical values, or a point pattern; or
2. i,jare indices for the matrixas.matrix(x); or
3. ican be converted to a point pattern byas.ppp(i, W=as.owin(x)), andiis 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 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 NAs 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 spatial window then X[i, drop=TRUE] is either:

• a numeric vector containing the pixel values for all pixels that lie inside the windowi. This happens ifiisnota rectangle (i.e.i$type != "rectangle") or ifrescue=FALSE.
• a pixel image. This happens only ifiis a rectangle (i$type = "rectangle") andrescue=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 as.owin(x). Then the pixel values at these points will be extracted as a vector.

See Also

im.object, [<-.im, ppp.object, as.ppp, owin.object, plot.im

Examples

# 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
 data(letterR)
 R <- affine(letterR, diag(c(1,1)/2), c(-2,-0.7))
 Y <- X[R, drop=FALSE]
 plot(Y)

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