use approx::{AbsDiffEq, RelativeEq, UlpsEq}; use std::fmt; use std::hash; #[cfg(feature = "abomonation-serialize")] use std::io::{Result as IOResult, Write}; #[cfg(feature = "serde-serialize-no-std")] use serde::{Deserialize, Serialize}; #[cfg(feature = "abomonation-serialize")] use abomonation::Abomonation; use simba::scalar::{RealField, SubsetOf}; use simba::simd::SimdRealField; use crate::base::allocator::Allocator; use crate::base::dimension::{DimNameAdd, DimNameSum, U1}; use crate::base::storage::Owned; use crate::base::{Const, DefaultAllocator, OMatrix, SVector, Scalar, Unit}; use crate::geometry::{AbstractRotation, Point, Translation}; /// A direct isometry, i.e., a rotation followed by a translation (aka. a rigid-body motion). /// /// This is also known as an element of a Special Euclidean (SE) group. /// The `Isometry` type can either represent a 2D or 3D isometry. /// A 2D isometry is composed of: /// - A translation part of type [`Translation2`](crate::Translation2) /// - A rotation part which can either be a [`UnitComplex`](crate::UnitComplex) or a [`Rotation2`](crate::Rotation2). /// A 3D isometry is composed of: /// - A translation part of type [`Translation3`](crate::Translation3) /// - A rotation part which can either be a [`UnitQuaternion`](crate::UnitQuaternion) or a [`Rotation3`](crate::Rotation3). /// /// Note that instead of using the [`Isometry`](crate::Isometry) type in your code directly, you should use one /// of its aliases: [`Isometry2`](crate::Isometry2), [`Isometry3`](crate::Isometry3), /// [`IsometryMatrix2`](crate::IsometryMatrix2), [`IsometryMatrix3`](crate::IsometryMatrix3). Though /// keep in mind that all the documentation of all the methods of these aliases will also appears on /// this page. /// /// # Construction /// * [From a 2D vector and/or an angle `new`, `translation`, `rotation`…](#construction-from-a-2d-vector-andor-a-rotation-angle) /// * [From a 3D vector and/or an axis-angle `new`, `translation`, `rotation`…](#construction-from-a-3d-vector-andor-an-axis-angle) /// * [From a 3D eye position and target point `look_at`, `look_at_lh`, `face_towards`…](#construction-from-a-3d-eye-position-and-target-point) /// * [From the translation and rotation parts `from_parts`…](#from-the-translation-and-rotation-parts) /// /// # Transformation and composition /// Note that transforming vectors and points can be done by multiplication, e.g., `isometry * point`. /// Composing an isometry with another transformation can also be done by multiplication or division. /// /// * [Transformation of a vector or a point `transform_vector`, `inverse_transform_point`…](#transformation-of-a-vector-or-a-point) /// * [Inversion and in-place composition `inverse`, `append_rotation_wrt_point_mut`…](#inversion-and-in-place-composition) /// * [Interpolation `lerp_slerp`…](#interpolation) /// /// # Conversion to a matrix /// * [Conversion to a matrix `to_matrix`…](#conversion-to-a-matrix) /// #[repr(C)] #[derive(Debug)] #[cfg_attr(feature = "serde-serialize-no-std", derive(Serialize, Deserialize))] #[cfg_attr( feature = "serde-serialize-no-std", serde(bound(serialize = "R: Serialize, DefaultAllocator: Allocator>, Owned>: Serialize")) )] #[cfg_attr( feature = "serde-serialize-no-std", serde(bound(deserialize = "R: Deserialize<'de>, DefaultAllocator: Allocator>, Owned>: Deserialize<'de>")) )] pub struct Isometry { /// The pure rotational part of this isometry. pub rotation: R, /// The pure translational part of this isometry. pub translation: Translation, } #[cfg(feature = "abomonation-serialize")] impl Abomonation for Isometry where T: SimdRealField, R: Abomonation, Translation: Abomonation, { unsafe fn entomb(&self, writer: &mut W) -> IOResult<()> { self.rotation.entomb(writer)?; self.translation.entomb(writer) } fn extent(&self) -> usize { self.rotation.extent() + self.translation.extent() } unsafe fn exhume<'a, 'b>(&'a mut self, bytes: &'b mut [u8]) -> Option<&'b mut [u8]> { self.rotation .exhume(bytes) .and_then(|bytes| self.translation.exhume(bytes)) } } #[cfg(feature = "rkyv-serialize-no-std")] mod rkyv_impl { use super::Isometry; use crate::{base::Scalar, geometry::Translation}; use rkyv::{offset_of, project_struct, Archive, Deserialize, Fallible, Serialize}; impl Archive for Isometry where T::Archived: Scalar, { type Archived = Isometry; type Resolver = (R::Resolver, as Archive>::Resolver); fn resolve( &self, pos: usize, resolver: Self::Resolver, out: &mut core::mem::MaybeUninit, ) { self.rotation.resolve( pos + offset_of!(Self::Archived, rotation), resolver.0, project_struct!(out: Self::Archived => rotation), ); self.translation.resolve( pos + offset_of!(Self::Archived, translation), resolver.1, project_struct!(out: Self::Archived => translation), ); } } impl, R: Serialize, S: Fallible + ?Sized, const D: usize> Serialize for Isometry where T::Archived: Scalar, { fn serialize(&self, serializer: &mut S) -> Result { Ok(( self.rotation.serialize(serializer)?, self.translation.serialize(serializer)?, )) } } impl Deserialize, _D> for Isometry where T::Archived: Scalar + Deserialize, R::Archived: Scalar + Deserialize, { fn deserialize(&self, deserializer: &mut _D) -> Result, _D::Error> { Ok(Isometry { rotation: self.rotation.deserialize(deserializer)?, translation: self.translation.deserialize(deserializer)?, }) } } } impl hash::Hash for Isometry where Owned>: hash::Hash, { fn hash(&self, state: &mut H) { self.translation.hash(state); self.rotation.hash(state); } } impl Copy for Isometry where Owned>: Copy { } impl Clone for Isometry { #[inline] fn clone(&self) -> Self { Self { rotation: self.rotation.clone(), translation: self.translation.clone(), } } } /// # From the translation and rotation parts impl, const D: usize> Isometry { /// Creates a new isometry from its rotational and translational parts. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3, Point3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::y() * f32::consts::PI); /// let iso = Isometry3::from_parts(tra, rot); /// /// assert_relative_eq!(iso * Point3::new(1.0, 2.0, 3.0), Point3::new(-1.0, 2.0, 0.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn from_parts(translation: Translation, rotation: R) -> Self { Self { rotation, translation, } } } /// # Inversion and in-place composition impl, const D: usize> Isometry where T::Element: SimdRealField, { /// Inverts `self`. /// /// # Example /// /// ``` /// # use std::f32; /// # use nalgebra::{Isometry2, Point2, Vector2}; /// let iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let inv = iso.inverse(); /// let pt = Point2::new(1.0, 2.0); /// /// assert_eq!(inv * (iso * pt), pt); /// ``` #[inline] #[must_use = "Did you mean to use inverse_mut()?"] pub fn inverse(&self) -> Self { let mut res = self.clone(); res.inverse_mut(); res } /// Inverts `self` in-place. /// /// # Example /// /// ``` /// # use std::f32; /// # use nalgebra::{Isometry2, Point2, Vector2}; /// let mut iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let pt = Point2::new(1.0, 2.0); /// let transformed_pt = iso * pt; /// iso.inverse_mut(); /// /// assert_eq!(iso * transformed_pt, pt); /// ``` #[inline] pub fn inverse_mut(&mut self) { self.rotation.inverse_mut(); self.translation.inverse_mut(); self.translation.vector = self.rotation.transform_vector(&self.translation.vector); } /// Computes `self.inverse() * rhs` in a more efficient way. /// /// # Example /// /// ``` /// # use std::f32; /// # use nalgebra::{Isometry2, Point2, Vector2}; /// let mut iso1 = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let mut iso2 = Isometry2::new(Vector2::new(10.0, 20.0), f32::consts::FRAC_PI_4); /// /// assert_eq!(iso1.inverse() * iso2, iso1.inv_mul(&iso2)); /// ``` #[inline] #[must_use] pub fn inv_mul(&self, rhs: &Isometry) -> Self { let inv_rot1 = self.rotation.inverse(); let tr_12 = rhs.translation.vector - self.translation.vector; Isometry::from_parts( inv_rot1.transform_vector(&tr_12).into(), inv_rot1 * rhs.rotation.clone(), ) } /// Appends to `self` the given translation in-place. /// /// # Example /// /// ``` /// # use std::f32; /// # use nalgebra::{Isometry2, Translation2, Vector2}; /// let mut iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let tra = Translation2::new(3.0, 4.0); /// // Same as `iso = tra * iso`. /// iso.append_translation_mut(&tra); /// /// assert_eq!(iso.translation, Translation2::new(4.0, 6.0)); /// ``` #[inline] pub fn append_translation_mut(&mut self, t: &Translation) { self.translation.vector += &t.vector } /// Appends to `self` the given rotation in-place. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry2, Translation2, UnitComplex, Vector2}; /// let mut iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::PI / 6.0); /// let rot = UnitComplex::new(f32::consts::PI / 2.0); /// // Same as `iso = rot * iso`. /// iso.append_rotation_mut(&rot); /// /// assert_relative_eq!(iso, Isometry2::new(Vector2::new(-2.0, 1.0), f32::consts::PI * 2.0 / 3.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn append_rotation_mut(&mut self, r: &R) { self.rotation = r.clone() * self.rotation.clone(); self.translation.vector = r.transform_vector(&self.translation.vector); } /// Appends in-place to `self` a rotation centered at the point `p`, i.e., the rotation that /// lets `p` invariant. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry2, Translation2, UnitComplex, Vector2, Point2}; /// let mut iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// let pt = Point2::new(1.0, 0.0); /// iso.append_rotation_wrt_point_mut(&rot, &pt); /// /// assert_relative_eq!(iso * pt, Point2::new(-2.0, 0.0), epsilon = 1.0e-6); /// ``` #[inline] pub fn append_rotation_wrt_point_mut(&mut self, r: &R, p: &Point) { self.translation.vector -= &p.coords; self.append_rotation_mut(r); self.translation.vector += &p.coords; } /// Appends in-place to `self` a rotation centered at the point with coordinates /// `self.translation`. /// /// # Example /// /// ``` /// # use std::f32; /// # use nalgebra::{Isometry2, Translation2, UnitComplex, Vector2, Point2}; /// let mut iso = Isometry2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2); /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); /// iso.append_rotation_wrt_center_mut(&rot); /// /// // The translation part should not have changed. /// assert_eq!(iso.translation.vector, Vector2::new(1.0, 2.0)); /// assert_eq!(iso.rotation, UnitComplex::new(f32::consts::PI)); /// ``` #[inline] pub fn append_rotation_wrt_center_mut(&mut self, r: &R) { self.rotation = r.clone() * self.rotation.clone(); } } /// # Transformation of a vector or a point impl, const D: usize> Isometry where T::Element: SimdRealField, { /// Transform the given point by this isometry. /// /// This is the same as the multiplication `self * pt`. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3, Point3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::y() * f32::consts::FRAC_PI_2); /// let iso = Isometry3::from_parts(tra, rot); /// /// let transformed_point = iso.transform_point(&Point3::new(1.0, 2.0, 3.0)); /// assert_relative_eq!(transformed_point, Point3::new(3.0, 2.0, 2.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn transform_point(&self, pt: &Point) -> Point { self * pt } /// Transform the given vector by this isometry, ignoring the translation /// component of the isometry. /// /// This is the same as the multiplication `self * v`. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::y() * f32::consts::FRAC_PI_2); /// let iso = Isometry3::from_parts(tra, rot); /// /// let transformed_point = iso.transform_vector(&Vector3::new(1.0, 2.0, 3.0)); /// assert_relative_eq!(transformed_point, Vector3::new(3.0, 2.0, -1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn transform_vector(&self, v: &SVector) -> SVector { self * v } /// Transform the given point by the inverse of this isometry. This may be /// less expensive than computing the entire isometry inverse and then /// transforming the point. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3, Point3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::y() * f32::consts::FRAC_PI_2); /// let iso = Isometry3::from_parts(tra, rot); /// /// let transformed_point = iso.inverse_transform_point(&Point3::new(1.0, 2.0, 3.0)); /// assert_relative_eq!(transformed_point, Point3::new(0.0, 2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_point(&self, pt: &Point) -> Point { self.rotation .inverse_transform_point(&(pt - self.translation.vector)) } /// Transform the given vector by the inverse of this isometry, ignoring the /// translation component of the isometry. This may be /// less expensive than computing the entire isometry inverse and then /// transforming the point. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::y() * f32::consts::FRAC_PI_2); /// let iso = Isometry3::from_parts(tra, rot); /// /// let transformed_point = iso.inverse_transform_vector(&Vector3::new(1.0, 2.0, 3.0)); /// assert_relative_eq!(transformed_point, Vector3::new(-3.0, 2.0, 1.0), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_vector(&self, v: &SVector) -> SVector { self.rotation.inverse_transform_vector(v) } /// Transform the given unit vector by the inverse of this isometry, ignoring the /// translation component of the isometry. This may be /// less expensive than computing the entire isometry inverse and then /// transforming the point. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry3, Translation3, UnitQuaternion, Vector3}; /// let tra = Translation3::new(0.0, 0.0, 3.0); /// let rot = UnitQuaternion::from_scaled_axis(Vector3::z() * f32::consts::FRAC_PI_2); /// let iso = Isometry3::from_parts(tra, rot); /// /// let transformed_point = iso.inverse_transform_unit_vector(&Vector3::x_axis()); /// assert_relative_eq!(transformed_point, -Vector3::y_axis(), epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn inverse_transform_unit_vector(&self, v: &Unit>) -> Unit> { self.rotation.inverse_transform_unit_vector(v) } } // NOTE: we don't require `R: Rotation<...>` here because this is not useful for the implementation // and makes it hard to use it, e.g., for Transform × Isometry implementation. // This is OK since all constructors of the isometry enforce the Rotation bound already (and // explicit struct construction is prevented by the dummy ZST field). /// # Conversion to a matrix impl Isometry { /// Converts this isometry into its equivalent homogeneous transformation matrix. /// /// This is the same as `self.to_matrix()`. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry2, Vector2, Matrix3}; /// let iso = Isometry2::new(Vector2::new(10.0, 20.0), f32::consts::FRAC_PI_6); /// let expected = Matrix3::new(0.8660254, -0.5, 10.0, /// 0.5, 0.8660254, 20.0, /// 0.0, 0.0, 1.0); /// /// assert_relative_eq!(iso.to_homogeneous(), expected, epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn to_homogeneous(&self) -> OMatrix, U1>, DimNameSum, U1>> where Const: DimNameAdd, R: SubsetOf, U1>, DimNameSum, U1>>>, DefaultAllocator: Allocator, U1>, DimNameSum, U1>>, { let mut res: OMatrix = crate::convert_ref(&self.rotation); res.fixed_slice_mut::(0, D) .copy_from(&self.translation.vector); res } /// Converts this isometry into its equivalent homogeneous transformation matrix. /// /// This is the same as `self.to_homogeneous()`. /// /// # Example /// /// ``` /// # #[macro_use] extern crate approx; /// # use std::f32; /// # use nalgebra::{Isometry2, Vector2, Matrix3}; /// let iso = Isometry2::new(Vector2::new(10.0, 20.0), f32::consts::FRAC_PI_6); /// let expected = Matrix3::new(0.8660254, -0.5, 10.0, /// 0.5, 0.8660254, 20.0, /// 0.0, 0.0, 1.0); /// /// assert_relative_eq!(iso.to_matrix(), expected, epsilon = 1.0e-6); /// ``` #[inline] #[must_use] pub fn to_matrix(&self) -> OMatrix, U1>, DimNameSum, U1>> where Const: DimNameAdd, R: SubsetOf, U1>, DimNameSum, U1>>>, DefaultAllocator: Allocator, U1>, DimNameSum, U1>>, { self.to_homogeneous() } } impl Eq for Isometry where R: AbstractRotation + Eq { } impl PartialEq for Isometry where R: AbstractRotation + PartialEq, { #[inline] fn eq(&self, right: &Self) -> bool { self.translation == right.translation && self.rotation == right.rotation } } impl AbsDiffEq for Isometry where R: AbstractRotation + AbsDiffEq, T::Epsilon: Copy, { type Epsilon = T::Epsilon; #[inline] fn default_epsilon() -> Self::Epsilon { T::default_epsilon() } #[inline] fn abs_diff_eq(&self, other: &Self, epsilon: Self::Epsilon) -> bool { self.translation.abs_diff_eq(&other.translation, epsilon) && self.rotation.abs_diff_eq(&other.rotation, epsilon) } } impl RelativeEq for Isometry where R: AbstractRotation + RelativeEq, T::Epsilon: Copy, { #[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.translation .relative_eq(&other.translation, epsilon, max_relative) && self .rotation .relative_eq(&other.rotation, epsilon, max_relative) } } impl UlpsEq for Isometry where R: AbstractRotation + UlpsEq, T::Epsilon: Copy, { #[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.translation .ulps_eq(&other.translation, epsilon, max_ulps) && self.rotation.ulps_eq(&other.rotation, epsilon, max_ulps) } } /* * * Display * */ impl fmt::Display for Isometry where R: fmt::Display, { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { let precision = f.precision().unwrap_or(3); writeln!(f, "Isometry {{")?; write!(f, "{:.*}", precision, self.translation)?; write!(f, "{:.*}", precision, self.rotation)?; writeln!(f, "}}") } }