2D affine transformation matrices — transform2d • affiner

transform2d(), project2d(), reflect2d(), rotate2d(), scale2d(), shear2d(), and translate2d() create 2D affine transformation matrix objects.

Usage

transform2d(mat = diag(3L))

permute2d(permutation = c("xy", "yx"))

project2d(line = as_line2d("x-axis"), ..., scale = 0)

reflect2d(line = as_line2d("x-axis"), ...)

rotate2d(theta = angle(0), ...)

scale2d(x_scale = 1, y_scale = x_scale)

shear2d(xy_shear = 0, yx_shear = 0)

translate2d(x = as_coord2d(0, 0), ...)

Arguments

mat: A 3x3 matrix representing a post-multiplied affine transformation matrix. The last column must be equal to c(0, 0, 1). If the last row is c(0, 0, 1) you may need to transpose it to convert it from a pre-multiplied affine transformation matrix to a post-multiplied one. If a 2x2 matrix (such as a 2x2 post-multiplied 2D rotation matrix) we'll quietly add a final column/row equal to c(0, 0, 1).
permutation: Either "xy" (no permutation) or "yx" (permute x and y axes)
line: A Line2D object of length one representing the line you with to reflect across or project to or an object coercible to one by as_line2d(line, ...) such as "x-axis" or "y-axis".
...: Passed to as_angle() or as_coord2d().
scale: Oblique projection scale factor. A degenerate 0 value indicates an orthogonal projection.
theta: An angle() object of length one or an object coercible to one by as_angle(theta, ...).
x_scale: Scaling factor to apply to x coordinates
y_scale: Scaling factor to apply to y coordinates
xy_shear: Horizontal shear factor: x = x + xy_shear * y
yx_shear: Vertical shear factor: y = yx_shear * x + y
x: A Coord2D object of length one or an object coercible to one by as_coord2d(x, ...).

Value

A 3x3 post-multiplied affine transformation matrix with classes "transform2d" and "at_matrix"

Details

transform2d(): User supplied (post-multiplied) affine transformation matrix
project2d(): Oblique vector projections onto a line parameterized by an oblique projection scale factor. A (degenerate) scale factor of zero results in an orthogonal projection.
reflect2d(): Reflections across a line. To "flip" across both the x-axis and the y-axis use scale2d(-1).
rotate2d(): Rotations around the origin parameterized by an angle().
scale2d(): Scale the x-coordinates and/or the y-coordinates by multiplicative scale factors.
shear2d(): Shear the x-coordinates and/or the y-coordinates using shear factors.
translate2d(): Translate the coordinates by a Coord2D class object parameter.

transform2d() 2D affine transformation matrix objects are meant to be post-multiplied and therefore should not be multiplied in reverse order. Note the Coord2D class object methods auto-pre-multiply affine transformations when "method chaining" so pre-multiplying affine transformation matrices to do a single cumulative transformation instead of a method chain of multiple transformations will not improve performance as much as it does in other R packages.

To convert a pre-multiplied 2D affine transformation matrix to a post-multiplied one simply compute its transpose using t(). To get an inverse transformation matrix from an existing transformation matrix that does the opposite transformations simply compute its inverse using solve().

Examples

p <- as_coord2d(x = sample(1:10, 3), y = sample(1:10, 3))

# {affiner} affine transformation matrices are post-multiplied
# and therefore should **not** go in reverse order
mat <- transform2d(diag(3)) %*%
         reflect2d(as_coord2d(-1, 1)) %*%
         rotate2d(90, "degrees") %*%
         scale2d(1, 2) %*%
         shear2d(0.5, 0.5) %*%
         translate2d(x = -1, y = -1)
p1 <- p$
  clone()$
  transform(mat)

# The equivalent result applying affine transformations via method chaining
p2 <- p$
  clone()$
  transform(diag(3L))$
  reflect(as_coord2d(-1, 1))$
  rotate(90, "degrees")$
  scale(1, 2)$
  shear(0.5, 0.5)$
  translate(x = -1, y = -1)

all.equal(p1, p2)
#> [1] TRUE