use approx::{AbsDiffEq, RelativeEq, UlpsEq}; use num_complex::Complex; use std::fmt; use crate::base::{Matrix2, Matrix3, Normed, Unit, Vector1, Vector2}; use crate::geometry::{Point2, Rotation2}; use crate::Scalar; use simba::scalar::RealField; use simba::simd::SimdRealField; use std::cmp::{Eq, PartialEq}; /// A 2D rotation represented as a complex number with magnitude 1. /// /// All the methods specific [`UnitComplex`](crate::UnitComplex) are listed here. You may also /// read the documentation of the [`Complex`](crate::Complex) type which /// is used internally and accessible with `unit_complex.complex()`. /// /// # Construction /// * [Identity `identity`](#identity) /// * [From a 2D rotation angle `new`, `from_cos_sin_unchecked`…](#construction-from-a-2d-rotation-angle) /// * [From an existing 2D matrix or complex number `from_matrix`, `rotation_to`, `powf`…](#construction-from-an-existing-2d-matrix-or-complex-number) /// * [From two vectors `rotation_between`, `scaled_rotation_between_axis`…](#construction-from-two-vectors) /// /// # Transformation and composition /// * [Angle extraction `angle`, `angle_to`…](#angle-extraction) /// * [Transformation of a vector or a point `transform_vector`, `inverse_transform_point`…](#transformation-of-a-vector-or-a-point) /// * [Conjugation and inversion `conjugate`, `inverse_mut`…](#conjugation-and-inversion) /// * [Interpolation `slerp`…](#interpolation) /// /// # Conversion /// * [Conversion to a matrix `to_rotation_matrix`, `to_homogeneous`…](#conversion-to-a-matrix) pub type UnitComplex = Unit>; impl PartialEq for UnitComplex { #[inline] fn eq(&self, rhs: &Self) -> bool { (**self).eq(&**rhs) } } impl Eq for UnitComplex {} impl Normed for Complex { type Norm = T::SimdRealField; #[inline] fn norm(&self) -> T::SimdRealField { // We don't use `.norm_sqr()` because it requires // some very strong Num trait requirements. (self.re.clone() * self.re.clone() + self.im.clone() * self.im.clone()).simd_sqrt() } #[inline] fn norm_squared(&self) -> T::SimdRealField { // We don't use `.norm_sqr()` because it requires // some very strong Num trait requirements. self.re.clone() * self.re.clone() + self.im.clone() * self.im.clone() } #[inline] fn scale_mut(&mut self, n: Self::Norm) { self.re *= n.clone(); self.im *= n; } #[inline] fn unscale_mut(&mut self, n: Self::Norm) { self.re /= n.clone(); self.im /= n; } } /// # Angle extraction impl UnitComplex where T::Element: SimdRealField, { /// The rotation angle in `]-pi; pi]` of this unit complex number. /// /// # Example /// ``` /// # use nalgebra::UnitComplex; /// let rot = UnitComplex::new(1.78); /// assert_eq!(rot.angle(), 1.78); /// ``` #[inline] #[must_use] pub fn angle(&self) -> T { self.im.clone().simd_atan2(self.re.clone()) } /// The sine of the rotation angle. /// /// # Example /// ``` /// # use nalgebra::UnitComplex; /// let angle = 1.78f32; /// let rot = UnitComplex::new(angle); /// assert_eq!(rot.sin_angle(), angle.sin()); /// ``` #[inline] #[must_use] pub fn sin_angle(&self) -> T { self.im.clone() } /// The cosine of the rotation angle. /// /// # Example /// ``` /// # use nalgebra::UnitComplex; /// let angle = 1.78f32; /// let rot = UnitComplex::new(angle); /// assert_eq!(rot.cos_angle(),angle.cos()); /// ``` #[inline] #[must_use] pub fn cos_angle(&self) -> T { self.re.clone() } /// The rotation angle returned as a 1-dimensional vector. /// /// This is generally used in the context of generic programming. Using /// the `.angle()` method instead is more common. #[inline] #[must_use] pub fn scaled_axis(&self) -> Vector1 { Vector1::new(self.angle()) } /// The rotation axis and angle in ]0, pi] of this complex number. /// /// This is generally used in the context of generic programming. Using /// the `.angle()` method instead is more common. /// Returns `None` if the angle is zero. #[inline] #[must_use] pub fn axis_angle(&self) -> Option<(Unit>, T)> where T: RealField, { let ang = self.angle(); if ang.is_zero() { None } else if ang.is_sign_positive() { Some((Unit::new_unchecked(Vector1::x()), ang)) } else { Some((Unit::new_unchecked(-Vector1::::x()), -ang)) } } /// The rotation angle needed to make `self` and `other` coincide. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::UnitComplex; /// let rot1 = UnitComplex::new(0.1); /// let rot2 = UnitComplex::new(1.7); /// assert_relative_eq!(rot1.angle_to(&rot2), 1.6); /// ``` #[inline] #[must_use] pub fn angle_to(&self, other: &Self) -> T { let delta = self.rotation_to(other); delta.angle() } } /// # Conjugation and inversion impl UnitComplex where T::Element: SimdRealField, { /// Compute the conjugate of this unit complex number. /// /// # Example /// ``` /// # use nalgebra::UnitComplex; /// let rot = UnitComplex::new(1.78); /// let conj = rot.conjugate(); /// assert_eq!(rot.complex().im, -conj.complex().im); /// assert_eq!(rot.complex().re, conj.complex().re); /// ``` #[inline] #[must_use = "Did you mean to use conjugate_mut()?"] pub fn conjugate(&self) -> Self { Self::new_unchecked(self.conj()) } /// Inverts this complex number if it is not zero. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::UnitComplex; /// let rot = UnitComplex::new(1.2); /// let inv = rot.inverse(); /// assert_relative_eq!(rot * inv, UnitComplex::identity(), epsilon = 1.0e-6); /// assert_relative_eq!(inv * rot, UnitComplex::identity(), epsilon = 1.0e-6); /// ``` #[inline] #[must_use = "Did you mean to use inverse_mut()?"] pub fn inverse(&self) -> Self { self.conjugate() } /// Compute in-place the conjugate of this unit complex number. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::UnitComplex; /// let angle = 1.7; /// let rot = UnitComplex::new(angle); /// let mut conj = UnitComplex::new(angle); /// conj.conjugate_mut(); /// assert_eq!(rot.complex().im, -conj.complex().im); /// assert_eq!(rot.complex().re, conj.complex().re); /// ``` #[inline] pub fn conjugate_mut(&mut self) { let me = self.as_mut_unchecked(); me.im = -me.im.clone(); } /// Inverts in-place this unit complex number. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::UnitComplex; /// let angle = 1.7; /// let mut rot = UnitComplex::new(angle); /// rot.inverse_mut(); /// assert_relative_eq!(rot * UnitComplex::new(angle), UnitComplex::identity()); /// assert_relative_eq!(UnitComplex::new(angle) * rot, UnitComplex::identity()); /// ``` #[inline] pub fn inverse_mut(&mut self) { self.conjugate_mut() } } /// # Conversion to a matrix impl UnitComplex where T::Element: SimdRealField, { /// Builds the rotation matrix corresponding to this unit complex number. /// /// # Example /// ``` /// # use nalgebra::{UnitComplex, Rotation2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_6); /// let expected = Rotation2::new(f32::consts::FRAC_PI_6); /// assert_eq!(rot.to_rotation_matrix(), expected); /// ``` #[inline] #[must_use] pub fn to_rotation_matrix(self) -> Rotation2 { let r = self.re.clone(); let i = self.im.clone(); Rotation2::from_matrix_unchecked(Matrix2::new(r.clone(), -i.clone(), i, r)) } /// Converts this unit complex number into its equivalent homogeneous transformation matrix. /// /// # Example /// ``` /// # use nalgebra::{UnitComplex, Matrix3}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_6); /// let expected = Matrix3::new(0.8660254, -0.5, 0.0, /// 0.5, 0.8660254, 0.0, /// 0.0, 0.0, 1.0); /// assert_eq!(rot.to_homogeneous(), expected); /// ``` #[inline] #[must_use] pub fn to_homogeneous(self) -> Matrix3 { self.to_rotation_matrix().to_homogeneous() } } /// # Transformation of a vector or a point impl UnitComplex where T::Element: SimdRealField, { /// Rotate the given point by this unit complex number. /// /// This is the same as the multiplication `self * pt`. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{UnitComplex, Point2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let transformed_point = rot.transform_point(&Point2::new(1.0, 2.0)); /// assert_relative_eq!(transformed_point, Point2::new(-2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn transform_point(&self, pt: &Point2) -> Point2 { self * pt } /// Rotate the given vector by this unit complex number. /// /// This is the same as the multiplication `self * v`. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{UnitComplex, Vector2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let transformed_vector = rot.transform_vector(&Vector2::new(1.0, 2.0)); /// assert_relative_eq!(transformed_vector, Vector2::new(-2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn transform_vector(&self, v: &Vector2) -> Vector2 { self * v } /// Rotate the given point by the inverse of this unit complex number. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{UnitComplex, Point2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let transformed_point = rot.inverse_transform_point(&Point2::new(1.0, 2.0)); /// assert_relative_eq!(transformed_point, Point2::new(2.0, -1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_point(&self, pt: &Point2) -> Point2 { // TODO: would it be useful performancewise not to call inverse explicitly (i-e. implement // the inverse transformation explicitly here) ? self.inverse() * pt } /// Rotate the given vector by the inverse of this unit complex number. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{UnitComplex, Vector2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let transformed_vector = rot.inverse_transform_vector(&Vector2::new(1.0, 2.0)); /// assert_relative_eq!(transformed_vector, Vector2::new(2.0, -1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_vector(&self, v: &Vector2) -> Vector2 { self.inverse() * v } /// Rotate the given vector by the inverse of this unit complex number. /// /// # Example /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::{UnitComplex, Vector2}; /// # use std::f32; /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let transformed_vector = rot.inverse_transform_unit_vector(&Vector2::x_axis()); /// assert_relative_eq!(transformed_vector, -Vector2::y_axis(), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_unit_vector(&self, v: &Unit>) -> Unit> { self.inverse() * v } } /// # Interpolation impl UnitComplex where T::Element: SimdRealField, { /// Spherical linear interpolation between two rotations represented as unit complex numbers. /// /// # Examples: /// /// ``` /// # #[macro_use] extern crate approx; /// # use nalgebra::geometry::UnitComplex; /// /// let rot1 = UnitComplex::new(std::f32::consts::FRAC_PI_4); /// let rot2 = UnitComplex::new(-std::f32::consts::PI); /// /// let rot = rot1.slerp(&rot2, 1.0 / 3.0); /// /// assert_relative_eq!(rot.angle(), std::f32::consts::FRAC_PI_2); /// ``` #[inline] #[must_use] pub fn slerp(&self, other: &Self, t: T) -> Self { Self::new(self.angle() * (T::one() - t.clone()) + other.angle() * t) } } impl fmt::Display for UnitComplex { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "UnitComplex angle: {}", self.angle()) } } impl AbsDiffEq for UnitComplex { type Epsilon = T; #[inline] fn default_epsilon() -> Self::Epsilon { T::default_epsilon() } #[inline] fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool { self.re.abs_diff_eq(&other.re, epsilon.clone()) && self.im.abs_diff_eq(&other.im, epsilon) } } impl RelativeEq for UnitComplex { #[inline] fn default_max_relative() -> Self::Epsilon { T::default_max_relative() } #[inline] fn relative_eq( &self, other: &Self, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool { self.re .relative_eq(&other.re, epsilon.clone(), max_relative.clone()) && self.im.relative_eq(&other.im, epsilon, max_relative) } } impl UlpsEq for UnitComplex { #[inline] fn default_max_ulps() -> u32 { T::default_max_ulps() } #[inline] fn ulps_eq(&self, other: &Self, epsilon: Self::Epsilon, max_ulps: u32) -> bool { self.re.ulps_eq(&other.re, epsilon.clone(), max_ulps) && self.im.ulps_eq(&other.im, epsilon, max_ulps) } }