3D affine transformation matrices — transform3d • affiner

transform3d(), project3d(), reflect3d(), rotate3d(), scale3d(), shear3d(), and translate3d() create 3D affine transformation matrix objects.

Usage

transform3d(mat = diag(4L))

permute3d(permutation = c("xyz", "xzy", "yxz", "yzx", "zyx", "zxy"))

project3d(
  plane = as_plane3d("xy-plane"),
  ...,
  scale = 0,
  alpha = angle(45, "degrees")
)

reflect3d(plane = as_plane3d("xy-plane"), ...)

rotate3d(axis = as_coord3d("z-axis"), theta = angle(0), ...)

scale3d(x_scale = 1, y_scale = x_scale, z_scale = x_scale)

shear3d(
  xy_shear = 0,
  xz_shear = 0,
  yx_shear = 0,
  yz_shear = 0,
  zx_shear = 0,
  zy_shear = 0
)

translate3d(x = as_coord3d(0, 0, 0), ...)

Arguments

mat: A 4x4 matrix representing a post-multiplied affine transformation matrix. The last column must be equal to c(0, 0, 0, 1). If the last row is c(0, 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 3x3 matrix (such as a 3x3 post-multiplied 3D rotation matrix) we'll quietly add a final column/row equal to c(0, 0, 0, 1).
permutation: Either "xyz" (no permutation), "xzy" (permute y and z axes), "yxz" (permute x and y axes), "yzx" (x becomes z, y becomes x, z becomes y), "zxy" (x becomes y, y becomes z, z becomes x), "zyx" (permute x and z axes)
plane: A Plane3D object of length one representing the plane you wish to reflect across or project to or an object coercible to one using as_plane3d(plane, ...) such as "xy-plane", "xz-plane", or "yz-plane".
...: Passed to as_angle() or as_coord3d().
scale: Oblique projection foreshortening scale factor. A (degenerate) 0 value indicates an orthographic projection. A value of 0.5 is used by a “cabinet projection” while a value of 1.0 is used by a “cavalier projection”.
alpha: Oblique projection angle (the angle the third axis is projected going off at). An angle() object or one coercible to one with as_angle(alpha, ...). Popular angles are 45 degrees, 60 degrees, and arctangent(2) degrees.
axis: A Coord3D class object or one that can coerced to one by as_coord3d(axis, ...). The axis represents the axis to be rotated around.
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
z_scale: Scaling factor to apply to z coordinates
xy_shear: Shear factor: x = x + xy_shear * y + xz_shear * z
xz_shear: Shear factor: x = x + xy_shear * y + xz_shear * z
yx_shear: Shear factor: y = yx_shear * x + y + yz_shear * z
yz_shear: Shear factor: y = yx_shear * x + y + yz_shear * z
zx_shear: Shear factor: z = zx_shear * x + zy_shear * y + z
zy_shear: Shear factor: z = zx_shear * x + zy_shear * y + z
x: A Coord3D object of length one or an object coercible to one by as_coord3d(x, ...).

Value

A 4x4 post-multiplied affine transformation matrix with classes "transform3d" and "at_matrix"

Details

transform3d(): User supplied (post-multiplied) affine transformation matrix
scale3d(): Scale the x-coordinates and/or the y-coordinates and/or the z-coordinates by multiplicative scale factors.
shear3d(): Shear the x-coordinates and/or the y-coordinates and/or the z-coordinates using shear factors.
translate3d(): Translate the coordinates by a Coord3D class object parameter.

transform3d() 3D affine transformation matrix objects are meant to be post-multiplied and therefore should not be multiplied in reverse order. Note the Coord3D 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 3D 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_coord3d(x = sample(1:10, 3), y = sample(1:10, 3), z = sample(1:10, 3))

# {affiner} affine transformation matrices are post-multiplied
# and therefore should **not** go in reverse order
mat <- transform3d(diag(4L)) %*%
         rotate3d("z-axis", degrees(90)) %*%
         scale3d(1, 2, 1) %*%
         translate3d(x = -1, y = -1, z = -1)
p1 <- p$
  clone()$
  transform(mat)

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

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