Package 'gridpattern'

gridpattern: 'grid' Pattern Grobs

Description

Provides 'grid' grobs that fill in a user-defined area with various patterns. Includes enhanced versions of the geometric and image-based patterns originally contained in the 'ggpattern' package as well as original 'pch', 'polygon_tiling', 'regular_polygon', 'rose', 'text', 'wave', and 'weave' patterns plus support for custom user-defined patterns.

Package options

The following gridpattern options may be set globally via base::options():

ggpattern_array_funcs

Set custom “array” pattern functions.

ggpattern_geometry_funcs

Set custom “geometry” pattern functions.

ggpattern_res

Set custom raster image resolution (pixels per inch) for certain patterns.

ggpattern_use_R4.1_clipping

If TRUE use the grid clipping path feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation of the clipped pattern. If NULL try to guess an appropriate choice.

ggpattern_use_R4.1_features

If TRUE sets the default for all the other ⁠ggpattern_use_R4.1_*⁠ options arguments to TRUE. If FALSE sets them to FALSE.

ggpattern_use_R4.1_gradients

If TRUE use the grid gradient feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation of the gradient pattern. If NULL try to guess an appropriate choice.

ggpattern_use_R4.1_masks

If TRUE use the grid mask feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation of the masked pattern. If NULL try to guess an appropriate choice.

ggpattern_use_R4.1_patterns

If TRUE use the grid pattern feature introduced in R v4.1.0. Currently only used by a couple of examples.

Note to use the R v4.1.0 features one needs R be (at least) version 4.1 and not all graphic devices support any/all these features. See https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/definitions/definitions.html for more information on these features.

Author(s)

Maintainer: Trevor L. Davis [email protected] (ORCID)

Authors:

• Mike FC (Code/docs adapted from ggpattern)

Other contributors:

• ggplot2 authors (some utility functions copied from ggplot2) [contributor]

See Also

Useful links:

• https://trevorldavis.com/R/gridpattern/

• https://github.com/trevorld/gridpattern

• Report bugs at https://github.com/trevorld/gridpattern/issues

---

Mask grob using another grob to specify the (alpha) mask

Description

alphaMaskGrob() masks a grob using another grob to specify the (alpha) mask.

Usage

alphaMaskGrob(
  maskee,
  masker,
  use_R4.1_masks = getOption("ggpattern_use_R4.1_masks",
    getOption("ggpattern_use_R4.1_features")),
  png_device = NULL,
  res = getOption("ggpattern_res", 72),
  name = NULL,
  gp = gpar(),
  vp = NULL
)

Arguments

maskee	Grob to be masked
masker	Grob that defines masking region
use_R4.1_masks	If TRUE use the grid mask feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation. If NULL try to guess an appropriate choice. Note not all graphic devices support the grid mask feature.
png_device	“png” graphics device to save intermediate raster data with if use_R4.1_masks is FALSE. If NULL and suggested package ragg is available and versions are high enough we directly capture masked raster via ragg::agg_capture(). Otherwise we will use png_device (default ragg::agg_png() if available else grDevices::png()) and png::readPNG() to manually compute a masked raster.
res	Resolution of desired rasterGrob in pixels per inch if use_R4.1_masks is FALSE.
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).

Value

A grid grob

Examples

# May take more than 5 seconds on CRAN servers
  if (capabilities("png") && require("grid")) {
    maskee <- patternGrob("circle", gp = gpar(col = "black", fill = "yellow"),
                           spacing = 0.1, density = 0.5)
    angle <- seq(2 * pi / 4, by = 2 * pi / 6, length.out = 7)
    x_hex_outer <- 0.5 + 0.5 * cos(angle)
    y_hex_outer <- 0.5 + 0.5 * sin(angle)
    x_hex_inner <- 0.5 + 0.25 * cos(rev(angle))
    y_hex_inner <- 0.5 + 0.25 * sin(rev(angle))
    gp <- gpar(lwd = 0, col = NA, fill = "white")
    masker <- grid::pathGrob(x = c(x_hex_outer, x_hex_inner),
                             y = c(y_hex_outer, y_hex_inner),
                             id = rep(1:2, each = 7),
                             rule = "evenodd", gp = gp)
    masked <- alphaMaskGrob(maskee, masker, use_R4.1_masks = FALSE)
    grid.draw(masked)
  }
  if (capabilities("png") && require("grid")) {
    maskee_transparent <- rectGrob(gp = gpar(col = NA, fill = "blue"))
    gp <- gpar(lwd = 20, col = "black", fill = grDevices::rgb(0, 0, 0, 0.5))
    masker_transparent <- editGrob(masker, gp = gp)
    masked_transparent <- alphaMaskGrob(maskee_transparent,
                                        masker_transparent,
                                        use_R4.1_masks = FALSE)
    grid.newpage()
    grid.draw(masked_transparent)
  }

---

Clip grob using another grob to specify the clipping path

Description

clippingPathGrob() clips a grob using another grob to specify the clipping path

Usage

clippingPathGrob(
  clippee,
  clipper,
  use_R4.1_clipping = getOption("ggpattern_use_R4.1_clipping",
    getOption("ggpattern_use_R4.1_features")),
  png_device = NULL,
  res = getOption("ggpattern_res", 72),
  name = NULL,
  gp = gpar(),
  vp = NULL
)

Arguments

clippee	Grob to be clipped
clipper	Grob that defines clipping region
use_R4.1_clipping	If TRUE use the grid clipping path feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation. If NULL try to guess an appropriate choice. Note not all graphic devices support the grid clipping path feature and the grid clipping path feature does not nest.
png_device	“png” graphics device to save intermediate raster data with if use_R4.1_clipping is FALSE. If NULL and suggested package ragg is available and versions are high enough we directly capture clipped raster via ragg::agg_capture(). Otherwise we will use png_device (default ragg::agg_png() if available else grDevices::png()) and png::readPNG() to manually compute a clipped raster.
res	Resolution of desired rasterGrob in pixels per inch if use_R4.1_clipping is FALSE.
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).

Value

A grid grob

Examples

if (capabilities("png") && require("grid")) {
    clippee <- patternGrob("circle", gp = gpar(col = "black", fill = "yellow"),
                           spacing = 0.1, density = 0.5)
    angle <- seq(2 * pi / 4, by = 2 * pi / 6, length.out = 7)
    x_hex_outer <- 0.5 + 0.5 * cos(angle)
    y_hex_outer <- 0.5 + 0.5 * sin(angle)
    x_hex_inner <- 0.5 + 0.25 * cos(rev(angle))
    y_hex_inner <- 0.5 + 0.25 * sin(rev(angle))
    clipper <- grid::pathGrob(x = c(x_hex_outer, x_hex_inner),
                              y = c(y_hex_outer, y_hex_inner),
                              id = rep(1:2, each = 7),
                              rule = "evenodd")
    clipped <- clippingPathGrob(clippee, clipper, use_R4.1_clipping = FALSE)
    grid.newpage()
    grid.draw(clipped)
  }

---

Create patterned grobs by pattern name

Description

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.
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 or not.
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).

Format

An object of class character of length 19.

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.

image

Image array patterns. See grid.pattern_image() 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 https://trevorldavis.com/R/gridpattern/dev/articles/developing-patterns.html for more information.

Custom array-based patterns

See https://trevorldavis.com/R/gridpattern/dev/articles/developing-patterns.html for more information.

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.

See Also

https://coolbutuseless.github.io/package/ggpattern/index.html for more details on the ggpattern package.

Examples

print(names_pattern)
 # 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")
 }

---

Ambient patterned grobs

Description

grid.pattern_ambient() draws noise patterns onto the graphic device powered by the ambient package.

Usage

grid.pattern_ambient(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  type = "simplex",
  fill = gp$fill %||% "grey80",
  fill2 = "#4169E1",
  frequency = 0.01,
  interpolator = "quintic",
  fractal = switch(type, worley = "none", "fbm"),
  octaves = 3,
  lacunarity = 2,
  gain = 0.5,
  pertubation = "none",
  pertubation_amplitude = 1,
  value = "cell",
  distance_ind = c(1, 2),
  jitter = 0.45,
  res = getOption("ggpattern_res", 72),
  alpha = NA_real_,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
type	Either cubic, perlin, simplex, value, white, or worley
fill	Colour.
fill2	Second colour.
frequency	Determines the granularity of the features in the noise.
interpolator	How should values between sampled points be calculated? Either 'linear', 'hermite', or 'quintic' (default), ranging from lowest to highest quality.
fractal	The fractal type to use. Either 'none', 'fbm' (default), 'billow', or 'rigid-multi'. It is suggested that you experiment with the different types to get a feel for how they behaves.
octaves	The number of noise layers used to create the fractal noise. Ignored if fractal = 'none'. Defaults to 3.
lacunarity	The frequency multiplier between successive noise layers when building fractal noise. Ignored if fractal = 'none'. Defaults to 2.
gain	The relative strength between successive noise layers when building fractal noise. Ignored if fractal = 'none'. Defaults to 0.5.
pertubation	The pertubation to use. Either 'none' (default), 'normal', or 'fractal'. Defines the displacement (warping) of the noise, with 'normal' giving a smooth warping and 'fractal' giving a more eratic warping.
pertubation_amplitude	The maximal pertubation distance from the origin. Ignored if pertubation = 'none'. Defaults to 1.
value	The noise value to return. Either 'value' (default) A random value associated with the closest point 'distance' The distance to the closest point 'distance2' The distance to the nth closest point (n given by distance_ind[1]) 'distance2add' Addition of the distance to the nth and mth closest point given in distance_ind 'distance2sub' Substraction of the distance to the nth and mth closest point given in distance_ind 'distance2mul' Multiplication of the distance to the nth and mth closest point given in distance_ind 'distance2div' Division of the distance to the nth and mth closest point given in distance_ind
distance_ind	Reference to the nth and mth closest points that should be used when calculating value.
jitter	The maximum distance a point can move from its start position during sampling of cell points.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array pattern.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

For more information about the noise types please see the relevant ambient documentation: ambient::noise_cubic(), ambient::noise_perlin(), ambient::noise_simplex(), ambient::noise_value(), ambient::noise_white(), and ambient::noise_worley(). grid.pattern_plasma() provides an alternative noise pattern that depends on magick.

Examples

if (requireNamespace("ambient", quietly = TRUE)) {
   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))
   grid.pattern_ambient(x_hex, y_hex, fill = "green", fill2 = "blue")
 }
 if (requireNamespace("ambient")) {
   grid::grid.newpage()
   grid.pattern_ambient(x_hex, y_hex, fill = "green", fill2 = "blue", type = "cubic")
 }

---

Grobs with patterns powered by the aRtsy package

Description

grid.pattern_aRtsy() draws patterns powered by the aRtsy package. names_aRtsy() returns character vector of supported types.

Usage

grid.pattern_aRtsy(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  type = "strokes",
  fill = gp$fill %||% "grey80",
  alpha = gp$alpha %||% NA_real_,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

names_aRtsy()

Arguments

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.
...	Currently ignored
type	Name of pattern.
fill	Passed to the underlying aRtsy function's color / colors argument.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

https://koenderks.github.io/aRtsy/ for more information about the aRtsy package.

Examples

if (requireNamespace("aRtsy", quietly = TRUE)) {
  print(names_aRtsy())
}

# Make 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))
if (requireNamespace("aRtsy", quietly = TRUE) &&
    guess_has_R4.1_features("patterns")) {
  grid::grid.newpage()
  grid.pattern_aRtsy(x_hex, y_hex, type = "forest",
                     fill = c("black", "white", "grey"))
}

---

Circle patterned grobs

Description

grid.pattern_circle() draws a circle pattern onto the graphic device.

Usage

grid.pattern_circle(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  grid = "square",
  type = NULL,
  subtype = NULL,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Adjusts the repeating of certain aesthetics such as color. Can use any type in names_hex, names_square, or names_weave. See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported type arguments.
subtype	See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported subtype arguments.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

See grid.pattern_regular_polygon() for a more general case of this pattern.

Examples

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))
grid.pattern_circle(x_hex, y_hex, fill = c("blue", "yellow"), density = 0.5)
grid::grid.newpage()
grid.pattern_circle(x_hex, y_hex, density = 0.8, grid = "hex_circle",
                    gp = grid::gpar(fill = c("blue", "yellow", "red")))
grid::grid.newpage()
grid.pattern_circle(x_hex, y_hex, density = 1.2, grid = "hex_circle",
                    gp = grid::gpar(fill = c("blue", "yellow", "red")))
# using a "twill_zigzag" 'weave' pattern
grid::grid.newpage()
grid.pattern_circle(x_hex, y_hex, fill = "blue", density = 0.5, type = "twill_zigzag")

---

Crosshatch patterned grobs

Description

grid.pattern_crosshatch() draws a crosshatch pattern onto the graphic device.

Usage

grid.pattern_crosshatch(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  fill2 = fill,
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  grid = "square",
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
fill2	The fill colour for the “top” crosshatch lines.
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid.pattern_weave() which interweaves two sets of lines. For a single set of lines use grid.pattern_stripe().

Examples

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))
grid.pattern_crosshatch(x_hex, y_hex, colour = "black", fill = "blue",
                        fill2 = "yellow", density = 0.5)
grid::grid.newpage()
grid.pattern_crosshatch(x_hex, y_hex, density = 0.3,
                        gp = grid::gpar(col = "blue", fill = "yellow"))

---

Grobs with a simple fill pattern

Description

grid.pattern_fill() draws a simple fill pattern onto the graphics device.

Usage

grid.pattern_fill(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  fill = gp$fill %||% "grey80",
  alpha = gp$alpha %||% NA_real_,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored
fill	Fill colour(s) or grid::pattern() / gradient object(s).
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid::grid.polygon()

Examples

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))
grid.pattern_fill(x_hex, y_hex, fill = "blue")

if (guess_has_R4.1_features("patterns")) {
  grid::grid.newpage()
  stripe_fill <- patternFill("stripe", fill = c("red", "blue"))
  grid.pattern_fill(x_hex, y_hex, fill = stripe_fill)
}

---

Gradient patterned grobs

Description

grid.pattern_gradient() draws a gradient pattern onto the graphic device.

Usage

grid.pattern_gradient(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  fill = gp$fill %||% "grey80",
  fill2 = "#4169E1",
  orientation = "vertical",
  alpha = gp$alpha %||% NA_real_,
  use_R4.1_gradients = getOption("ggpattern_use_R4.1_gradients",
    getOption("ggpattern_use_R4.1_features")),
  aspect_ratio = 1,
  key_scale_factor = 1,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
fill	Colour.
fill2	Second colour.
orientation	vertical, horizontal, or radial.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
use_R4.1_gradients	Whether to use the gradient feature introduced in R v4.1 or use a rasterGrob approximation. Note not all graphic devices support the grid gradient feature.
aspect_ratio	Override aspect ratio.
key_scale_factor	Additional scale factor for legend.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array 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. If draw is TRUE then also draws to the graphic device as a side effect.

Examples

if (requireNamespace("magick") && capabilities("png")) {
   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))
   grid.pattern_gradient(x_hex, y_hex, fill = "green")
 }
 if (requireNamespace("magick") && capabilities("png")) {
   grid::grid.newpage()
   grid.pattern_gradient(x_hex, y_hex, fill = "green", orientation = "radial")
 }

---

Image patterned grobs

Description

grid.pattern_image() draws an image pattern onto the graphic device.

Usage

grid.pattern_image(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  filename = "",
  type = "fit",
  scale = 1,
  gravity = switch(type, tile = "southwest", "center"),
  filter = "lanczos",
  alpha = gp$alpha %||% NA_real_,
  aspect_ratio = 1,
  key_scale_factor = 1,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
filename	Image of filename or URL
type	Image scaling type
scale	Extra scaling
gravity	Position of image within area. magick::gravity_types() returns a vector of supported values.
filter	Filter to use when scaling. magick::filter_types() returns a vector of supported values.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
aspect_ratio	Override aspect ratio.
key_scale_factor	Additional scale factor for legend.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array 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).

Details

Here is a description of the type arguments:

expand

Scale the image beyond the bounding box and crop it such that the image fully covers the width and the height of the region.

fit

Scale the image such that either the width or the height of the image fits in the bounding box. Affected by gravity

none

Position a single image in the region without attempting to scale to the bounding box size. Affected by scale and gravity.

squish

Distort the image to cover the bounding box of the region.

tile

Repeat the image to cover the bounding box. Affected by tile.

Value

A grid grob object invisibly. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid.pattern_placeholder() is an image pattern that uses images downloaded from the internet. reset_image_cache() resets the image cache used by grid.pattern_image() and grid.pattern_placeholder().

Examples

# May emit a "CPU time > 2.5 times elapsed time" NOTE in a CRAN check
  if (requireNamespace("magick")) {
    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))
    logo_filename <- system.file("img", "Rlogo.png" , package = "png")
    grid.pattern_image(x_hex, y_hex, filename = logo_filename, type = "fit")
  }
  if (requireNamespace("magick")) {
    # "tile" `type` image pattern depends on `magick` functionality
    # which is not reliable across platforms
    grid::grid.newpage()
    try(grid.pattern_image(x_hex, y_hex, filename = logo_filename,
                           type = "tile"))
  }

---

Magick patterned grobs

Description

grid.pattern_magick() draws a imagemagick pattern onto the graphic device. names_magick, names_magick_intensity, and names_magick_stripe are character vectors of supported type values plus subsets for shaded intensity and stripes.

Usage

grid.pattern_magick(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  type = "hexagons",
  fill = "grey20",
  scale = 1,
  filter = "box",
  alpha = gp$alpha %||% NA_real_,
  aspect_ratio = 1,
  key_scale_factor = 1,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

names_magick

names_magick_intensity

names_magick_stripe

Arguments

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.
...	Currently ignored.
type	Magick pattern types. names_magick, names_magick_intensity, and names_magick_stripe are character vectors of supported type values plus subsets for shaded intensity and stripes.
fill	Fill colour
scale	Extra scaling
filter	Filter to use when scaling. magick::filter_types() returns a vector of supported values.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
aspect_ratio	Override aspect ratio.
key_scale_factor	Additional scale factor for legend.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array 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).

Format

An object of class character of length 54.

An object of class character of length 21.

An object of class character of length 19.

Value

A grid grob object invisibly. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

The imagemagick documentation http://www.imagemagick.org/script/formats.php for more information.

Examples

if (requireNamespace("magick")) {
    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))
    grid.pattern_magick(x_hex, y_hex, type="octagons", fill="blue", scale=2)
  }

  # supported magick pattern names
  print(names_magick)

---

Grobs without any pattern

Description

grid.pattern_none() draws nothing onto the graphic device.

Usage

grid.pattern_none(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid::grid.null()

Examples

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))
grid.pattern_none(x_hex, y_hex)

---

Plotting character patterned grobs

Description

grid.pattern_pch() draws a plotting character pattern onto the graphic device.

Usage

grid.pattern_pch(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  scale = 0.5,
  shape = 1L,
  grid = "square",
  type = NULL,
  subtype = NULL,
  rot = 0,
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
scale	For star polygons, multiplier (between 0 and 1) applied to exterior radius to get interior radius.
shape	An integer from 0 to 25 or NA. See graphics::points() for more details. Note we only support these shapes and do not support arbitrary ASCII / Unicode characters.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Adjusts the repeating of certain aesthetics such as color. Can use any type in names_hex, names_square, or names_weave. See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported type arguments.
subtype	See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported subtype arguments.
rot	Angle to rotate regular polygon (degrees, counter-clockwise).
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid.pattern_regular_polygon() which is used to implement this pattern.

Examples

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))
gp <- grid::gpar(col = "black", fill = "lightblue")

if (capabilities("png") || guess_has_R4.1_features("masks")) {
  # pch 0-6 are simple shapes with no fill
  grid.pattern_pch(x_hex, y_hex, shape = 0:6, gp = gp,
                   spacing = 0.1, density = 0.4, angle = 0)
}
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  # pch 7-14 are compound shapes with no fill
  grid::grid.newpage()
  grid.pattern_pch(x_hex, y_hex, shape = 7:14, gp = gp,
                   spacing = 0.1, density = 0.4, angle = 0)
}
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  # pch 15-20 are filled with 'col'
  grid::grid.newpage()
  grid.pattern_pch(x_hex, y_hex, shape = 15:20, gp = gp,
                   spacing = 0.1, density = 0.4, angle = 0)
}
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  # pch 21-25 are filled with 'fill'
  grid::grid.newpage()
  grid.pattern_pch(x_hex, y_hex, shape = 21:25, gp = gp,
                   spacing = 0.1, density = 0.4, angle = 0)
}
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  # using a 'basket' weave `type` with two shapes
  grid::grid.newpage()
  grid.pattern_pch(x_hex, y_hex, shape = c(1,4), gp = gp,
                   type = "basket",
                   spacing = 0.1, density = 0.4, angle = 0)
}

---

Placeholder image patterned grobs

Description

grid.pattern_placeholder() draws a placeholder image pattern onto the graphic device. names_placeholder are character vectors of supported placeholder types.

Usage

grid.pattern_placeholder(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  type = "bear",
  alpha = gp$alpha %||% NA_real_,
  aspect_ratio = 1,
  key_scale_factor = 1,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

names_placeholder

Arguments

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.
...	Currently ignored.
type	Image source. names_placeholder is a vector of supported values. If you would like only greyscale images append bw to the name.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
aspect_ratio	Override aspect ratio.
key_scale_factor	Additional scale factor for legend.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array 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).

Format

An object of class character of length 22.

Value

A grid grob object invisibly. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

reset_image_cache() resets the image cache used by grid.pattern_image() and grid.pattern_placeholder().

Examples

if (requireNamespace("magick")) {
    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))
    # requires internet connection to download from placeholder image websites
    try(grid.pattern_placeholder(x_hex, y_hex, type="bear"))
  }

  print(names_placeholder)

---

Plasma patterned grobs

Description

grid.pattern_plasma() draws a plasma pattern onto the graphic device.

Usage

grid.pattern_plasma(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  fill = gp$fill %||% "grey80",
  scale = 1,
  alpha = gp$alpha %||% NA_real_,
  aspect_ratio = 1,
  key_scale_factor = 1,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
fill	Colour.
scale	Extra scaling
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
aspect_ratio	Override aspect ratio.
key_scale_factor	Additional scale factor for legend.
res	Assumed resolution (in pixels per graphic device inch) to use when creating array 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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid.pattern_ambient() provides a noise pattern using the ambient package. Pseudorandom seeds for the plasma pattern may be set via magick::magick_set_seed().

Examples

if (requireNamespace("magick")) {
    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))
    grid.pattern_plasma(x_hex, y_hex, fill = "green")
  }

---

Polygon tiling patterned grobs

Description

grid.pattern_polygon_tiling() draws a specified polygon tiling pattern onto the graphic device. names_polygon_tiling lists all supported types.

Usage

grid.pattern_polygon_tiling(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  type = "square",
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

names_polygon_tiling

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
type	Name of polygon tiling to draw. See Details.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value). Not supported for all polygon tiling type.
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
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).

Format

An object of class character of length 36.

Details

grid.pattern_polygon_tiling() supports 1, 2, or 3 fill colors with the first colors (weakly) covering a larger area. Size of the pattern is controlled by spacing. We support the following polygon tiling types:

elongated_triangular

Creates an elongated triangular tiling made of squares and triangles.

herringbone

Creates a herringbone tiling made of rectangles.

hexagonal

Creates a hexagonal tiling made of hexagons.

pythagorean

Creates a Pythagorean tiling made of squares of two different sizes.

rhombille

Creates a rhombille tiling made of rhombi.

rhombitrihexagonal

Creates a rhombitrihexagonal tiling made out of dodecagons, hexagons, and squares.

snub_square

Creates a snub square tiling made of squares and triangles.

snub_trihexagonal

Creates a snub trihexagonal tiling made of hexagons and triangles.

square

Creates a square tiling made of squares.

tetrakis_square

Creates a tetrakis square tiling made of isosceles right triangles.

triangular

Creates a triangular tiling made of equilateral triangles.

trihexagonal

Creates a trihexagonal tiling made of hexagons and triangles.

truncated_square

Creates a truncated square tiling made of octagons and squares.

truncated_hexagonal

Creates a truncated hexagonal tiling made of dodecagons and triangles.

truncated_trihexagonal

Creates a truncated trihexagonal tiling made of hexagons, squares, and triangles.

⁠2*.2**.2*.2**⁠

Creates a polygon tiling made of rhombi.

⁠2**.3**.12*⁠

Creates a polygon tiling made of rhombi, triangles, and twelve-pointed stars.

⁠3.3.3.3**⁠

Creates a polygon tiling made of triangles.

⁠3.3*.3.3**⁠

Creates a regular (star) polygon tiling made of triangles and three-pointed stars.

⁠3.3.3.12*.3.3.12*⁠

Creates a regular (star) polygon tiling made of triangles and twelve-pointed stars.

⁠3.3.8*.3.4.3.8*⁠

Creates a regular (star) polygon tiling made of triangles, squares, and eight-pointed stars.

⁠3.3.8*.4**.8*⁠

Creates a regular (star) polygon tiling made of triangles, four-pointed stars, and eight-pointed stars.

⁠3.4.6.3.12*⁠

Creates a regular (star) polygon tiling made of triangles, squares, hexagons, and twelve-pointed stars.

⁠3.4.8.3.8*⁠

Creates a regular (star) polygon tiling made of triangles, squares, octagons, and eight-pointed stars.

⁠3.6*.6**⁠

Creates a regular (star) polygon tiling made of triangles and six-pointed stars.

⁠4.2*.4.2**⁠

Creates a polygon tiling made of squares and rhombi.

⁠4.4*.4**⁠

Creates a regular (star) polygon tiling made of squares and four-pointed stars.

⁠4.6.4*.6⁠

Creates a regular (star) polygon tiling made of squares, hexagons, and four-pointed stars.

⁠4.6*.4.6*.4.6*⁠

Creates a regular (star) polygon tiling made of squares and six-pointed stars.

⁠4.8*.4**.8*⁠

Creates a polygon tiling of squares and eight-pointed stars.

⁠6.6*.6.6*⁠

Creates a regular (star) polygon tiling made of hexagons and six-pointed stars.

⁠8.4*.8.4*⁠

Creates a regular (star) polygon tiling made of octagons and four-pointed stars.

⁠9.3.9.3*⁠

Creates a regular (star) polygon tiling made of triangles, nonagons, and three-pointed stars.

⁠12.3*.12.3*⁠

Creates a regular (star) polygon tiling made of dodecagons and three-pointed stars.

⁠12.12.4*⁠

Creates a regular (star) polygon tiling made of dodecagons and four-pointed stars.

⁠18.18.3*⁠

Creates a regular (star) polygon tiling made of eighteen-sided polygons and three-pointed stars.

Value

A grid grob object invisibly. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

The tiling vignette vignette("tiling", package = "gridpattern") for more information about these tilings as well as more examples of polygon tiling using the grid.pattern_regular_polygon() function.

Examples

print(names_polygon_tiling)

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))
gp1 <- grid::gpar(fill = "yellow", col = "black")
gp2 <- grid::gpar(fill = c("yellow", "red"), col = "black")
gp3 <- grid::gpar(fill = c("yellow", "red", "blue"), col = "black")

grid.pattern_polygon_tiling(x_hex, y_hex, type = "herringbone", gp = gp1)

grid::grid.newpage()
grid.pattern_polygon_tiling(x_hex, y_hex, type = "hexagonal",
                            spacing = 0.2, gp = gp3)

grid::grid.newpage()
grid.pattern_polygon_tiling(x_hex, y_hex, type = "pythagorean",
                            spacing = 0.2, gp = gp2)

grid::grid.newpage()
grid.pattern_polygon_tiling(x_hex, y_hex, type = "snub_trihexagonal",
                            spacing = 0.2, gp = gp3)

grid::grid.newpage()
grid.pattern_polygon_tiling(x_hex, y_hex, type = "rhombille",
                              spacing = 0.2, gp = gp3)

---

Regular polygon patterned grobs

Description

grid.pattern_regular_polygon() draws a regular polygon pattern onto the graphic device.

Usage

grid.pattern_regular_polygon(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  scale = 0.5,
  shape = "convex4",
  grid = "square",
  type = NULL,
  subtype = NULL,
  rot = 0,
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
scale	For star polygons, multiplier (between 0 and 1) applied to exterior radius to get interior radius.
shape	Either "convex" or "star" followed by the number of exterior vertices or alternatively "circle", "square", "null", "rhombille_rhombus", "tetrakis_left", or "tetrakis_right". For example "convex5" corresponds to a pentagon and "star6" corresponds to a six-pointed star. The "square" shape is larger than the "convex4" shape and is rotated an extra 45 degrees, it can be used to generate a multi-colored “checkers” effect when density is 1. The "null" shape is not drawn, it can be used to create holes within multiple-element patterns. The "rhombille_rhombus" shape draws a rhombus while the "tetrakis_left" or "tetrakis_right" shapes draw an isosceles right triangle. These latter three non-regular-polygon shapes are intended to help generate rhombille and tetrakis square tilings.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Adjusts the repeating of certain aesthetics such as color. Can use any type in names_hex, names_square, or names_weave. See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported type arguments.
subtype	See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported subtype arguments.
rot	Angle to rotate regular polygon (degrees, counter-clockwise).
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

grid.pattern_circle() for a special case of this pattern. The tiling vignette features more examples of regular polygon tiling using this function vignette("tiling", package = "gridpattern").

Examples

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))

# 'density', 'rot', and 'shape' are vectorized
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)

# checker pattern using "square" shape
grid::grid.newpage()
grid.pattern_regular_polygon(x_hex, y_hex, shape = "square",
                             colour = "transparent",
                             fill = c("black", "red", "blue", "yellow"),
                             angle = 0, density = 1.0, spacing = 0.2)

# checker pattern using the default "convex4" shape
grid::grid.newpage()
grid.pattern_regular_polygon(x_hex, y_hex, density = 1.0,
                             colour = "black", fill = "blue")

# using a "twill_zigzag" 'weave' pattern
grid::grid.newpage()
grid.pattern_regular_polygon(x_hex, y_hex, fill = c("blue", "yellow"),
                             shape = c("circle", "star8"),
                             density = c(0.5, 0.6), type = "twill_zigzag")

# hexagon tiling
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")

# triangle tiling
grid::grid.newpage()
grid.pattern_regular_polygon(x_hex, y_hex, fill = "green",
                             density = 1.0, spacing = 0.1,
                             shape = "convex3", grid = "hex")

---

Rose curve patterned grobs

Description

grid.pattern_rose() draws a rose curve pattern onto the graphic device.

Usage

grid.pattern_rose(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  frequency = 0.1,
  grid = "square",
  type = NULL,
  subtype = NULL,
  rot = 0,
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  use_R4.1_masks = getOption("ggpattern_use_R4.1_masks",
    getOption("ggpattern_use_R4.1_features")),
  png_device = NULL,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
frequency	The “angular frequency” parameter of the rose pattern.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Adjusts the repeating of certain aesthetics such as color. Can use any type in names_hex, names_square, or names_weave. See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported type arguments.
subtype	See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported subtype arguments.
rot	Angle to rotate rose (degrees, counter-clockwise).
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
use_R4.1_masks	If TRUE use the grid mask feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation. If NULL try to guess an appropriate choice. Note not all graphic devices support the grid mask feature.
png_device	“png” graphics device to save intermediate raster data with if use_R4.1_masks is FALSE. If NULL and suggested package ragg is available and versions are high enough we directly capture masked raster via ragg::agg_capture(). Otherwise we will use png_device (default ragg::agg_png() if available else grDevices::png()) and png::readPNG() to manually compute a masked raster.
res	Resolution of desired rasterGrob in pixels per inch if use_R4.1_masks is FALSE.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

See https://en.wikipedia.org/wiki/Rose_(mathematics) for more information.

Examples

if (capabilities("png") || guess_has_R4.1_features("masks")) {
    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))
    gp <- grid::gpar(fill = c("blue", "red", "yellow", "green"), col = "black")
    grid.pattern_rose(x_hex, y_hex,
                      spacing = 0.15, density = 0.5, angle = 0,
                      frequency = 1:4, gp = gp)
  }
  if (capabilities("png") || guess_has_R4.1_features("masks")) {
    grid::grid.newpage()
    grid.pattern_rose(x_hex, y_hex,
                      spacing = 0.15, density = 0.5, angle = 0,
                      frequency = 1/1:4, gp = gp)
  }
  if (capabilities("png") || guess_has_R4.1_features("masks")) {
    grid::grid.newpage()
    grid.pattern_rose(x_hex, y_hex,
                      spacing = 0.18, density = 0.5, angle = 0,
                      frequency = c(3/2, 7/3, 5/4, 3/7), gp = gp)
  }

---

Stripe patterned grobs

Description

grid.pattern_stripe() draws a stripe pattern onto the graphic device.

Usage

grid.pattern_stripe(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  grid = "square",
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

⁠[grid.pattern_crosshatch()]⁠ and ⁠[grid.pattern_weave()]⁠ for overlaying stripes.

Examples

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))
grid.pattern_stripe(x_hex, y_hex, colour = "black",
                    fill = c("red", "blue"), density = 0.4)

# Can alternatively use "gpar()" to specify colour and line attributes
grid::grid.newpage()
grid.pattern_stripe(x_hex, y_hex, density = 0.3,
                    gp = grid::gpar(col = "blue", fill = "yellow"))

---

Text character patterned grobs

Description

grid.pattern_text() draws a text character pattern onto the graphic device.

Usage

grid.pattern_text(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  angle = 30,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  scale = 0.5,
  shape = "X",
  grid = "square",
  type = NULL,
  subtype = NULL,
  rot = 0,
  alpha = gp$alpha %||% NA_real_,
  size = gp$fontsize %||% 12,
  fontfamily = gp$fontfamily %||% "sans",
  fontface = gp$fontface %||% "plain",
  use_R4.1_masks = getOption("ggpattern_use_R4.1_masks",
    getOption("ggpattern_use_R4.1_features")),
  png_device = NULL,
  res = getOption("ggpattern_res", 72),
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
angle	Rotation angle in degrees.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
scale	For star polygons, multiplier (between 0 and 1) applied to exterior radius to get interior radius.
shape	A character or expression vector. See label argument of grid::textGrob() for more details.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Adjusts the repeating of certain aesthetics such as color. Can use any type in names_hex, names_square, or names_weave. See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported type arguments.
subtype	See for pattern_hex(), pattern_square(), and pattern_weave() for more information about supported subtype arguments.
rot	Angle to rotate regular polygon (degrees, counter-clockwise).
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
size	Fontsize
fontfamily	The font family. See grid::gpar() for more details.
fontface	The font face. See grid::gpar() for more details.
use_R4.1_masks	If TRUE use the grid mask feature introduced in R v4.1.0. If FALSE do a rasterGrob approximation. If NULL try to guess an appropriate choice. Note not all graphic devices support the grid mask feature.
png_device	“png” graphics device to save intermediate raster data with if use_R4.1_masks is FALSE. If NULL and suggested package ragg is available and versions are high enough we directly capture masked raster via ragg::agg_capture(). Otherwise we will use png_device (default ragg::agg_png() if available else grDevices::png()) and png::readPNG() to manually compute a masked raster.
res	Resolution of desired rasterGrob in pixels per inch if use_R4.1_masks is FALSE.
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. If draw is TRUE then also draws to the graphic device as a side effect.

Examples

if (capabilities("png") &&
    gridpattern:::device_supports_unicode()) {
  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))

  playing_card_symbols <- c("\u2660", "\u2665", "\u2666", "\u2663")
  grid.pattern_text(x_hex, y_hex,
                   shape = playing_card_symbols,
                   colour = c("black", "red", "red", "black"),
                   size = 18, spacing = 0.1, angle = 0)
}

---

Wave patterned grobs

Description

grid.pattern_wave() draws a wave pattern onto the graphic device.

Usage

grid.pattern_wave(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  amplitude = 0.5 * spacing,
  frequency = 1/spacing,
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  grid = "square",
  type = "triangle",
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	Fill colour(s) or grid::pattern() / gradient object(s).
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for amplitude, frequency, spacing, xoffset, and yoffset parameters.
amplitude	Wave amplitude (in units units)
frequency	Linear frequency (in inverse units units)
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	Either “sine” or “triangle” (default).
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

Use grid.pattern_stripe() for straight lines instead of waves.

Examples

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))
grid::grid.newpage()
grid.pattern_wave(x_hex, y_hex, colour = "black", type = "sine",
                  fill = c("red", "blue"), density = 0.4,
                  spacing = 0.15, angle = 0,
                  amplitude = 0.05, frequency = 1 / 0.20)

# zig-zag pattern is a wave of `type` "triangle"
grid::grid.newpage()
grid.pattern_wave(x_hex, y_hex, colour = "black", type = "triangle",
                    fill = c("red", "blue"), density = 0.4,
                    spacing = 0.15, angle = 0, amplitude = 0.075)

---

Weave patterned grobs

Description

grid.pattern_weave() draws a weave pattern onto the graphic device.

Usage

grid.pattern_weave(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  colour = gp$col %||% "grey20",
  fill = gp$fill %||% "grey80",
  fill2 = fill,
  angle = 30,
  density = 0.2,
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  alpha = gp$alpha %||% NA_real_,
  linetype = gp$lty %||% 1,
  linewidth = size %||% gp$lwd %||% 1,
  size = NULL,
  grid = "square",
  type = "plain",
  subtype = NA,
  default.units = "npc",
  name = NULL,
  gp = gpar(),
  draw = TRUE,
  vp = NULL
)

Arguments

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.
...	Currently ignored.
colour	Stroke colour(s).
fill	The fill colour for the horizontal "weft" lines.
fill2	The fill colour for the vertical "warp" lines.
angle	Rotation angle in degrees.
density	Approx. fraction of area the pattern fills.
spacing	Spacing between repetitions of pattern (in units units).
xoffset	Shift pattern along x axis (in units units).
yoffset	Shift pattern along y axis (in units units).
units	grid::unit() units for spacing, xoffset, and yoffset parameters.
alpha	Alpha (between 0 and 1) or NA (default, preserves colors' alpha value).
linetype	Stroke linetype.
linewidth	Stroke linewidth.
size	For backwards compatibility can be used to set linewidth.
grid	Adjusts placement and density of certain graphical elements. "square" (default) is a square grid. "hex" is a hexagonal grid suitable for hexagonal and triangular tiling. "hex_circle" is a hexagonal grid suitable for circle packing. "elongated_triangle" is a grid used for the "elongated triangle" tiling.
type	The weave type. See pattern_weave() for more details.
subtype	The weave subtype. See pattern_weave() for more details.
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. If draw is TRUE then also draws to the graphic device as a side effect.

See Also

pattern_weave()

Examples

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))
gp <- grid::gpar(colour = "black", fill = "lightblue", lwd=0.5)

# Plain weave (default weave)
grid.pattern_weave(x_hex, y_hex, fill2 = "yellow",
                   gp = gp, spacing = 0.1, density = 0.3)

# Irregular matt weave
grid::grid.newpage()
grid.pattern_weave(x_hex, y_hex,  type = "matt_irregular",
                   fill2 = "yellow", gp = gp, spacing = 0.1, density = 0.3)

# Twill weave
grid::grid.newpage()
grid.pattern_weave(x_hex, y_hex, type = "twill",
                   fill2 = "yellow", gp = gp, spacing = 0.1, density = 0.3)

# Zig-zag twill
grid::grid.newpage()
grid.pattern_weave(x_hex, y_hex, type = "twill_zigzag",
                   fill2 = "yellow", gp = gp, spacing = 0.05, density = 0.7)

# Herringbone twill with density 1
grid::grid.newpage()
gp$col <- NA
grid.pattern_weave(x_hex, y_hex, type = "twill_herringbone",
                   fill2 = "yellow", gp = gp, spacing = 0.05, density = 1.0)

---