Extract.im {spatstat.geom}

Extract Subset of Image

Description

Extract a subset or subregion of a pixel image.

Usage

  ## S3 method for class '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, 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.

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. i is a spatial object such as a window, a pixel image with logical values, a linear network, or a point pattern; or

2. i,j are indices for the matrix as.matrix(x); or

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

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

Author(s)

Adrian Baddeley [e-mail], Rolf Turner [e-mail] and Ege Rubak [e-mail]

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