R: Convert to Pixel Image

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,
            na.replace=NULL)

      ## S3 method for class 'owin'
    as.im(X, W=NULL, ...,
            eps=NULL, dimyx=NULL, xy=NULL,
            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,
            na.replace=NULL)

      ## S3 method for class 'function'
    as.im(X, W=NULL, ...,
            eps=NULL, dimyx=NULL, xy=NULL,
            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,
            na.replace=NULL, approx=TRUE)

      ## S3 method for class 'nnfun'
    as.im(X, W=NULL, ...,
            eps=NULL, dimyx=NULL, xy=NULL,
            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,
            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 `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`, only named arguments are passed, and only if they match the names of formal arguments of `X`.
`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 if the result would normally be a list of pixel images but the list contains only one image. If `drop=TRUE` (the default), the pixel image is extracted and the result is a pixel image. If `drop=FALSE`, this list is returned as the result.
`stringsAsFactors` | 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 depends on the version of R. See section Handling Character Strings.
`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"` (see `owin.object`). The result is an image with all pixel entries equal to `value` inside the window `X`, and `NA` outside.

- 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 window `W` (and `NA` outside, unless the argument `na.replace` is given). Argument `W` 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 argument `W` must be present. This window will be converted to a binary image mask. Then the function `X` will be evaluated in the form `X(x, y, ...)` where `x` and `y` are vectors containing 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 a `function(x,y,...)` defined in a spatial region. The function will be evaluated as described above. The window `W` defaults to the domain of definition of the function.

- an object of class `"funxy"` which also belongs to one of the following special classes. If `approx=TRUE` (the default), the function will be evaluated approximately using a very fast algorithm. If `approx=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 command `distfun`). The fast approximation is the distance transform `distmap`.

  - an object of class `"nnfun"` representing a nearest neighbour function (created by the command `nnfun`). The fast approximation is `nnmap`.

  - an object of class `"densityfun"` representing a kernel estimate of intensity (created by the command `densityfun`). The fast approximation is the Fast Fourier Transform algorithm in `density.ppp`.

  - an object of class `"Smoothfun"` representing kernel-smoothed values (created by the command `Smoothfun`). The fast approximation is the Fast Fourier Transform algorithm in `Smooth.ppp`.

- An `expression` involving the variables `x` and `y` representing the spatial coordinates, and possibly also involving other variables. The additional argument `W` must be present; it will be converted to a binary image mask. The expression `X` will be evaluated in an environment where `x` and `y` are vectors containing the spatial coordinates of all the pixels in the image mask. Evaluation of the expression `X` must yield a vector or factor, of the same length as `x` and `y`, giving the pixel values.

- a list with entries `x, y, z` in the format expected by the standard `R` functions `image.default` and `contour.default`. That is, `z` is a matrix of pixel values, `x` and `y` are vectors of x and y coordinates respectively, and `z[i,j]` is the pixel value for the location `(x[i],y[j])`.

- a point pattern (object of class `"ppp"`). See the separate documentation for `as.im.ppp`.

- A data frame with at least three columns. Columns named `x`, `y` and `z`, if present, will be assumed to contain the spatial coordinates and the pixel values, respectively. Otherwise the `x` and `y` 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` or `xy` 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 a `list(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 is `stringsAsFactors=FALSE` and the default can be changed by setting `options(stringsAsFactors=FALSE)`.

- in R versions >= 4.1.0 the default is `stringsAsFactors=FALSE` and there is no option to change the default.

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

Separate documentation for `as.im.ppp`

### Examples

      data(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)
      # 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)

[Package spatstat.geom version 2.3-2 Index]