R: Extract Subset of Image

Extract.im {spatstat} | R Documentation

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

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

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk

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

[Package spatstat version 1.54-0 Index]