The R Project SVN R

Rev

Rev 61168 | Rev 79580 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
52406 murrell 1 
% File src/library/graphics/man/path.Rd
2 
% Part of the R package, http://www.R-project.org
59039 ripley 3 
% Copyright 1995-2011 R Core Team
52406 murrell 4 
% Distributed under GPL 2 or later
5 
 
6 
\name{polypath}
56186 murdoch 7 
\alias{polypath}
52406 murrell 8 
\title{Path Drawing}
9 
\description{
10 
  \code{path} draws a path whose vertices are
11 
  given in \code{x} and \code{y}.
12 
}
13 
\usage{
61433 ripley 14 
polypath(x, y = NULL,
52406 murrell 15 
         border = NULL, col = NA, lty = par("lty"),
16 
         rule = "winding", \dots)
17 
}
18 
\arguments{
61168 ripley 19 
  \item{x, y}{vectors containing the coordinates of the vertices
52406 murrell 20 
    of the path.}
21 
   \item{col}{the color for filling the path. The default,
22 
     \code{NA}, is to leave paths unfilled, unless \code{density} is
23 
     specified.  (For back-compatibility, \code{NULL} is equivalent to
24 
     \code{NA}.)  If \code{density} is specified with a positive value
25 
     this gives the color of the shading lines.}
26 
  \item{border}{the color to draw the border.  The default, \code{NULL},
27 
    means to use \code{\link{par}("fg")}.  Use \code{border = NA} to
28 
    omit borders.
61433 ripley 29 
 
52406 murrell 30 
    For compatibility with S, \code{border} can also be logical, in
31 
    which case \code{FALSE} is equivalent to \code{NA} (borders omitted)
32 
    and \code{TRUE} is equivalent to \code{NULL} (use the foreground colour),
33 
  }
34 
  \item{lty}{the line type to be used, as in \code{\link{par}}.}
35 
  \item{rule}{character value specifying the path fill mode: either
61433 ripley 36 
    \code{"winding"} or \code{"evenodd"}.}
56113 ripley 37 
  \item{\dots}{\link{graphical parameters} such as \code{xpd}, \code{lend},
52406 murrell 38 
    \code{ljoin} and \code{lmitre} can be given as arguments.}
39 
}
40 
\details{
41 
  The coordinates can be passed in a plotting structure
42 
  (a list with \code{x} and \code{y} components), a two-column matrix,
43 
  \dots.  See \code{\link{xy.coords}}.
44 
 
45 
  It is assumed that the path is to be closed by joining the last point to
46 
  the first point.
61433 ripley 47 
 
52406 murrell 48 
  The coordinates can contain missing values.  The behaviour is similar
56846 ripley 49 
  to that of \code{\link{polygon}}, except that instead of breaking a
50 
  polygon into several polygons, \code{NA} values break the path into
51 
  several sub-paths (including closing the last point to the first point
52 
  in each sub-path).  See the examples below.
52406 murrell 53 
 
54 
  The distinction between a path and a polygon is that the former
55 
  can contain holes, as interpreted by the fill rule; these fill a region if
56 
  the path border encircles it an odd or non-zero number of times,
57 
  respectively.
61433 ripley 58 
 
52406 murrell 59 
  Hatched shading (as implemented for \code{polygon()}) is not
60 
  (currently) supported.
61433 ripley 61 
 
56846 ripley 62 
  Not all graphics devices support this function: for example
63 
  \code{xfig} and \code{pictex} do not.
52406 murrell 64 
}
65 
\references{
66 
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
67 
  \emph{The New S Language}.
68 
  Wadsworth & Brooks/Cole.
69 
 
70 
  Murrell, P. (2005) \emph{R Graphics}. Chapman & Hall/CRC Press.
71 
}
72 
\seealso{
73 
  \code{\link{segments}} for even more flexibility, \code{\link{lines}},
74 
  \code{\link{rect}}, \code{\link{box}}, \code{\link{polygon}}.
75 
 
76 
  \code{\link{par}} for how to specify colors.
77 
}
78 
\examples{
56280 ripley 79 
plotPath <- function(x, y, col = "grey", rule = "winding") {
52406 murrell 80 
    plot.new()
56280 ripley 81 
    plot.window(range(x, na.rm = TRUE), range(y, na.rm = TRUE))
82 
    polypath(x, y, col = col, rule = rule)
52406 murrell 83 
    if (!is.na(col))
56280 ripley 84 
        mtext(paste("Rule:", rule), side = 1, line = 0)
52406 murrell 85 
}
86 
 
87 
plotRules <- function(x, y, title) {
88 
    plotPath(x, y)
56280 ripley 89 
    plotPath(x, y, rule = "evenodd")
90 
    mtext(title, side = 3, line = 0)
91 
    plotPath(x, y, col = NA)
52406 murrell 92 
}
93 
 
56280 ripley 94 
op <- par(mfrow = c(5, 3), mar = c(2, 1, 1, 1))
52406 murrell 95 
 
96 
plotRules(c(.1, .1, .9, .9, NA, .2, .2, .8, .8),
97 
          c(.1, .9, .9, .1, NA, .2, .8, .8, .2),
56280 ripley 98 
          "Nested rectangles, both clockwise")
99 
plotRules(c(.1, .1, .9, .9, NA, .2, .8, .8, .2),
100 
          c(.1, .9, .9, .1, NA, .2, .2, .8, .8),
101 
          "Nested rectangles, outer clockwise, inner anti-clockwise")
102 
plotRules(c(.1, .1, .4, .4, NA, .6, .9, .9, .6),
103 
          c(.1, .4, .4, .1, NA, .6, .6, .9, .9),
104 
          "Disjoint rectangles")
105 
plotRules(c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
106 
          c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
107 
          "Overlapping rectangles, both clockwise")
108 
plotRules(c(.1, .1, .6, .6, NA, .4, .9, .9, .4),
109 
          c(.1, .6, .6, .1, NA, .4, .4, .9, .9),
110 
          "Overlapping rectangles, one clockwise, other anti-clockwise")
52406 murrell 111 
 
112 
par(op)
113 
}
114 
\keyword{aplot}