grid.pattern_image: 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
)

Value

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

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.

Examples

Run this code

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