affine_settings: Compute `grid` affine transformation feature viewports and transformation functions

Description

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

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

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.

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.

Examples

Run this code

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