grid.pattern_hatch: Heraldic color hatching patterned grobs

In gridpattern: 'grid' Pattern Grobs

Heraldic color hatching patterned grobs

Description

grid.pattern_hatch() draws a heraldic color hatching patterns onto the graphic device. names_hatch() returns a character vector of supported type values.

Usage

grid.pattern_hatch(
  x = c(0, 0, 1, 1),
  y = c(1, 0, 0, 1),
  id = 1L,
  ...,
  type = "gules",
  subtype = "combinatorial",
  colour = gp$col %||% "grey20",
  spacing = 0.05,
  xoffset = 0,
  yoffset = 0,
  units = "snpc",
  alpha = gp$alpha %||% NA_real_,
  lineend = gp$lineend %||% "round",
  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
)

names_hatch(
  subtype = c("combinatorial", "fox-davies", "goodman", "unicode"),
  accent = FALSE
)

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	A tincture or color name. names_hatch() lists supported values. Both traditional tincture names (e.g. "gules") and modern color equivalents (e.g. "red") are accepted. Matching is case-insensitive and ignores hyphens and spaces.
subtype	A string with one of "combinatorial" (default): an extension of the seven standard Petra Sancta hatchings with systematically derived mixed-color hatchings. "fox-davies": the hatchings in Fox-Davies' A Complete Guide to Heraldry. "goodman": the hatchings in David Goodman's Heraldic Tincture reference. "unicode": the hatchings used in Unicode character charts. The string is case-insensitive and hyphens and spaces are ignored.
colour	Stroke colour(s).
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).
lineend	Line end style, one of "round" (default), "butt", or "square".
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).
accent	If TRUE, return tincture names using their traditional accented spellings where applicable (e.g. "tenn\u00e9", "brun\u00e2tre"). Defaults to FALSE.

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_line() for single-direction lines, grid.pattern_crosshatch() for perpendicular lines. vignette("hatching", package = "gridpattern") for a visual overview of all subtypes. https://en.wikisource.org/wiki/A_Complete_Guide_to_Heraldry/Chapter_7#74 for Fox-Davies' A Complete Guide to Heraldry. https://david.goodman.graphics/portfolio/item/crests-heraldry-and-coats-of-arms/ for David Goodman's Heraldic Tincture reference.

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))
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  grid::grid.newpage()
  grid.pattern_hatch(x_hex, y_hex, type = "azure", colour = "blue")
}
if (capabilities("png") || guess_has_R4.1_features("masks")) {
  grid::grid.newpage()
  grid.pattern_hatch(x_hex, y_hex, type = "cendree", colour = "grey", spacing = 0.1)
}
print(names_hatch())
print(names_hatch("fox-davies"))
print(names_hatch("goodman"))
print(names_hatch("unicode"))

gridpattern documentation built on June 23, 2026, 5:08 p.m.