grid.path {grid} | R Documentation

## Draw a Path

### Description

These functions create and draw one or more paths. The final point of a path will automatically be connected to the initial point.

### Usage

    pathGrob(x, y,
             id=NULL, id.lengths=NULL,
             pathId=NULL, pathId.lengths=NULL,
             rule="winding",
             default.units="npc",
             name=NULL, gp=gpar(), vp=NULL)
    grid.path(...)

### Arguments

`x` | A numeric vector or unit object specifying x-locations.
`y` | A numeric vector or unit object specifying y-locations.
`id` | A numeric vector used to separate locations in `x` and `y` into sub-paths. All locations with the same `id` belong to the same sub-path.
`id.lengths` | A numeric vector used to separate locations in `x` and `y` into sub-paths. Specifies consecutive blocks of locations which make up separate sub-paths.
`pathId` | A numeric vector used to separate locations in `x` and `y` into distinct paths. All locations with the same `pathId` belong to the same path.
`pathId.lengths` | A numeric vector used to separate locations in `x` and `y` into paths. Specifies consecutive blocks of locations which make up separate paths.
`rule` | A character value specifying the fill rule: either `"winding"` or `"evenodd"`.
`default.units` | A string indicating the default units to use if `x` or `y` are only given as numeric vectors.
`name` | A character identifier.
`gp` | An object of class `gpar`, typically the output from a call to the function `gpar`. This is basically a list of graphical parameter settings.
`vp` | A Grid viewport object (or NULL).
`...` | Arguments passed to `pathGrob()`.

### Details

Both functions create a path grob (a graphical object describing a path), but only `grid.path` draws the path (and then only if `draw` is `TRUE`).

A path is like a polygon except that the former can contain holes, as interpreted by the fill rule; these fill a region if the path border encircles it an odd or non-zero number of times, respectively.

Not all graphics devices support this function: for example `xfig` and `pictex` do not.

### Value

A grob object.

### Author(s)

Paul Murrell

### See Also

Grid, `viewport`

### Examples

    pathSample <- function(x, y, rule, gp = gpar()) {
        if (is.na(rule))
            grid.path(x, y, id = rep(1:2, each = 4), gp = gp)
        else
            grid.path(x, y, id = rep(1:2, each = 4), rule = rule, gp = gp)
        if (!is.na(rule))
            grid.text(paste("Rule:", rule), y = 0, just = "bottom")
    }

    pathTriplet <- function(x, y, title) {
        pushViewport(viewport(height = 0.9, layout = grid.layout(1, 3),
                              gp = gpar(cex = .7)))
        grid.rect(y = 1, height = unit(1, "char"), just = "top",
                  gp = gpar(col = NA, fill = "grey"))
        grid.text(title, y = 1, just = "top")
        pushViewport(viewport(layout.pos.col = 1))
        pathSample(x, y, rule = "winding",
                   gp = gpar(fill = "grey"))
        popViewport()
        pushViewport(viewport(layout.pos.col = 2))
        pathSample(x, y, rule = "evenodd",
                   gp = gpar(fill = "grey"))
        popViewport()
        pushViewport(viewport(layout.pos.col = 3))
        pathSample(x, y, rule = NA)
        popViewport()
        popViewport()
    }

    pathTest <- function() {
        grid.newpage()
        pushViewport(viewport(layout = grid.layout(5, 1)))
        pushViewport(viewport(layout.pos.row = 1))
        pathTriplet(c(.1, .1, .9, .9, .2, .2, .8, .8),
                    c(.1, .9, .9, .1, .2, .8, .8, .2),
                    "Nested rectangles, both clockwise")
        popViewport()
        pushViewport(viewport(layout.pos.row = 2))
        pathTriplet(c(.1, .1, .9, .9, .2, .8, .8, .2),
                    c(.1, .9, .9, .1, .2, .2, .8, .8),
                    "Nested rectangles, outer clockwise, inner anti-clockwise")
        popViewport()
        pushViewport(viewport(layout.pos.row = 3))
        pathTriplet(c(.1, .1, .4, .4, .6, .9, .9, .6),
                    c(.1, .4, .4, .1, .6, .6, .9, .9),
                    "Disjoint rectangles")
        popViewport()
        pushViewport(viewport(layout.pos.row = 4))
        pathTriplet(c(.1, .1, .6, .6, .4, .4, .9, .9),
                    c(.1, .6, .6, .1, .4, .9, .9, .4),
                    "Overlapping rectangles, both clockwise")
        popViewport()
        pushViewport(viewport(layout.pos.row = 5))
        pathTriplet(c(.1, .1, .6, .6, .4, .9, .9, .4),
                    c(.1, .6, .6, .1, .4, .4, .9, .9),
                    "Overlapping rectangles, one clockwise, other anti-clockwise")
        popViewport()
        popViewport()
    }

    pathTest()

    # Drawing multiple paths at once
    holed_rect <- cbind(c(.15, .15, -.15, -.15, .1, .1, -.1, -.1),
                        c(.15, -.15, -.15, .15, .1, -.1, -.1, .1))
    holed_rects <- rbind(
        holed_rect + matrix(c(.7, .2), nrow = 8, ncol = 2, byrow = TRUE),
        holed_rect + matrix(c(.7, .8), nrow = 8, ncol = 2, byrow = TRUE),
        holed_rect + matrix(c(.2, .5), nrow = 8, ncol = 2, byrow = TRUE)
    )
    grid.newpage()
    grid.path(x = holed_rects[, 1], y = holed_rects[, 2],
              id = rep(1:6, each = 4), pathId = rep(1:3, each = 8),
              gp = gpar(fill = c('red', 'blue', 'green')),
              rule = 'evenodd')

    # Not specifying pathId will treat all points as part of the same path, thus
    # having same fill
    grid.newpage()
    grid.path(x = holed_rects[, 1], y = holed_rects[, 2],
              id = rep(1:6, each = 4),
              gp = gpar(fill = c('red', 'blue', 'green')),
              rule = 'evenodd')

[Package grid version 3.6.0 Index]