Create patterned grobs by pattern name

grid.pattern() draws patterned shapes onto the graphic device. patternGrob() returns the grid grob objects. names_pattern is a character vector of builtin patterns.

Usage

grid.pattern(
  pattern = "stripe",
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  legend = FALSE,
  prefix = "pattern_",
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

names_pattern

patternGrob(
  pattern = "stripe",
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  legend = FALSE,
  prefix = "pattern_",
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

pattern

Name of pattern. See Details section for a list of supported patterns. Builtin patterns may also be referred to by their qualified name e.g. "gridpattern::stripe" and custom patterns registered by packages by "pkg::name". A qualified name "pkg::name" (or a bare name preferred to a pattern of {pkg}, see prefer_pattern()) loads {pkg}'s namespace (if installed and not yet loaded) so it may register its patterns (like pkg::fn does). See register_pattern() for more information.

x

A numeric vector or unit object specifying x-locations of the pattern boundary.

y

A numeric vector or unit object specifying y-locations of the pattern boundary.

id

A numeric vector used to separate locations in x, y into multiple boundaries. All locations within the same id belong to the same boundary.

...

Pattern parameters.

legend

Whether this is intended to be drawn in a legend (key) or not. Either a logical value or a non-negative number:

FALSE or 0: Not a legend key (the default).
TRUE or 1: A legend key drawn at the scale of the key.
A positive number s: A legend key showing (the centre of) the pattern as it would be drawn in an area s times the width and height of the key i.e. the pattern is drawn in a centred viewport s times larger than the key (and clipped to the boundary). Relative lengths such as “snpc” spacings and offsets are then s times larger relative to the key while absolute lengths such as line widths, font sizes, “cm” units, and (a user-set) pattern_res are unchanged (the default pattern_res is s times larger so array patterns resemble the plot panels). This is what {ggpattern} uses so its legend keys resemble its plot panels.

A numeric legend key is also zoomed by the pattern_key_scale_factor parameter (default 1): the viewport is legend * pattern_key_scale_factor times larger than the key and pattern_spacing, pattern_xoffset, and pattern_yoffset are multiplied by pattern_key_scale_factor if pattern_units isn't “snpc”. A logical legend isn't zoomed by pattern_key_scale_factor (the caller zooms it if desired, as {ggpattern} 1.3.1 and earlier do) so TRUE and 1 differ if it isn't 1 (although the "magick" pattern scales its image by it either way). Pattern functions are always passed a logical legend value.

prefix

Prefix to prepend to the name of each of the pattern parameters in .... For compatibility with ggpattern most underlying functions assume parameters beginning with pattern_.

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.

draw

A logical value indicating whether graphics output should be produced.

vp

A Grid viewport object (or NULL).

Value

A grid grob object (invisibly in the case of grid.pattern()). If draw is TRUE then grid.pattern() also draws to the graphic device as a side effect.

Details

Here is a list of the various patterns supported:

ambient: Noise array patterns onto the graphic device powered by the ambient package. See grid.pattern_ambient() for more information.
aRtsy: Patterns powered by the aRtsy package. See grid.pattern_aRtsy() for more information.
circle: Circle geometry patterns. See grid.pattern_circle() for more information.
crosshatch: Crosshatch geometry patterns. See grid.pattern_crosshatch() for more information.
gradient: Gradient array/geometry patterns. See grid.pattern_gradient() for more information.
hatch: Heraldic hatching patterns. See grid.pattern_hatch() for more information.
image: Image array patterns. See grid.pattern_image() for more information.
line: Line geometry patterns. See grid.pattern_line() for more information.
magick: imagemagick array patterns. See grid.pattern_magick() for more information.
none: Does nothing. See grid::grid.null() for more information.
pch: Plotting character geometry patterns. See grid.pattern_pch() for more information.
placeholder: Placeholder image array patterns. See grid.pattern_placeholder() for more information.
plasma: Plasma array patterns. See grid.pattern_plasma() for more information.
polygon_tiling: Polygon tiling patterns. See grid.pattern_polygon_tiling() for more information.
regular_polygon: Regular polygon patterns. See grid.pattern_regular_polygon() for more information.
rose: Rose array/geometry patterns. See grid.pattern_rose() for more information.
stripe: Stripe geometry patterns. See grid.pattern_stripe() for more information.
text: Text array/geometry patterns. See grid.pattern_text() for more information.
wave: Wave geometry patterns. See grid.pattern_wave() for more information.
weave: Weave geometry patterns. See grid.pattern_weave() for more information.
Custom geometry-based patterns: See register_pattern() and the “Developing Patterns” vignette vignette("developing-patterns", package = "gridpattern") for more information.
Custom array-based patterns: See register_pattern() and the “Developing Patterns” vignette vignette("developing-patterns", package = "gridpattern") for more information.

Examples

 print(names_pattern)
#>  [1] "ambient"         "aRtsy"           "circle"          "crosshatch"     
#>  [5] "fill"            "gradient"        "hatch"           "image"          
#>  [9] "line"            "magick"          "none"            "pch"            
#> [13] "placeholder"     "plasma"          "polygon_tiling"  "regular_polygon"
#> [17] "rose"            "stripe"          "text"            "wave"           
#> [21] "weave"          
 # May take more than 5 seconds on CRAN servers
 x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
 y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))

 # geometry-based patterns
 # 'stripe' pattern
 grid::grid.newpage()
 grid.pattern("stripe", x_hex, y_hex,
              colour="black", fill=c("yellow", "blue"), density = 0.5)


 # Can alternatively use "gpar()" to specify colour and line attributes
 grid::grid.newpage()
 grid.pattern("stripe", x_hex, y_hex,
              gp = grid::gpar(col="blue", fill="red", lwd=2))


 # 'weave' pattern
 grid::grid.newpage()
 grid.pattern("weave", x_hex, y_hex, type = "satin",
              colour = "black", fill = "lightblue", fill2 =  "yellow",
              density = 0.3)


 # 'regular_polygon' pattern
 grid::grid.newpage()
 grid.pattern_regular_polygon(x_hex, y_hex, colour = "black",
                              fill = c("blue", "yellow", "red"),
                              shape = c("convex4", "star8", "circle"),
                              density = c(0.45, 0.42, 0.4),
                              spacing = 0.08, angle = 0)


 # can be used to achieve a variety of 'tiling' effects
 grid::grid.newpage()
 grid.pattern_regular_polygon(x_hex, y_hex, color = "transparent",
                              fill = c("white", "grey", "black"),
                              density = 1.0, spacing = 0.1,
                              shape = "convex6", grid = "hex")

 if (suppressPackageStartupMessages(requireNamespace("magick", quietly = TRUE))) {
   # array-based patterns
   # 'image' pattern
   logo_filename <- system.file("img", "Rlogo.png" , package="png")
   grid::grid.newpage()
   grid.pattern("image", x_hex, y_hex, filename=logo_filename, type="fit")
 }

 if (suppressPackageStartupMessages(requireNamespace("magick", quietly = TRUE))) {
   # 'plasma' pattern
   grid::grid.newpage()
   grid.pattern("plasma", x_hex, y_hex, fill="green")
 }

Usage

Arguments

Value

Details

See also

Examples