R: Create a Window

owin {spatstat} | R Documentation

## Create a Window

### Description

Creates an object of class `"owin"` representing an observation window in the two-dimensional plane

### Usage

      owin(xrange=c(0,1), yrange=c(0,1), ..., poly=NULL, mask=NULL,
    unitname=NULL, xy=NULL)

### Arguments

`xrange` | x coordinate limits of enclosing box
`yrange` | y coordinate limits of enclosing box
`...` | Ignored.
`poly` | Optional. Polygonal boundary of window. Incompatible with `mask`.
`mask` | Optional. Logical matrix giving binary image of window. Incompatible with `poly`.
`unitname` | Optional. Name of unit of length. Either a single character string, or a vector of two character strings giving the singular and plural forms, respectively.
`xy` | Optional. List with components `x` and `y` specifying the pixel coordinates for `mask`.

### Details

In the spatstat library, a point pattern dataset must include information about the window of observation. This is represented by an object of class `"owin"`. See `owin.object` for an overview.

To create a window in its own right, users would normally invoke `owin`, although sometimes `as.owin` may be convenient.

A window may be rectangular, polygonal, or a mask (a binary image).

- rectangular windows: If only `xrange` and `yrange` are given, then the window will be rectangular, with its x and y coordinate dimensions given by these two arguments (which must be vectors of length 2). If no arguments are given at all, the default is the unit square with dimensions `xrange=c(0,1)` and `yrange=c(0,1)`.

- polygonal windows: If `poly` is given, then the window will be polygonal.

  - single polygon: If `poly` is a matrix or data frame with two columns, or a structure with two component vectors `x` and `y` of equal length, then these values are interpreted as the cartesian coordinates of the vertices of a polygon circumscribing the window. The vertices must be listed anticlockwise. No vertex should be repeated (i.e. do not repeat the first vertex).

  - multiple polygons or holes: If `poly` is a list, each entry `poly[[i]]` of which is a matrix or data frame with two columns or a structure with two component vectors `x` and `y` of equal length, then the successive list members `poly[[i]]` are interpreted as separate polygons which together make up the boundary of the window. The vertices of each polygon must be listed anticlockwise if the polygon is part of the external boundary, but clockwise if the polygon is the boundary of a hole in the window. Again, do not repeat any vertex.

- binary masks: If `mask` is given, then the window will be a binary image.

  - Specified by logical matrix: Normally the argument `mask` should be a logical matrix such that `mask[i,j]` is `TRUE` if the point `(x[j],y[i])` belongs to the window, and `FALSE` if it does not. Note carefully that rows of `mask` correspond to the y coordinate, and columns to the x coordinate. Here `x` and `y` are vectors of x and y coordinates equally spaced over `xrange` and `yrange` respectively. The pixel coordinate vectors `x` and `y` may be specified explicitly using the argument `xy`, which should be a list containing components `x` and `y`. Alternatively there is a sensible default.

  - Specified by list of pixel coordinates: Alternatively the argument `mask` can be a data frame with 2 or 3 columns. If it has 2 columns, it is expected to contain the spatial coordinates of all the pixels which are inside the window. If it has 3 columns, it should contain the spatial coordinates (x,y) of every pixel in the grid, and the logical value associated with each pixel. The pixels may be listed in any order.

To create a window which is mathematically defined by inequalities in the Cartesian coordinates, use `raster.x()` and `raster.y()` as in the examples below.

Functions `square` and `disc` will create square and circular windows, respectively.

### Value

An object of class `"owin"` describing a window in the two-dimensional plane.

### Validity of polygon data

Polygon data may contain geometrical inconsistencies such as self-intersections and overlaps. These inconsistencies must be removed to prevent problems in other spatstat functions. By default, polygon data will be repaired automatically using polygon-clipping code. The repair process may change the number of vertices in a polygon and the number of polygon components. To disable the repair process, set `spatstat.options(fixpolygons=FALSE)`.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner r.turner@auckland.ac.nz

### See Also

`owin.object`, `as.owin`, `complement.owin`, `ppp.object`, `ppp`

`square`, `hexagon`, `regularpolygon`, `disc`, `ellipse`.

### Examples

      w <- owin()
      w <- owin(c(0,1), c(0,1))
      # the unit square

      w <- owin(c(10,20), c(10,30), unitname=c("foot","feet"))
      # a rectangle of dimensions 10 x 20 feet
      # with lower left corner at (10,10)

      # polygon (diamond shape)
      w <- owin(poly=list(x=c(0.5,1,0.5,0),y=c(0,1,2,1)))
      w <- owin(c(0,1), c(0,2), poly=list(x=c(0.5,1,0.5,0),y=c(0,1,2,1)))

      # polygon with hole
      ho <- owin(poly=list(list(x=c(0,1,1,0), y=c(0,0,1,1)),
                           list(x=c(0.6,0.4,0.4,0.6), y=c(0.2,0.2,0.4,0.4))))

      w <- owin(c(-1,1), c(-1,1), mask=matrix(TRUE, 100,100))
              # 100 x 100 image, all TRUE
      X <- raster.x(w)
      Y <- raster.y(w)
      wm <- owin(w$xrange, w$yrange, mask=(X^2 + Y^2 <= 1))
              # discrete approximation to the unit disc

      ## Not run:
      if(FALSE) {
        plot(c(0,1),c(0,1),type="n")
        bdry <- locator()
        # click the vertices of a polygon (anticlockwise)
      }

    ## End(Not run)

      w <- owin(poly=bdry)
      ## Not run: plot(w)

     ## Not run:
     im <- as.logical(matrix(scan("myfile"), nrow=128, ncol=128))
     # read in an arbitrary 128 x 128 digital image from text file
     rim <- im[, 128:1]
     # Assuming it was given in row-major order in the file
     # i.e. scanning left-to-right in rows from top-to-bottom,
     # the use of matrix() has effectively transposed rows & columns,
     # so to convert it to our format just reverse the column order.
     w <- owin(mask=rim)
     plot(w)
     # display it to check!

    ## End(Not run)

[Package spatstat version 1.63-3 Index]