as.im: 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, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)
  ## S3 method for class 'owin':
as.im(X, W=NULL, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL, value=1)
  ## S3 method for class 'matrix':
as.im(X, W=NULL, \dots)
  ## S3 method for class 'tess':
as.im(X, W=NULL, \dots, 
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)
  ## S3 method for class 'function':
as.im(X, W=NULL, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL, strict=FALSE)
  ## S3 method for class 'funxy':
as.im(X, W=Window(X), ...)
  ## S3 method for class 'distfun':
as.im(X, W=NULL, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)
  ## S3 method for class 'nnfun':
as.im(X, W=NULL, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)
  ## S3 method for class 'Smoothfun':
as.im(X, W=NULL, \dots)
  ## S3 method for class 'leverage.ppm':
as.im(X, \dots)
  ## S3 method for class 'data.frame':
as.im(X, \dots, step, fatal=TRUE, drop=TRUE)
  ## S3 method for class 'default':
as.im(X, W=NULL, \dots,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)

Arguments

Data to be converted to a pixel image.

Window object which determines the spatial domain and pixel array geometry.

...

Additional arguments passed to X when X is a function.

eps,dimyx,xy

Optional parameters passed to as.mask which determine the pixel array geometry. See as.mask.

na.replace

Optional value to replace NA entries in the output image.

value

Optional. The value to be assigned to pixels inside the window, if X is a window.

strict

Logical value indicating whether to match formal arguments of X when X is a function. If strict=FALSE (the default), all the ... arguments are passed to X. If strict=TRUE

step

Optional. A single number, or numeric vector of length 2,
    giving the grid step lengths
    in the $x$ and $y$ directions.

fatal

Logical value indicating what to do if the resulting image
    would be too large for available memory. If fatal=TRUE (the
    default), an error occurs. If fatal=FALSE, a warning is
    issued and NULL is returned.

drop

Logical value indicating what to do when X
    is a data frame with 3 columns. If drop=TRUE (the default),
    the result is a pixel image. If drop=FALSE, the result is
    a list containing one image.

`Value`

A pixel image (object of class "im"),
  or a list of pixel images, 
  or NULL if the conversion failed.

`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 tovalueinside the windowX,
    andNAoutside.
a matrix.
a tessellation (object of class"tess").
    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.
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 windowW(andNAoutside, unless the
    argumentna.replaceis given).
    ArgumentWis required.
a function of the formfunction(x, y, ...)which is to be evaluated to yield the image pixel values.
    In this case, the additional argumentWmust be present.
    This window will be converted to
    a binary image mask. Then the functionXwill be evaluated
    in the formX(x, y, ...)wherexandyarevectorscontaining the$x$and$y$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,...)
an object of class"distfun"representing a distance function
    (created by the commanddistfun).
an object of class"nnfun"representing a nearest neighbour function
    (created by the commandnnfun).
a list with entriesx, y, zin the format expected by
    the standardRfunctionsimage.defaultandcontour.default.
    That is,zis a matrix of pixel values,xandyare vectors of$x$and$y$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 namedx,yandz, if present,
    will be assumed to contain the spatial coordinates and the pixel
    values, respectively. Otherwise thexandycoordinates 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 argumenteps,dimyxorxyif present;
the pixel dimensions of the windowW, if it is
    present and if it is a binary mask;
the pixel dimensions ofXif it is an image,
    a binary mask, or alist(x,y,z);
the default pixel dimensions, 
    controlled byspatstat.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.

`See Also`

Separate documentation for as.im.ppp

`Examples`

Run this codedata(demopat)
  # 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)
  # 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
  data(letterR)
  Z <- as.im(f, letterR, x0=2.5, y0=2)
  image(Z)
  # usual convention in S
  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)

  # pixellate the Dirichlet tessellation
  Di <- dirichlet(runifpoint(10))
  plot(as.im(Di))
  plot(Di, add=TRUE)

  # 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(slope) <- c("metre","metres")
  all.equal(slope, grad) # TRUE
Run the code above in your browser using DataLab