affineGrob: Affine transformation grob

In affiner: A Finer Way to Render 3D Illustrated Objects in 'grid' Using Affine Transformations

Affine transformation grob

Description

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

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.

Value

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

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

affiner documentation built on April 4, 2025, 4:42 a.m.