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))A two-dimensional pixel image.
An object of class "im".
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).
An integer or logical vector serving as the column index if
matrix indexing is being used. Ignored if i is a spatial object.
Ignored.
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.
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.
Optional. An object of class "owin" or "im"
determining a pixel grid.
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 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 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 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.
# 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]
# }
Run the code above in your browser using DataLab