\name{owin}
\alias{owin}
\title{Create a Window}
\description{
  Creates an object of class \code{"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{
  \item{xrange}{\eqn{x} coordinate limits of enclosing box}
  \item{yrange}{\eqn{y} coordinate limits of enclosing box}
  \item{\dots}{Ignored.}
  \item{poly}{
    Optional. Polygonal boundary of window.
    Incompatible with \code{mask}.
  }
  \item{mask}{
    Optional. Logical matrix giving binary image of window.
    Incompatible with \code{poly}.
  }
  \item{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.
  }
  \item{xy}{
    Optional. List with components \code{x} and \code{y} specifying the
    pixel coordinates for \code{mask}.
  }
}
\value{
An object of class \code{"owin"} 
describing a window in the two-dimensional plane.
}
\details{
  In the \pkg{spatstat} library, a point pattern dataset must include
  information about the window of observation. This is represented by
  an object of class \code{"owin"}.
  See \code{\link{owin.object}} for an overview.

  To create a window in its own right, 
  users would normally invoke \code{owin},
  although sometimes \code{\link{as.owin}} may be convenient.

  A window may be rectangular, polygonal, or a mask (a binary image).
  \itemize{
    \item
    \bold{rectangular windows:}
    If only \code{xrange} and \code{yrange} are given, then
    the window will be rectangular, with its \eqn{x} and \eqn{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 \code{xrange=c(0,1)} and \code{yrange=c(0,1)}.
    \item
    \bold{polygonal windows:}
    If \code{poly} is given, then the window will be polygonal.
    \itemize{
      \item
      \emph{single polygon:}
      If \code{poly} is a matrix or data frame with two columns, or
      a structure with two component vectors \code{x} and \code{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 \emph{anticlockwise}.
      No vertex should be repeated (i.e. do not repeat the first
      vertex).
      \item
      \emph{multiple polygons or holes:}
      If \code{poly} is a list, each entry \code{poly[[i]]}
      of which is a matrix or data frame with two columns
      or a structure with
      two component vectors \code{x} and \code{y} of equal length,
      then the successive list members \code{poly[[i]]}
      are interpreted as separate polygons which together
      make up the boundary of the window.
      The vertices of each polygon must be listed \emph{anticlockwise}
      if the polygon is part of the external boundary,
      but \emph{clockwise}
      if the polygon is the boundary of a hole in the window.
      Again, do not repeat any vertex.
    }
    \item
    \bold{binary masks:}
    If \code{mask} is given, then the window will be a binary image.
    The argument \code{mask} should be a logical matrix
    such that \code{mask[i,j]} is \code{TRUE} if the point
    \code{(x[j],y[i])} belongs to the window, and \code{FALSE} if it
    does not. Note carefully that rows of \code{mask} correspond to the
    \eqn{y} coordinate, and columns to the \eqn{x} coordinate.
    Here \code{x} and \code{y} are vectors of \eqn{x} and \eqn{y}
    coordinates equally spaced over \code{xrange} and \code{yrange}
    respectively. The pixel coordinate vectors \code{x} and \code{y}
    may be specified explicitly using the argument \code{xy}, which
    should be a list containing components \code{x} and \code{y}.
    Alternatively there is a sensible default.
  }
  To create a window which is mathematically
  defined by inequalities in the Cartesian coordinates, 
  use \code{\link{raster.x}()} and \code{\link{raster.y}()}
  as in the examples below.

  Functions \code{\link{square}} and \code{\link{disc}}
  will create square and circular windows, respectively.
}
\seealso{
  \code{\link{square}},
  \code{\link{disc}},
  \code{\link{owin.object}},
  \code{\link{as.owin}},
  \code{\link{complement.owin}},
  \code{\link{ppp.object}},
  \code{\link{ppp}}
}
\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

  \dontrun{
  plot(c(0,1),c(0,1),type="n")
  bdry <- locator()
  # click the vertices of a polygon (anticlockwise)
  }
  \testonly{
  bdry <- list(x=c(0.1,0.3,0.7,0.4,0.2),
               y=c(0.1,0.1,0.5,0.7,0.3))
  }
  w <- owin(poly=bdry)
  \dontrun{plot(w)}
 
 \dontrun{
 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!
 }
}
\author{Adrian Baddeley
  \email{Adrian.Baddeley@csiro.au}
  \url{http://www.maths.uwa.edu.au/~adrian/}
  and Rolf Turner
  \email{r.turner@auckland.ac.nz}
}
\keyword{spatial}
\keyword{datagen}