From 96db8e564a72b5686e2a366b632cf427333608ec Mon Sep 17 00:00:00 2001 From: sebcrozet Date: Sun, 28 Oct 2018 07:33:14 +0100 Subject: [PATCH] Complete the documentation for Translation. --- src/geometry/translation.rs | 54 ++++++++++++++++++++++-- src/geometry/translation_alga.rs | 6 +-- src/geometry/translation_alias.rs | 14 +++++- src/geometry/translation_construction.rs | 36 +++++++++++++--- src/geometry/translation_conversion.rs | 19 +++++++-- src/geometry/translation_ops.rs | 16 +++---- 6 files changed, 120 insertions(+), 25 deletions(-) diff --git a/src/geometry/translation.rs b/src/geometry/translation.rs index e7821cca..7b1a8957 100644 --- a/src/geometry/translation.rs +++ b/src/geometry/translation.rs @@ -52,7 +52,7 @@ where { #[inline] fn clone(&self) -> Self { - Translation::from_vector(self.vector.clone()) + Translation::from(self.vector.clone()) } } @@ -99,7 +99,7 @@ where where Des: Deserializer<'a> { let matrix = VectorN::::deserialize(deserializer)?; - Ok(Translation::from_vector(matrix)) + Ok(Translation::from(matrix)) } } @@ -108,18 +108,49 @@ where DefaultAllocator: Allocator { /// Creates a new translation from the given vector. #[inline] + #[deprecated(note = "Use `::from` instead.")] pub fn from_vector(vector: VectorN) -> Translation { Translation { vector: vector } } /// Inverts `self`. + /// + /// # Example + /// ``` + /// # use nalgebra::{Translation2, Translation3}; + /// let t = Translation3::new(1.0, 2.0, 3.0); + /// assert_eq!(t * t.inverse(), Translation3::identity()); + /// assert_eq!(t.inverse() * t, Translation3::identity()); + /// + /// // Work in all dimensions. + /// let t = Translation2::new(1.0, 2.0); + /// assert_eq!(t * t.inverse(), Translation2::identity()); + /// assert_eq!(t.inverse() * t, Translation2::identity()); + /// ``` #[inline] pub fn inverse(&self) -> Translation where N: ClosedNeg { - Translation::from_vector(-&self.vector) + Translation::from(-&self.vector) } /// Converts this translation into its equivalent homogeneous transformation matrix. + /// + /// # Example + /// ``` + /// # use nalgebra::{Translation2, Translation3, Matrix3, Matrix4}; + /// let t = Translation3::new(10.0, 20.0, 30.0); + /// let expected = Matrix4::new(1.0, 0.0, 0.0, 10.0, + /// 0.0, 1.0, 0.0, 20.0, + /// 0.0, 0.0, 1.0, 30.0, + /// 0.0, 0.0, 0.0, 1.0); + /// assert_eq!(t.to_homogeneous(), expected); + /// + /// let t = Translation2::new(10.0, 20.0); + /// let expected = Matrix3::new(1.0, 0.0, 10.0, + /// 0.0, 1.0, 20.0, + /// 0.0, 0.0, 1.0); + /// assert_eq!(t.to_homogeneous(), expected); + /// ``` #[inline] pub fn to_homogeneous(&self) -> MatrixN> where @@ -135,6 +166,23 @@ where DefaultAllocator: Allocator } /// Inverts `self` in-place. + /// + /// # Example + /// ``` + /// # use nalgebra::{Translation2, Translation3}; + /// let t = Translation3::new(1.0, 2.0, 3.0); + /// let mut inv_t = Translation3::new(1.0, 2.0, 3.0); + /// inv_t.inverse_mut(); + /// assert_eq!(t * inv_t, Translation3::identity()); + /// assert_eq!(inv_t * t, Translation3::identity()); + /// + /// // Work in all dimensions. + /// let t = Translation2::new(1.0, 2.0); + /// let mut inv_t = Translation2::new(1.0, 2.0); + /// inv_t.inverse_mut(); + /// assert_eq!(t * inv_t, Translation2::identity()); + /// assert_eq!(inv_t * t, Translation2::identity()); + /// ``` #[inline] pub fn inverse_mut(&mut self) where N: ClosedNeg { diff --git a/src/geometry/translation_alga.rs b/src/geometry/translation_alga.rs index 896e7a8b..24aa28d2 100644 --- a/src/geometry/translation_alga.rs +++ b/src/geometry/translation_alga.rs @@ -183,16 +183,16 @@ where DefaultAllocator: Allocator #[inline] fn from_vector(v: VectorN) -> Option { - Some(Self::from_vector(v)) + Some(Self::from(v)) } #[inline] fn powf(&self, n: N) -> Option { - Some(Self::from_vector(&self.vector * n)) + Some(Self::from(&self.vector * n)) } #[inline] fn translation_between(a: &Point, b: &Point) -> Option { - Some(Self::from_vector(b - a)) + Some(Self::from(b - a)) } } diff --git a/src/geometry/translation_alias.rs b/src/geometry/translation_alias.rs index 331c1405..41885db7 100644 --- a/src/geometry/translation_alias.rs +++ b/src/geometry/translation_alias.rs @@ -1,9 +1,21 @@ -use base::dimension::{U2, U3}; +use base::dimension::{U1, U2, U3, U4, U5, U6}; use geometry::Translation; +/// A 1-dimensional translation. +pub type Translation1 = Translation; + /// A 2-dimensional translation. pub type Translation2 = Translation; /// A 3-dimensional translation. pub type Translation3 = Translation; + +/// A 4-dimensional translation. +pub type Translation4 = Translation; + +/// A 5-dimensional translation. +pub type Translation5 = Translation; + +/// A 6-dimensional translation. +pub type Translation6 = Translation; diff --git a/src/geometry/translation_construction.rs b/src/geometry/translation_construction.rs index cc67507d..d55c43c2 100644 --- a/src/geometry/translation_construction.rs +++ b/src/geometry/translation_construction.rs @@ -18,10 +18,23 @@ use geometry::Translation; impl Translation where DefaultAllocator: Allocator { - /// Creates a new square identity rotation of the given `dimension`. + /// Creates a new identity translation. + /// + /// # Example + /// ``` + /// # use nalgebra::{Point2, Point3, Translation2, Translation3}; + /// let t = Translation2::identity(); + /// let p = Point2::new(1.0, 2.0); + /// assert_eq!(t * p, p); + /// + /// // Works in all dimensions. + /// let t = Translation3::identity(); + /// let p = Point3::new(1.0, 2.0, 3.0); + /// assert_eq!(t * p, p); + /// ``` #[inline] pub fn identity() -> Translation { - Self::from_vector(VectorN::::from_element(N::zero())) + Self::from(VectorN::::from_element(N::zero())) } } @@ -41,7 +54,7 @@ where { #[inline] fn sample<'a, G: Rng + ?Sized>(&self, rng: &'a mut G) -> Translation { - Translation::from_vector(rng.gen::>()) + Translation::from(rng.gen::>()) } } @@ -53,7 +66,7 @@ where { #[inline] fn arbitrary(rng: &mut G) -> Self { - Self::from_vector(Arbitrary::arbitrary(rng)) + Self::from(Arbitrary::arbitrary(rng)) } } @@ -63,23 +76,32 @@ where * */ macro_rules! componentwise_constructors_impl( - ($($D: ty, $($args: ident:$irow: expr),*);* $(;)*) => {$( + ($($doc: expr; $D: ty, $($args: ident:$irow: expr),*);* $(;)*) => {$( impl Translation where DefaultAllocator: Allocator { - /// Initializes this matrix from its components. + #[doc = "Initializes this translation from its components."] + #[doc = "# Example\n```"] + #[doc = $doc] + #[doc = "```"] #[inline] pub fn new($($args: N),*) -> Self { - Self::from_vector(VectorN::::new($($args),*)) + Self::from(VectorN::::new($($args),*)) } } )*} ); componentwise_constructors_impl!( + "# use nalgebra::Translation1;\nlet t = Translation1::new(1.0);\nassert!(t.vector.x == 1.0);"; U1, x:0; + "# use nalgebra::Translation2;\nlet t = Translation2::new(1.0, 2.0);\nassert!(t.vector.x == 1.0 && t.vector.y == 2.0);"; U2, x:0, y:1; + "# use nalgebra::Translation3;\nlet t = Translation3::new(1.0, 2.0, 3.0);\nassert!(t.vector.x == 1.0 && t.vector.y == 2.0 && t.vector.z == 3.0);"; U3, x:0, y:1, z:2; + "# use nalgebra::Translation4;\nlet t = Translation4::new(1.0, 2.0, 3.0, 4.0);\nassert!(t.vector.x == 1.0 && t.vector.y == 2.0 && t.vector.z == 3.0 && t.vector.w == 4.0);"; U4, x:0, y:1, z:2, w:3; + "# use nalgebra::Translation5;\nlet t = Translation5::new(1.0, 2.0, 3.0, 4.0, 5.0);\nassert!(t.vector.x == 1.0 && t.vector.y == 2.0 && t.vector.z == 3.0 && t.vector.w == 4.0 && t.vector.a == 5.0);"; U5, x:0, y:1, z:2, w:3, a:4; + "# use nalgebra::Translation6;\nlet t = Translation6::new(1.0, 2.0, 3.0, 4.0, 5.0, 6.0);\nassert!(t.vector.x == 1.0 && t.vector.y == 2.0 && t.vector.z == 3.0 && t.vector.w == 4.0 && t.vector.a == 5.0 && t.vector.b == 6.0);"; U6, x:0, y:1, z:2, w:3, a:4, b:5; ); diff --git a/src/geometry/translation_conversion.rs b/src/geometry/translation_conversion.rs index 0d0b20ea..d4fd9df2 100644 --- a/src/geometry/translation_conversion.rs +++ b/src/geometry/translation_conversion.rs @@ -28,7 +28,7 @@ where { #[inline] fn to_superset(&self) -> Translation { - Translation::from_vector(self.vector.to_superset()) + Translation::from(self.vector.to_superset()) } #[inline] @@ -38,7 +38,9 @@ where #[inline] unsafe fn from_superset_unchecked(rot: &Translation) -> Self { - Translation::from_vector(rot.vector.to_subset_unchecked()) + Translation { + vector: rot.vector.to_subset_unchecked(), + } } } @@ -145,7 +147,9 @@ where #[inline] unsafe fn from_superset_unchecked(m: &MatrixN>) -> Self { let t = m.fixed_slice::(0, D::dim()); - Self::from_vector(::convert_unchecked(t.into_owned())) + Self { + vector: ::convert_unchecked(t.into_owned()), + } } } @@ -159,3 +163,12 @@ where t.to_homogeneous() } } + +impl From> for Translation +where DefaultAllocator: Allocator +{ + #[inline] + fn from(vector: VectorN) -> Self { + Translation { vector } + } +} diff --git a/src/geometry/translation_ops.rs b/src/geometry/translation_ops.rs index d124c763..57b8d6d1 100644 --- a/src/geometry/translation_ops.rs +++ b/src/geometry/translation_ops.rs @@ -13,44 +13,44 @@ use geometry::{Point, Translation}; add_sub_impl!(Mul, mul, ClosedAdd; (D, U1), (D, U1) -> (D) for D: DimName; self: &'a Translation, right: &'b Translation, Output = Translation; - Translation::from_vector(&self.vector + &right.vector); 'a, 'b); + Translation::from(&self.vector + &right.vector); 'a, 'b); add_sub_impl!(Mul, mul, ClosedAdd; (D, U1), (D, U1) -> (D) for D: DimName; self: &'a Translation, right: Translation, Output = Translation; - Translation::from_vector(&self.vector + right.vector); 'a); + Translation::from(&self.vector + right.vector); 'a); add_sub_impl!(Mul, mul, ClosedAdd; (D, U1), (D, U1) -> (D) for D: DimName; self: Translation, right: &'b Translation, Output = Translation; - Translation::from_vector(self.vector + &right.vector); 'b); + Translation::from(self.vector + &right.vector); 'b); add_sub_impl!(Mul, mul, ClosedAdd; (D, U1), (D, U1) -> (D) for D: DimName; self: Translation, right: Translation, Output = Translation; - Translation::from_vector(self.vector + right.vector); ); + Translation::from(self.vector + right.vector); ); // Translation ÷ Translation // FIXME: instead of calling inverse explicitly, could we just add a `mul_tr` or `mul_inv` method? add_sub_impl!(Div, div, ClosedSub; (D, U1), (D, U1) -> (D) for D: DimName; self: &'a Translation, right: &'b Translation, Output = Translation; - Translation::from_vector(&self.vector - &right.vector); 'a, 'b); + Translation::from(&self.vector - &right.vector); 'a, 'b); add_sub_impl!(Div, div, ClosedSub; (D, U1), (D, U1) -> (D) for D: DimName; self: &'a Translation, right: Translation, Output = Translation; - Translation::from_vector(&self.vector - right.vector); 'a); + Translation::from(&self.vector - right.vector); 'a); add_sub_impl!(Div, div, ClosedSub; (D, U1), (D, U1) -> (D) for D: DimName; self: Translation, right: &'b Translation, Output = Translation; - Translation::from_vector(self.vector - &right.vector); 'b); + Translation::from(self.vector - &right.vector); 'b); add_sub_impl!(Div, div, ClosedSub; (D, U1), (D, U1) -> (D) for D: DimName; self: Translation, right: Translation, Output = Translation; - Translation::from_vector(self.vector - right.vector); ); + Translation::from(self.vector - right.vector); ); // Translation × Point // FIXME: we don't handle properly non-zero origins here. Do we want this to be the intended