Affine transformation grob

affineGrob() is a grid grob function to facilitate using the group affine transformation features introduced in R 4.2.

Usage

affineGrob(
  grob,
  vp_define = NULL,
  transform = NULL,
  vp_use = NULL,
  name = NULL,
  gp = grid::gpar(),
  vp = NULL
)

grid.affine(...)

Arguments

grob

A grid grob to perform affine transformations on. Passed to grid::defineGrob() as its src argument.

vp_define

grid::viewport() to define grid group in. Passed to grid::defineGrob() as its vp argument. This will cumulative with the current viewport and the vp argument (if any), if this cumulative viewport falls outside the graphics device drawing area this grob may be clipped on certain graphics devices.

transform

An affine transformation function. If NULL default to grid::viewportTransform(). Passed to grid::useGrob() as its transform argument.

vp_use

grid::viewport() passed to grid::useGrob() as its vp argument.

name

A character identifier (for grid).

gp

A grid::gpar() object.

vp

A grid::viewport() object (or NULL).

...

Passed to affineGrob()

Value

A grid::gTree() (grob) object of class "affine". As a side effect grid.affine() draws to the active graphics device.

Details

Not all graphics devices provided by grDevices or other R packages support the affine transformation feature introduced in R 4.2. If isTRUE(getRversion() >= '4.2.0') then the active graphics device should support this feature if isTRUE(grDevices::dev.capabilities()$transformations). In particular the following graphics devices should support the affine transformation feature:

• R's grDevices::pdf() device

• R's 'cairo' devices e.g. grDevices::cairo_pdf(), grDevices::png(type = 'cairo'), grDevices::svg(), grDevices::x11(type = 'cairo'), etc. If isTRUE(capabilities('cairo')) then R was compiled with support for the 'cairo' devices .

• R's 'quartz' devices (since R 4.3.0) e.g. grDevices::quartz(), grDevices::png(type = 'quartz'), etc. If isTRUE(capabilities('aqua')) then R was compiled with support for the 'quartz' devices (generally only TRUE on macOS systems).

• ragg's devices (since v1.3.0) e.g. ragg::agg_png(), ragg::agg_capture(), etc.

See also

See affine_settings() for computing good transform and vp_use settings. See https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html for more information about the group affine transformation feature. See isocubeGrob() which wraps this function to render isometric cubes.

Examples

if (require("grid")) {
  grob <- grobTree(rectGrob(gp = gpar(fill = "blue", col = NA)),
                   circleGrob(gp=gpar(fill="yellow", col = NA)),
                   textGrob("RSTATS", gp=gpar(fontsize=32)))
  grid.newpage()
  pushViewport(viewport(width=unit(4, "in"), height=unit(2, "in")))
  grid.draw(grob)
  popViewport()
}


if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  vp_define <- viewport(width=unit(2, "in"), height=unit(2, "in"))
  affine <- affineGrob(grob, vp_define=vp_define)
  grid.newpage()
  pushViewport(viewport(width=unit(4, "in"), height=unit(2, "in")))
  grid.draw(affine)
  popViewport()
}

if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  settings <- affine_settings(xy = list(x = c(3/3, 2/3, 0/3, 1/3),
                                        y = c(2/3, 1/3, 1/3, 2/3)),
                              unit = "snpc")
  affine <- affineGrob(grob,
                       vp_define = vp_define,
                       transform = settings$transform,
                       vp_use = settings$vp)
  grid.newpage()
  grid.draw(affine)
}