as.im {spatstat.geom} | R Documentation |
Convert to Pixel Image
Description
Converts various kinds of data to a pixel image
Usage
as.im(X, ...)
## S3 method for class 'im'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL)
## S3 method for class 'owin'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL, value=1)
## S3 method for class 'matrix'
as.im(X, W=NULL, ...)
## S3 method for class 'tess'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL, values=NULL)
## S3 method for class 'function'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL,
stringsAsFactors=NULL,
strict=FALSE, drop=TRUE)
## S3 method for class 'funxy'
as.im(X, W=Window(X), ...)
## S3 method for class 'expression'
as.im(X, W=NULL, ...)
## S3 method for class 'distfun'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL, approx=TRUE)
## S3 method for class 'nnfun'
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL, approx=TRUE)
## S3 method for class 'data.frame'
as.im(X, ..., step, fatal=TRUE, drop=TRUE)
## Default S3 method:
as.im(X, W=NULL, ...,
eps=NULL, dimyx=NULL, xy=NULL,
rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
na.replace=NULL)
Arguments
X |
Data to be converted to a pixel image. |
W |
Window object which determines the spatial domain and pixel array geometry. |
... |
Additional arguments passed to |
eps , dimyx , xy , rule.eps |
Optional parameters passed to |
na.replace |
Optional value to replace |
value |
Optional.
The value to be assigned to pixels inside the window,
if |
values |
Optional.
Vector of values to be assigned to each tile of the tessellation,
when |
strict |
Logical value indicating whether to match formal arguments
of |
step |
Optional. A single number, or numeric vector of length 2,
giving the grid step lengths
in the |
fatal |
Logical value indicating what to do if the resulting image
would be too large for available memory. If |
drop |
Logical value indicating what to do if the result would
normally be a list of pixel images but the list contains
only one image.
If |
stringsAsFactors |
Logical value (passed to |
approx |
Logical value indicating whether to compute an approximate result at faster speed. |
Details
This function converts the data X
into a pixel image
object of class "im"
(see im.object
).
The function as.im
is generic, with methods for the classes
listed above.
Currently X
may be any of the following:
-
a pixel image object, of class
"im"
. -
a window object, of class
"owin"
(seeowin.object
). The result is an image with all pixel entries equal tovalue
inside the windowX
, andNA
outside. -
a matrix.
-
a tessellation (object of class
"tess"
). By default, the result is a factor-valued image, with one factor level corresponding to each tile of the tessellation. Pixels are classified according to the tile of the tessellation into which they fall. If argumentvalues
is given, the result is a pixel image in which every pixel inside thei
-th tile of the tessellation has pixel value equal tovalues[i]
. -
a single number (or a single logical, complex, factor or character value). The result is an image with all pixel entries equal to this constant value inside the window
W
(andNA
outside, unless the argumentna.replace
is given). ArgumentW
is required. -
a function of the form
function(x, y, ...)
which is to be evaluated to yield the image pixel values. In this case, the additional argumentW
must be present. This window will be converted to a binary image mask. Then the functionX
will be evaluated in the formX(x, y, ...)
wherex
andy
are vectors containing thex
andy
coordinates of all the pixels in the image mask, and...
are any extra arguments given. This function must return a vector or factor of the same length as the input vectors, giving the pixel values. -
an object of class
"funxy"
representing afunction(x,y,...)
defined in a spatial region. The function will be evaluated as described above. The windowW
defaults to the domain of definition of the function. -
an object of class
"funxy"
which also belongs to one of the following special classes. Ifapprox=TRUE
(the default), the function will be evaluated approximately using a very fast algorithm. Ifapprox=FALSE
, the function will be evaluated exactly at each grid location as described above.-
an object of class
"distfun"
representing a distance function (created by the commanddistfun
). The fast approximation is the distance transformdistmap
. -
an object of class
"nnfun"
representing a nearest neighbour function (created by the commandnnfun
). The fast approximation isnnmap
. -
an object of class
"densityfun"
representing a kernel estimate of intensity (created by the commanddensityfun
). The fast approximation is the Fast Fourier Transform algorithm indensity.ppp
. -
an object of class
"Smoothfun"
representing kernel-smoothed values (created by the commandSmoothfun
). The fast approximation is the Fast Fourier Transform algorithm inSmooth.ppp
.
-
-
An
expression
involving the variablesx
andy
representing the spatial coordinates, and possibly also involving other variables. The additional argumentW
must be present; it will be converted to a binary image mask. The expressionX
will be evaluated in an environment wherex
andy
are vectors containing the spatial coordinates of all the pixels in the image mask. Evaluation of the expressionX
must yield a vector or factor, of the same length asx
andy
, giving the pixel values. -
a list with entries
x, y, z
in the format expected by the standardR
functionsimage.default
andcontour.default
. That is,z
is a matrix of pixel values,x
andy
are vectors ofx
andy
coordinates respectively, andz[i,j]
is the pixel value for the location(x[i],y[j])
. -
a point pattern (object of class
"ppp"
). See the separate documentation foras.im.ppp
. -
A data frame with at least three columns. Columns named
x
,y
andz
, if present, will be assumed to contain the spatial coordinates and the pixel values, respectively. Otherwise thex
andy
coordinates will be taken from the first two columns of the data frame, and any remaining columns will be interpreted as pixel values.
The spatial domain (enclosing rectangle) of the pixel image
is determined by the argument W
. If W
is absent,
the spatial domain is determined by X
.
When X
is a function, a matrix, or a single numerical value,
W
is required.
The pixel array dimensions of the final resulting image are determined by (in priority order)
the argument
eps
,dimyx
orxy
if present;the pixel dimensions of the window
W
, if it is present and if it is a binary mask;the pixel dimensions of
X
if it is an image, a binary mask, or alist(x,y,z)
;the default pixel dimensions, controlled by
spatstat.options
.
Note that if eps
, dimyx
or xy
is given, this will override
the pixel dimensions of X
if it has them.
Thus, as.im
can be used to change an image's pixel dimensions.
If the argument na.replace
is given, then all NA
entries
in the image will be replaced by this value. The resulting image is
then defined everwhere on the full rectangular domain, instead of a
smaller window. Here na.replace
should be a single value,
of the same type as the other entries in the image.
If X
is a pixel image that was created by an older version
of spatstat, the command X <- as.im(X)
will
repair the internal format of X
so that it conforms to the
current version of spatstat.
If X
is a data frame with m
columns,
then m-2
columns of data are interpreted as pixel values,
yielding m-2
pixel images. The result of
as.im.data.frame
is a list of pixel
images, belonging to the class "imlist"
.
If m = 3
and drop=TRUE
(the default), then the
result is a pixel image rather than a list containing this image.
If X
is a function(x,y)
which returns a matrix of
values, then as.im(X, W)
will be a list of pixel images.
Value
A pixel image (object of class "im"
),
or a list of pixel images,
or NULL
if the conversion failed.
Character-valued images
By default, if the pixel value data are character strings, they will be
treated as levels of a factor, and the resulting image will be
factor-valued. To prevent the conversion of character strings to
factors, use the argument stringsAsFactors=FALSE
,
which is recognised by most of the
methods for as.im
, or alternatively set
options(stringsAsFactors=FALSE)
.
Handling Character Strings
The argument stringsAsFactors
is a logical value (passed to data.frame
)
specifying how to handle pixel values which
are character strings. If TRUE
, character values are
interpreted as factor levels. If FALSE
, they remain
as character strings. The default values of stringsAsFactors
depends on the version of R.
In R versions
< 4.1.0
the factory-fresh default isstringsAsFactors=FALSE
and the default can be changed by settingoptions(stringsAsFactors=FALSE)
.In R versions
>= 4.1.0
the default isstringsAsFactors=FALSE
and there is no option to change the default.
Author(s)
Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk
See Also
Separate documentation for as.im.ppp
Examples
# window object
W <- Window(demopat)
plot(W)
Z <- as.im(W)
image(Z)
# function
Z <- as.im(function(x,y) {x^2 + y^2}, unit.square())
image(Z)
# or as an expression
Z <- as.im(expression(x^2+y^2), square(1))
# function with extra arguments
f <- function(x, y, x0, y0) {
sqrt((x - x0)^2 + (y-y0)^2)
}
Z <- as.im(f, unit.square(), x0=0.5, y0=0.5)
image(Z)
# Revisit the Sixties
Z <- as.im(f, letterR, x0=2.5, y0=2)
image(Z)
# usual convention in R
stuff <- list(x=1:10, y=1:10, z=matrix(1:100, nrow=10))
Z <- as.im(stuff)
# convert to finer grid
Z <- as.im(Z, dimyx=256)
#' distance functions
d <- distfun(redwood)
Zapprox <- as.im(d)
Zexact <- as.im(d, approx=FALSE)
plot(solist(approx=Zapprox, exact=Zexact), main="")
# pixellate the Dirichlet tessellation
Di <- dirichlet(redwood)
plot(as.im(Di))
plot(Di, add=TRUE, border="white")
# as.im.data.frame is the reverse of as.data.frame.im
grad <- bei.extra$grad
slopedata <- as.data.frame(grad)
slope <- as.im(slopedata)
unitname(grad) <- unitname(slope) <- unitname(grad) # for compatibility
all.equal(slope, grad) # TRUE
## handling of character values
as.im("a", W=letterR, na.replace="b")
as.im("a", W=letterR, na.replace="b", stringsAsFactors=FALSE)