R: Pixel Image Approximation of a Window

as.mask {spatstat.geom}

R Documentation

Pixel Image Approximation of a Window

Description

Obtain a discrete (pixel image) approximation of a given window

Usage

 as.mask(w, eps=NULL, dimyx=NULL, xy=NULL,
         rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"))

Arguments

`w`	A window (object of class `"owin"`) or data acceptable to `as.owin`.
`eps`	(optional) width and height of pixels. A single number, or a numeric vector of length 2.
`dimyx`	(optional) pixel array dimensions. A single integer, or an integer vector of length 2 giving dimensions in the y and x directions.
`xy`	(optional) data containing pixel coordinates, such as a pixel image (object of class `"im"`), or a window of type `"mask"`. See Details.
`rule.eps`	Character string (partially matched) specifying what to do when `eps` is not a divisor of the frame size. Ignored if `eps` is missing or null. See Details.

Details

A ‘mask’ is a spatial window that is represented by a pixel image with binary values. It is an object of class "owin" with type "mask".

This function as.mask creates a representation of any spatial window w as a mask. It generates a rectangular grid of locations in the plane, tests whether each of these locations lies inside w, and stores the results as a mask.

The most common use of this function is to approximate the shape of a rectangular or polygonal window w by a mask, for computational purposes. In this case, we will usually want to have a very fine grid of pixels.

This function can also be used to generate a coarsely-spaced grid of locations inside a window, for purposes such as subsampling and prediction.

The argument w should be a window (object of class "owin"). If it is another kind of spatial data, then the window information will be extracted using as.owin.

The grid spacing and location are controlled by the arguments eps, dimyx and xy, which are mutually incompatible.

If eps is given, then it specifies the desired grid spacing, that is, the desired size of the pixels. If eps is a single number, it specifies that the desired grid spacing is eps in both the x and y directions, that is, the desired pixels are squares with side length eps. If eps is a vector of length 2, it specifies that the desired grid spacing is eps[1] in the x direction and eps[2] in the y direction. That is, the desired pixels are rectangles of width eps[1] and height eps[2].

When eps is given, the argument rule.eps specifies what to do if pixels of the desired size would not fit exactly into the rectangular frame of w.

if rule.eps="adjust.eps" (the default), the rectangular frame will remain unchanged, and the grid spacing (pixel size) eps will be reduced slightly so that an integer number of pixels fits exactly into the frame.
if rule.eps="grow.frame", the grid spacing (pixel size) eps will remain unchanged, and the rectangular frame will be expanded slightly so that it consists of an integer number of pixels in each direction.
if rule.eps="shrink.frame", the grid spacing (pixel size) eps will remain unchanged, and the rectangular frame will be contracted slightly so that it consists of an integer number of pixels in each direction.

If dimyx is given, then the pixel grid will be an m \times n rectangular grid where m, n are given by dimyx[2], dimyx[1] respectively. Warning: dimyx[1] is the number of pixels in the y direction, and dimyx[2] is the number in the x direction. The grid spacing (pixel size) is determined by the frame size and the number of pixels.

If xy is given, then this should be some kind of data specifing the coordinates of a pixel grid. It may be

a list or structure containing elements x and y which are numeric vectors of equal length. These will be taken as x and y coordinates of the margins of the grid. The pixel coordinates will be generated from these two vectors.
a pixel image (object of class "im").
a window (object of class "owin") which is of type "mask" so that it contains pixel coordinates.

If xy is given and is either a pixel image or a mask, then w may be omitted, and the window information will be extracted from xy.

If neither eps nor dimyx nor xy is given, the pixel raster dimensions are obtained from spatstat.options("npixel").

There is no inverse of this function. However, the function as.polygonal will compute a polygonal approximation of a binary mask.

Value

A window (object of class "owin") of type "mask" representing a binary pixel image.

Discretisation rule

The rule used in as.mask is that a pixel is part of the discretised window if and only if the centre of the pixel falls in the original window. This is usually sufficient for most purposes, and is fast to compute.

Other discretisation rules are possible; they are available using the function owin2mask.

Converting a spatial pattern to a mask

If the intention is to discretise or pixellate a spatial pattern, such as a point pattern, line segment pattern or a linear network, then as.mask is not the appropriate function to use, because as.mask extracts only the window information and converts this window to a mask.

To discretise a point pattern, use pixellate.ppp. To discretise a line segment pattern, use pixellate.psp or psp2mask. To discretise a linear network, use pixellate.linnet.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

Examples

  w <- owin(c(0,10),c(0,10), poly=list(x=c(1,2,3,2,1), y=c(2,3,4,6,7)))
  m <- as.mask(w)
  if(interactive()) {
     plot(w)
     plot(m)
  }
  x <- 1:9
  y <- seq(0.25, 9.75, by=0.5)
  m <- as.mask(w, xy=list(x=x, y=y))

  B <- square(1)
  as.mask(B, eps=0.3)
  as.mask(B, eps=0.3, rule.eps="g")
  as.mask(B, eps=0.3, rule.eps="s")

[Package spatstat.geom version 3.2-9 Index]