Chapter 831: Matrix Transformations (Manual)

Core Idea

How three.js stores and updates an Object3D's transform: a local matrix relative to its parent, a matrixWorld in absolute space, automatic vs. manual update control, and why rotations are always stored internally as quaternions.

Key Concepts

• object.matrix: encodes an object's position, rotation and scale relative to its parent.
• object.matrixWorld: the object's transform in absolute/world space, derived by combining the object's local matrix with its parent chain.
• matrixAutoUpdate: when enabled (the default), an object's matrix recomputes automatically; can be disabled for static objects to update manually and save work.
• object.updateMatrixWorld(): forces a world-matrix recompute when a parent or child's transform changed and you need the new world matrix immediately.
• applyMatrix4() / Matrix4.decompose() caveat: applying an arbitrary matrix relies on decomposing it into position/rotation/scale, which isn't always possible — e.g. an object with a non-uniformly scaled parent may not have a cleanly decomposable world matrix.
• Euler angles vs. quaternions: three.js exposes both, but always stores rotation internally as a quaternion, because Euler angles are subject to gimbal lock (losing a degree of rotational freedom in certain configurations).
• object.setRotationFromEuler(): the modern way to set rotation from Euler angles — it updates the underlying quaternion rather than relying on a deprecated useQuaternion flag.

Key Takeaways

1. An object's matrix is parent-relative; use matrixWorld for absolute-space transforms.
2. Disable matrixAutoUpdate for static objects and call updateMatrix()/updateMatrixWorld() manually to save per-frame work.
3. applyMatrix4() can fail to decompose cleanly on objects with non-uniformly scaled parents — be cautious applying arbitrary matrices in that situation.
4. Rotation is always stored as a quaternion internally; use setRotationFromEuler() rather than the deprecated useQuaternion flag if you're working with Euler angles.

Connects To

• Object3D: the base class all of these matrix/quaternion properties and methods live on.