Compute grid affine transformation feature viewports and transformation functions

affine_settings() computes grid group affine transformation feature viewport and transformation function settings given the (x,y) coordinates of the corners of the affine transformed "viewport" one wishes to draw in.

Usage

affine_settings(
  xy = data.frame(x = c(0, 0, 1, 1), y = c(1, 0, 0, 1)),
  unit = getOption("affiner_grid_unit", "inches")
)

Arguments

xy

An R object with named elements x and y representing the (x,y) coordinates of the affine transformed "viewport" one wishes to draw in. The (x,y) coordinates of the "viewport" should be in "upper left", "lower left", "lower right", and "upper right" order (this ordering should be from the perspective of before the "affine transformation" of the "viewport").

unit

Which grid::unit() to assume the xy "x" and "y" coordinates are expressed in.

Value

A named list with the following group affine transformation feature viewport and functions settings:

transform

An affine transformation function to pass to affineGrob() or useGrob(). If getRversion() is less than "4.2.0" will instead be NULL.

vp

A grid::viewport() object to pass to affineGrob() or useGrob().

sx

x-axis sx factor

flipX

whether the affine transformed "viewport" is "flipped" horizontally

x

x-coordinate for viewport

y

y-coordinate for viewport

width

Width of viewport

height

Height of viewport

default.units

Default grid::unit() for viewport

angle

angle for viewport

Usage in other packages

To avoid taking a dependency on affiner you may copy the source of affine_settings() into your own package under the permissive Unlicense. Either use usethis::use_standalone("trevorld/affiner", "standalone-affine-settings.r") or copy the file standalone-affine-settings.r into your R directory and add grid to the Imports of your DESCRIPTION file.

See also

Intended for use with affineGrob() and grid::useGrob(). See https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html for more information about the group affine transformation feature.

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"))
  settings <- affine_settings(xy = list(x = c(1/3, 0/3, 2/3, 3/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)
}

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