ThreeJS Matrix Transformations

Three.js encodes 3D transformations using matrices for translations (position), rotations, and scaling. Every Object3D instance has a matrix that records the location, rotation, and scale of the object. This page explains how to change the transformation of an item.

Convenience properties and matrixAutoUpdate

There are two ways to update the transformation of an object:

1. Change the object's location, quaternion, and scale attributes, and three.js will recalculate the object's matrix based on these changes:

object.position.copy( start_position );
object.quaternion.copy( quaternion );

The matrix will be automatically recalculated if the matrixAutoUpdate attribute is set to true by default. If the object is static, or if you want to control whether recalculation happens manually, you can get better performance by setting the attribute false:

object.matrixAutoUpdate = false;

After you've made any changes to the properties, manually update the matrix:

object.updateMatrix();

2. Directly alter the object's matrix. There are several methods for altering the matrix in the Matrix4 class:

object.matrix.setRotationFromQuaternion( quaternion );
object.matrix.setPosition( start_position );
object.matrixAutoUpdate = false;

It's important to remember that matrixAutoUpdate must be set to false in this scenario, and you shouldn't call updateMatrix. The call to updateMatrix will overwrite any manual modifications to the matrix, recalculating it from position, scale, and other factors.

Object and World Matrices

The matrix of an object maintains the object's transformation relative to its parent; you must use the object's Object3D.matrixWorld to retrieve the object's transformation in world coordinates.

You can request that the child object's matrixWorld be updated when either the parent or the child object's transformation changes by calling updateMatrixWorld ().

Rotation and Quaternion

Three.js has two representations for 3D rotations: Euler angles and Quaternions, as well as conversion tools between the two. Gimbal lock is a problem with Euler angles, where some configurations can lose a degree of freedom (preventing the object from being rotated about one axis). As a result, object rotations are always kept in the quaternion of the object.

When the useQuaternion property was set to false in previous versions of the library, the object's matrix was constructed using an Euler angle. This behavior is no longer recommended; instead, use the setRotationFromEuler function to update the quaternion.