|
|
|
|
|
<!DOCTYPE html><html lang="en"><head>
|
|
|
|
|
|
<meta charset="utf-8">
|
|
|
|
|
|
<title>Matrix Transformations</title>
|
|
|
|
|
|
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
|
|
|
|
|
|
<meta name="twitter:card" content="summary_large_image">
|
|
|
|
|
|
<meta name="twitter:site" content="@threejs">
|
|
|
|
|
|
<meta name="twitter:title" content="Three.js – Matrix Transformations">
|
|
|
|
|
|
<meta property="og:image" content="https://threejs.org/files/share.png">
|
|
|
|
|
|
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
|
|
|
|
|
|
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../resources/lesson.css">
|
|
|
|
|
|
<link rel="stylesheet" href="../resources/lang.css">
|
|
|
|
|
|
<script type="importmap">
|
|
|
|
|
|
{
|
|
|
|
|
|
"imports": {
|
|
|
|
|
|
"three": "../../build/three.module.js"
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
</script>
|
|
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="lesson-title">
|
|
|
|
|
|
<h1>Matrix Transformations</h1>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="lesson">
|
|
|
|
|
|
<div class="lesson-main">
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Three.js uses `matrices` to encode 3D transformations---translations (position), rotations, and scaling. Every instance of `Object3D` has a `matrix` which stores that object's position, rotation, and scale. This page describes how to update an object's transformation.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h2>Convenience properties and `matrixAutoUpdate`</h2>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
There are two ways to update an object's transformation:
|
|
|
|
|
|
</p>
|
|
|
|
|
|
<ol>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
Modify the object's `position`, `quaternion`, and `scale` properties, and let three.js recompute
|
|
|
|
|
|
the object's matrix from these properties:
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
|
|
|
object.position.copy( start_position );
|
|
|
|
|
|
object.quaternion.copy( quaternion );
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
|
|
|
object.matrixAutoUpdate = false;
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
And after changing any properties, manually update the matrix:
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
|
|
|
object.updateMatrix();
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
Modify the object's matrix directly. The `Matrix4` class has various methods for modifying the matrix:
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
|
|
|
object.matrix.setRotationFromQuaternion( quaternion );
|
|
|
|
|
|
object.matrix.setPosition( start_position );
|
|
|
|
|
|
object.matrixAutoUpdate = false;
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
Note that `matrixAutoUpdate` <em>must</em> be set to `false` in this case, and you should make sure <em>not</em> to call `updateMatrix`. Calling `updateMatrix` will clobber the manual changes made to the matrix, recalculating the matrix from `position`, `scale`, and so on.
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
|
|
<h2>Object and world matrices</h2>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
An object's matrix stores the object's transformation <em>relative</em> to the object's parent; to get the object's transformation in <em>world</em> coordinates, you must access the object's world matrix.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
When either the parent or the child object's transformation changes, you can request that the child object's world matrix be updated by calling `object.updateMatrixWorld()`.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
An object can be transformed via `applyMatrix4()`. Note: Under-the-hood, this method relies on `Matrix4.decompose()`, and not all matrices are decomposable in this way. For example, if an object has a non-uniformly scaled parent, then the object's world matrix may not be decomposable, and this method may not be appropriate.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h2>Rotation and Quaternion</h2>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Three.js provides two ways of representing 3D rotations: Euler angles and 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 <em>always</em> stored in the object's quaternion.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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 `object.setRotationFromEuler()` method, which will update the quaternion.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script src="../resources/prettify.js"></script>
|
|
|
|
|
|
<script src="../resources/lesson.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body></html>
|
