Homogeneous transformations

Enoki provides a number of convenience functions to construct 3D homogeneous coordinate transformations (rotations, translations, scales, perspective transformation matrices, etc.). To use them, include the following header file:

#include <enoki/transform.h>

Reference

template<typename Matrix, typename Vector3>
Matrix translate(Vector3 v)

Constructs a homogeneous coordinate transformation, which translates points by v.

template<typename Matrix, typename Vector3>
Matrix scale(Vector3 v)

Constructs a homogeneous coordinate transformation, which scales points by v.

template<typename Matrix, typename Vector3, typename Float>
Matrix rotate(Vector3 v, Float angle)

Constructs a homogeneous coordinate transformation, which rotates by angle radians around the axis v. The function requires v to be normalized.

template<typename Matrix>
auto transform_decompose(Matrix m)

Performs a polar decomposition of a non-perspective 4x4 homogeneous coordinate matrix and returns a tuple of

1. A positive definite 3x3 matrix containing an inhomogeneous scaling operation
2. A rotation quaternion
3. A 3D translation vector

This representation is helpful when animating keyframe animations.

The function also handles singular inputs m, in which case the rotation component is set to the identity quaternion and the scaling part simply copies the input matrix.

template<typename Matrix3, typename Quaternion, typename Vector3>
auto transform_compose(Matrix3 scale, Quaternion rotation, Vector3 translate)

This function composes a 4x4 homogeneous coordinate transformation from the given scale, rotation, and translation. It performs the reverse of transform_decompose.

template<typename Matrix3, typename Quaternion, typename Vector3>
auto transform_compose_inverse(Matrix3 scale, Quaternion rotation, Vector3 translate)

This function composes a 4x4 homogeneous inverse coordinate transformation from the given scale, rotation, and translation. It is the equivalent to (but more efficient than) the expression inverse(transform_compose(...)).

template<typename Matrix, typename Point3, typename Vector3>
Matrix look_at(Point3 origin, Point3, target, Vector3 up)

Constructs a homogeneous coordinate transformation, which translates to \(\mathrm{origin}\), maps the negative \(z\) axis to \(\mathrm{target}-\mathrm{origin}\) (normalized) and the positive \(y\) axis to \(\mathrm{up}\) (if orthogonal to \(\mathrm{target}-\mathrm{origin}\)). The algorithm performs Gram-Schmidt orthogonalization to ensure that the returned matrix is orthonormal.

template<typename Matrix, typename Float>
Matrix perspective(Float fov, Float near, Float far)

Constructs an OpenGL-compatible perspective projection matrix with the specified field of view (in radians) and near and far clip planes. The returned matrix performs the transformation

\[\begin{split}\begin{pmatrix} x\\y\\z\end{pmatrix} \mapsto \begin{pmatrix} -c\,x/z\\ -c\,x/z\\ \frac{2\,\mathrm{far}\,\mathrm{near}\,+\,z\,(\mathrm{far}+\mathrm{near})}{z\, (\mathrm{far}-\mathrm{near})} \end{pmatrix},\end{split}\]

where

\[c = \mathrm{cot}\!\left(0.5\, \textrm{fov}\right),\]

which maps \((0, 0, -\mathrm{near})^T\) to \((0, 0, -1)^T\) and \((0, 0, -\mathrm{far})^T\) to \((0, 0, 1)^T\).

template<typename Matrix, typename Float>
Matrix frustum(Float left, Float right, Float bottom, Float top, Float near, Float far)

Constructs an OpenGL-compatible perspective projection matrix. The provided parameters specify the intersection of the camera frustum with the near clipping plane. Specifically, the returned transformation maps \((\mathrm{left}, \mathrm{bottom}, -\mathrm{near})\) to \((-1, -1, -1)\) and \((\mathrm{right}, \mathrm{top}, -\mathrm{near})\) to \((1, 1, -1)\).

template<typename Matrix, typename Float>
Matrix ortho(Float left, Float right, Float bottom, Float top, Float near, Float far)

Constructs an OpenGL-compatible orthographic projection matrix. The provided parameters specify the intersection of the camera frustum with the near clipping plane. Specifically, the returned transformation maps \((\mathrm{left}, \mathrm{bottom}, -\mathrm{near})\) to \((-1, -1, -1)\) and \((\mathrm{right}, \mathrm{top}, -\mathrm{near})\) to \((1, 1, -1)\).