`matrices.Rd`

These functions construct 4x4 matrices for transformations in the homogeneous coordinate system used by OpenGL, and translate vectors between homogeneous and Euclidean coordinates.

```
identityMatrix()
scaleMatrix(x, y, z)
translationMatrix(x, y, z)
rotationMatrix(angle, x, y, z, matrix)
asHomogeneous(x)
asEuclidean(x)
asHomogeneous2(x)
asEuclidean2(x)
scale3d(obj, x, y, z, ...)
translate3d(obj, x, y, z, ...)
rotate3d(obj, angle, x, y, z, matrix, ...)
transform3d(obj, matrix, ...)
```

- x, y, z, angle, matrix
See details

- obj
An object to be transformed

- ...
Additional parameters to be passed to methods

OpenGL uses homogeneous coordinates to handle perspective and affine
transformations. The homogeneous point `(x, y, z, w)`

corresponds
to the Euclidean point `(x/w, y/w, z/w)`

. The matrices produced by
the functions `scaleMatrix`

, `translationMatrix`

, and `rotationMatrix`

are to be left-multiplied by a row vector
of homogeneous coordinates; alternatively, the transpose of the result
can be right-multiplied by a column vector. The generic functions
`scale3d`

, `translate3d`

and `rotate3d`

apply these transformations
to the `obj`

argument. The `transform3d`

function is a synonym
for `rotate3d(obj, matrix = matrix)`

.

By default, it is assumed that `obj`

is a row vector
(or a matrix of row vectors) which will be multiplied on the right by
the corresponding matrix, but users may write methods for these generics
which operate differently. Methods are supplied for `mesh3d`

objects.

To compose transformations, use matrix multiplication. The effect is to apply the matrix on the left first, followed by the one on the right.

`identityMatrix`

returns an identity matrix.

`scaleMatrix`

scales each coordinate by the given factor. In Euclidean
coordinates, `(u, v, w)`

is transformed to `(x*u, y*v, z*w)`

.

`translationMatrix`

translates each coordinate by the given translation, i.e.
`(u, v, w)`

is transformed to `(u + x, v + y, w + z)`

.

`rotationMatrix`

can be called in three ways. With
arguments `angle, x, y, z`

it represents a rotation
of `angle`

radians about the axis
`x, y, z`

. If `matrix`

is a 3x3 rotation matrix,
it will be converted into the corresponding matrix in 4x4 homogeneous
coordinates. Finally, if a 4x4 matrix is given, it will be returned unchanged.
(The latter behaviour is used to allow `transform3d`

to act like a
generic function, even though it is not.)

Use `asHomogeneous(x)`

to convert the Euclidean vector `x`

to
homogeneous coordinates, and `asEuclidean(x)`

for the reverse transformation. These functions accept the following
inputs:

n x 3 matrices: rows are assumed to be Euclidean

n x 4 matrices: rows are assumed to be homogeneous

vectors of length 3n or 4n: assumed to be vectors concatenated. For the ambiguous case of vectors that are length 12n (so both 3n and 4n are possible), the assumption is that the conversion is necessary:

`asEuclidean`

assumes the vectors are homogeneous, and`asHomogeneous`

assumes the vectors are Euclidean.

Outputs are n x 4 or n x 3 matrices for `asHomogeneous`

and `asEuclidean`

respectively.

The functions `asHomogeneous2`

and `asEuclidean2`

act similarly, but they assume inputs are 3 x n or 4 x n
and outputs are in similar shapes.

`identityMatrix`

,
`scaleMatrix`

, `translationMatrix`

, and `rotationMatrix`

produce
a 4x4 matrix representing the requested transformation
in homogeneous coordinates.
`scale3d`

, `translate3d`

and `rotate3d`

transform the object
and produce a new object of the same class.

`par3d`

for a description of how RGL uses matrices in
rendering.

```
# A 90 degree rotation about the x axis:
rotationMatrix(pi/2, 1, 0, 0)
#> [,1] [,2] [,3] [,4]
#> [1,] 1 0.000000e+00 0.000000e+00 0
#> [2,] 0 6.123234e-17 -1.000000e+00 0
#> [3,] 0 1.000000e+00 6.123234e-17 0
#> [4,] 0 0.000000e+00 0.000000e+00 1
# Find what happens when you rotate (2, 0, 0) by 45 degrees about the y axis:
x <- asHomogeneous(c(2, 0, 0))
y <- x %*% rotationMatrix(pi/4, 0, 1, 0)
asEuclidean(y)
#> [,1] [,2] [,3]
#> [1,] 1.414214 0 1.414214
# or more simply...
rotate3d(c(2, 0, 0), pi/4, 0, 1, 0)
#> [,1] [,2] [,3]
#> [1,] 1.414214 0 1.414214
```