/////////////////////////////// Matrix transformations

Three.js uses matrices to encode 3D transformations:

1- translations (position),

2- rotations, and

3- scaling.

Important to know:

Every instance of Object3D has a matrix which stores that object's position, rotation, and scale.

Convenience properties and matrixAutoUpdate

There are two ways to update an object's transformation:

1-Modify the object's position, quaternion, and scale properties, then ask Three.js to recompute the object's matrix from these properties:

Calling the updateMatrix method forces the object's matrix to be recomputed from position, quaternion, and scale. You can also set

2- Modify the object's matrix directly.

The Matrix4 class has various methods for modifying the matrix:

Note that matrixAutoUpdate must be set to false in this case, and you should make sure not to call updateMatrix. Calling updateMatrix will clobber the manual changes made to the matrix, recalculating the matrix from position, scale, and so on.

Object and world matrices

An object's matrix stores the object's transformation relative to the object's parent;

to get the object's transformation in world coordinates, you must access the object's Object3D.matrixWorld.

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

Rotation and Quaternion

Three.js provides two ways of representing 3D rotations:

1-Euler angles and

2-Quaternions,

as well as methods for converting between the two.

Euler angles are subject to a problem called "gimbal lock,"

where certain configurations can lose a degree of freedom (preventing the object from being rotated about one axis).

For this reason, object rotations are always stored in the object's quaternion.

Previous versions of the library included a useQuaternion property which, when set to false, would cause the object's matrix to be calculated from an Euler angle.

This practice is deprecated---instead, you should use the setRotationFromEuler method, which will update the quaternion.

///////////////////////

# [name]

Three.js uses *matrices* to encode 3D transformations---translations (position), rotations, and scaling. Every instance of [page:Object3D] has a [page:Object3D.matrix matrix] which stores that object's position, rotation, and scale. This page describes how to update an object's transformation.

## Convenience properties and *matrixAutoUpdate*

There are two ways to update an object's transformation:
1. Modify the object's *position*, *quaternion*, and *scale* properties, and let Three.js recompute the object's matrix from these properties: ``` object.position.copy(start_position); object.quaternion.copy(quaternion); ``` By default, the *matrixAutoUpdate* property is set true, and the matrix will be automatically recalculated. If the object is static, or you wish to manually control when recalculation occurs, better performance can be obtained by setting the property false: ``` object.matrixAutoUpdate = false; ``` And after changing any properties, manually update the matrix: ``` object.updateMatrix(); ```
2. Modify the object's matrix directly. The [page:Matrix4] class has various methods for modifying the matrix: ``` object.matrix.setRotationFromQuaternion(quaternion); object.matrix.setPosition(start_position); object.matrixAutoUpdate = false; ``` Note that *matrixAutoUpdate* must be set to *false* in this case, and you should make sure not to call *updateMatrix*. Calling *updateMatrix* will clobber the manual changes made to the matrix, recalculating the matrix from *position*, *scale*, and so on.

## Object and world matrices

An object's [page:Object3D.matrix matrix] stores the object's transformation relative to the object's [page:Object3D.parent parent]; to get the object's transformation in world coordinates, you must access the object's [page:Object3D.matrixWorld].

When either the parent or the child object's transformation changes, you can request that the child object's [page:Object3D.matrixWorld matrixWorld] be updated by calling [page:Object3D.updateMatrixWorld updateMatrixWorld]().

## Rotation and Quaternion

Three.js provides two ways of representing 3D rotations: [page:Euler Euler angles] and [page:Quaternion Quaternions], as well as methods for converting between the two. Euler angles are subject to a problem called "gimbal lock," where certain configurations can lose a degree of freedom (preventing the object from being rotated about one axis). For this reason, object rotations are always stored in the object's [page:Object3D.quaternion quaternion].

Previous versions of the library included a *useQuaternion* property which, when set to false, would cause the object's [page:Object3D.matrix matrix] to be calculated from an Euler angle. This practice is deprecated---instead, you should use the [page:Object3D.setRotationFromEuler setRotationFromEuler] method, which will update the quaternion.