Skip to main content

three_rs/math/
euler.rs

1//! Port of `three.js/src/math/Euler.js`.
2//!
3//! `Euler` in three.js holds its fields behind accessors so it can fire an
4//! `onChange` callback (that is how `Object3D.rotation` keeps
5//! `Object3D.quaternion` in step). Rust has no such hook, so the fields are
6//! plain and the callers that need the sync do it explicitly — see
7//! [`crate::core::Object3D::set_rotation`].
8
9use super::math_utils::clamp;
10use super::{Matrix4, Quaternion, Vector3};
11
12/// The axis order in which the three rotations of an [`Euler`] are applied.
13/// Corresponds to the order strings three.js uses (`'XYZ'`, `'YXZ'`, etc.);
14/// three.js also accepts an unrecognized order string by warning and leaving
15/// the angles unchanged; there is no such fallback here since the type
16/// system rules it out.
17#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
18pub enum EulerOrder {
19    /// `Euler.DEFAULT_ORDER`.
20    #[default]
21    XYZ,
22    /// Y, then X, then Z.
23    YXZ,
24    /// Z, then X, then Y.
25    ZXY,
26    /// Z, then Y, then X.
27    ZYX,
28    /// Y, then Z, then X.
29    YZX,
30    /// X, then Z, then Y.
31    XZY,
32}
33
34/// Port of three.js' `Euler`: a rotation expressed as three angles (radians)
35/// applied in a given [`EulerOrder`]. Unlike three.js, setting a field here
36/// does not fire an `onChange` callback; see the module docs above.
37#[derive(Clone, Copy, Debug, Default, PartialEq)]
38pub struct Euler {
39    /// The angle of the x axis in radians.
40    pub x: f64,
41    /// The angle of the y axis in radians.
42    pub y: f64,
43    /// The angle of the z axis in radians.
44    pub z: f64,
45    /// The order in which the rotations are applied.
46    pub order: EulerOrder,
47}
48
49impl Euler {
50    /// `new Euler( x, y, z )` — order defaults to `Euler.DEFAULT_ORDER`.
51    pub fn new(x: f64, y: f64, z: f64) -> Self {
52        Self {
53            x,
54            y,
55            z,
56            order: EulerOrder::XYZ,
57        }
58    }
59
60    /// `new Euler( x, y, z, order )`.
61    pub fn new_with_order(x: f64, y: f64, z: f64, order: EulerOrder) -> Self {
62        Self { x, y, z, order }
63    }
64
65    /// `Euler.set( x, y, z )` — keeps the current order.
66    pub fn set(&mut self, x: f64, y: f64, z: f64) -> &mut Self {
67        self.x = x;
68        self.y = y;
69        self.z = z;
70        self
71    }
72
73    /// `Euler.set( x, y, z, order )`.
74    pub fn set_with_order(&mut self, x: f64, y: f64, z: f64, order: EulerOrder) -> &mut Self {
75        self.x = x;
76        self.y = y;
77        self.z = z;
78        self.order = order;
79        self
80    }
81
82    /// `Euler.copy()`.
83    pub fn copy(&mut self, euler: &Self) -> &mut Self {
84        *self = *euler;
85        self
86    }
87
88    /// `Euler.setFromRotationMatrix()`. Assumes the upper 3x3 of `m` is a pure
89    /// rotation (i.e. unscaled).
90    pub fn set_from_rotation_matrix(&mut self, m: &Matrix4, order: EulerOrder) -> &mut Self {
91        let te = &m.elements;
92        let (m11, m12, m13) = (te[0], te[4], te[8]);
93        let (m21, m22, m23) = (te[1], te[5], te[9]);
94        let (m31, m32, m33) = (te[2], te[6], te[10]);
95
96        match order {
97            EulerOrder::XYZ => {
98                self.y = clamp(m13, -1.0, 1.0).asin();
99
100                if m13.abs() < 0.9999999 {
101                    self.x = (-m23).atan2(m33);
102                    self.z = (-m12).atan2(m11);
103                } else {
104                    self.x = m32.atan2(m22);
105                    self.z = 0.0;
106                }
107            }
108            EulerOrder::YXZ => {
109                self.x = (-clamp(m23, -1.0, 1.0)).asin();
110
111                if m23.abs() < 0.9999999 {
112                    self.y = m13.atan2(m33);
113                    self.z = m21.atan2(m22);
114                } else {
115                    self.y = (-m31).atan2(m11);
116                    self.z = 0.0;
117                }
118            }
119            EulerOrder::ZXY => {
120                self.x = clamp(m32, -1.0, 1.0).asin();
121
122                if m32.abs() < 0.9999999 {
123                    self.y = (-m31).atan2(m33);
124                    self.z = (-m12).atan2(m22);
125                } else {
126                    self.y = 0.0;
127                    self.z = m21.atan2(m11);
128                }
129            }
130            EulerOrder::ZYX => {
131                self.y = (-clamp(m31, -1.0, 1.0)).asin();
132
133                if m31.abs() < 0.9999999 {
134                    self.x = m32.atan2(m33);
135                    self.z = m21.atan2(m11);
136                } else {
137                    self.x = 0.0;
138                    self.z = (-m12).atan2(m22);
139                }
140            }
141            EulerOrder::YZX => {
142                self.z = clamp(m21, -1.0, 1.0).asin();
143
144                if m21.abs() < 0.9999999 {
145                    self.x = (-m23).atan2(m22);
146                    self.y = (-m31).atan2(m11);
147                } else {
148                    self.x = 0.0;
149                    self.y = m13.atan2(m33);
150                }
151            }
152            EulerOrder::XZY => {
153                self.z = (-clamp(m12, -1.0, 1.0)).asin();
154
155                if m12.abs() < 0.9999999 {
156                    self.x = m32.atan2(m22);
157                    self.y = m13.atan2(m11);
158                } else {
159                    self.x = (-m23).atan2(m33);
160                    self.y = 0.0;
161                }
162            }
163        }
164
165        self.order = order;
166
167        self
168    }
169
170    /// `Euler.setFromQuaternion()`.
171    pub fn set_from_quaternion(&mut self, q: &Quaternion, order: EulerOrder) -> &mut Self {
172        let mut matrix = Matrix4::identity();
173        matrix.make_rotation_from_quaternion(q);
174        self.set_from_rotation_matrix(&matrix, order)
175    }
176
177    /// `Euler.setFromVector3()` — keeps the current order.
178    pub fn set_from_vector3(&mut self, v: &Vector3) -> &mut Self {
179        self.set(v.x, v.y, v.z)
180    }
181
182    /// `Euler.reorder()`: same rotation, different order. Note that information
183    /// can be lost, exactly as in three.js.
184    pub fn reorder(&mut self, new_order: EulerOrder) -> &mut Self {
185        let mut q = Quaternion::default();
186        q.set_from_euler(self);
187        self.set_from_quaternion(&q, new_order)
188    }
189
190    /// `Euler.equals()`.
191    pub fn equals(&self, euler: &Self) -> bool {
192        euler.x == self.x && euler.y == self.y && euler.z == self.z && euler.order == self.order
193    }
194
195    /// `Euler.fromArray()` — the `order` element of three.js' array form has no
196    /// numeric equivalent, so only the three angles are read.
197    pub fn from_array(&mut self, array: &[f64]) -> &mut Self {
198        self.x = array[0];
199        self.y = array[1];
200        self.z = array[2];
201        self
202    }
203
204    /// `Euler.toArray()`, angles only.
205    pub fn to_array(&self) -> [f64; 3] {
206        [self.x, self.y, self.z]
207    }
208}