Image patterned grobs

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

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

Value

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

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.

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