Matrix Transformations in Three.js

In Three.js, matrices are used to encode 3D transformations—including translations (position), rotations, and scaling. Every Object3D instance has a matrix property that stores its transformation state. Understanding how to work with these matrices is essential for precise control of objects in a 3D scene.

Updating Transformations

There are two main ways to update an object’s transformation:

1. Using Convenience Properties

You can modify the object’s position, quaternion, and scale directly. By default, the matrixAutoUpdate property is set to true, which means Three.js will automatically recompute the object’s matrix from these values.

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

If the object is static or you want more control, you can set matrixAutoUpdate = false and manually trigger updates:

object.matrixAutoUpdate = false;
object.updateMatrix();

This approach can offer better performance in certain cases.

2. Modifying the Matrix Directly

You can also edit the object’s matrix directly using methods from the Matrix4 class:

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

⚠️ Important: When working this way, keep matrixAutoUpdate set to false, and do not call updateMatrix(). Calling it would overwrite your manual matrix edits.

Object and World Matrices

An object’s matrix represents its transformation relative to its parent. To obtain an object’s world transformation, use its matrixWorld.

Whenever the transformation of an object or its parent changes, you can refresh the world matrix:

object.updateMatrixWorld();

You can also apply transformations directly with:

object.applyMatrix4(matrix);

Note: This method internally uses Matrix4.decompose(). Not all matrices are decomposable—particularly in cases like non-uniform scaling in parent objects—so use with caution.

Rotation and Quaternions

Three.js supports two ways to represent rotations:

Euler angles (yaw, pitch, roll)
Quaternions

While Euler angles are intuitive, they suffer from gimbal lock, a condition where one axis of rotation becomes “locked.” To avoid this, Three.js internally stores object rotations in quaternions.

If you prefer working with Euler angles, use:

object.setRotationFromEuler(euler);

This updates the quaternion automatically. Previous versions of Three.js included a useQuaternion property, but this is now deprecated.

Summary

Use position, quaternion, and scale for easy transformations.
Disable matrixAutoUpdate for manual control.
World transformations require updateMatrixWorld().
Prefer quaternions over Euler angles to avoid gimbal lock.
Use setRotationFromEuler() to convert safely between the two.

By mastering these techniques, you can take full control of how objects move, rotate, and scale within your Three.js scenes.