-
-
Notifications
You must be signed in to change notification settings - Fork 35.7k
/
Copy pathmatrix-transformations.html
97 lines (85 loc) · 5 KB
/
matrix-transformations.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
<!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>