transform3d: 3D affine transformation matrices

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

3D affine transformation matrices

Description

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, ...).

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

Value

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

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

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