From b6d741c5939ae4b42d5871db5f2abaca08756a87 Mon Sep 17 00:00:00 2001 From: sebcrozet Date: Tue, 6 Nov 2018 22:43:03 +0100 Subject: [PATCH] Document similarity_construction.rs. --- src/geometry/isometry_construction.rs | 6 +- src/geometry/similarity_construction.rs | 140 +++++++++++++++++++++++- 2 files changed, 144 insertions(+), 2 deletions(-) diff --git a/src/geometry/isometry_construction.rs b/src/geometry/isometry_construction.rs index 38f42c02..4d0702f0 100644 --- a/src/geometry/isometry_construction.rs +++ b/src/geometry/isometry_construction.rs @@ -27,10 +27,14 @@ where DefaultAllocator: Allocator /// # Example /// /// ``` - /// # use nalgebra::{Isometry2, Point2}; + /// # use nalgebra::{Isometry2, Point2, Isometry3, Point3}; + /// /// let iso = Isometry2::identity(); /// let pt = Point2::new(1.0, 2.0); + /// assert_eq!(iso * pt, pt); /// + /// let iso = Isometry3::identity(); + /// let pt = Point3::new(1.0, 2.0, 3.0); /// assert_eq!(iso * pt, pt); /// ``` #[inline] diff --git a/src/geometry/similarity_construction.rs b/src/geometry/similarity_construction.rs index a198b196..ccb39866 100644 --- a/src/geometry/similarity_construction.rs +++ b/src/geometry/similarity_construction.rs @@ -25,6 +25,20 @@ where DefaultAllocator: Allocator, { /// Creates a new identity similarity. + /// + /// # Example + /// + /// ``` + /// # use nalgebra::{Similarity2, Point2, Similarity3, Point3}; + /// + /// let sim = Similarity2::identity(); + /// let pt = Point2::new(1.0, 2.0); + /// assert_eq!(sim * pt, pt); + /// + /// let sim = Similarity3::identity(); + /// let pt = Point3::new(1.0, 2.0, 3.0); + /// assert_eq!(sim * pt, pt); + /// ``` #[inline] pub fn identity() -> Self { Self::from_isometry(Isometry::identity(), N::one()) @@ -67,6 +81,20 @@ where { /// The similarity that applies the scaling factor `scaling`, followed by the rotation `r` with /// its axis passing through the point `p`. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity2, Point2, UnitComplex}; + /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); + /// let pt = Point2::new(3.0, 2.0); + /// let sim = Similarity2::rotation_wrt_point(rot, pt, 4.0); + /// + /// assert_relative_eq!(sim * Point2::new(1.0, 2.0), Point2::new(-3.0, 3.0), epsilon = 1.0e-6); + /// ``` #[inline] pub fn rotation_wrt_point(r: R, p: Point, scaling: N) -> Self { let shift = r.transform_vector(&-&p.coords); @@ -101,7 +129,19 @@ where // 2D rotation. impl Similarity> { - /// Creates a new similarity from a translation and a rotation angle. + /// Creates a new similarity from a translation, a rotation, and an uniform scaling factor. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{SimilarityMatrix2, Vector2, Point2}; + /// let sim = SimilarityMatrix2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2, 3.0); + /// + /// assert_relative_eq!(sim * Point2::new(2.0, 4.0), Point2::new(-11.0, 8.0), epsilon = 1.0e-6); + /// ``` #[inline] pub fn new(translation: Vector2, angle: N, scaling: N) -> Self { Self::from_parts( @@ -114,6 +154,18 @@ impl Similarity> { impl Similarity> { /// Creates a new similarity from a translation and a rotation angle. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity2, Vector2, Point2}; + /// let sim = Similarity2::new(Vector2::new(1.0, 2.0), f32::consts::FRAC_PI_2, 3.0); + /// + /// assert_relative_eq!(sim * Point2::new(2.0, 4.0), Point2::new(-11.0, 8.0), epsilon = 1.0e-6); + /// ``` #[inline] pub fn new(translation: Vector2, angle: N, scaling: N) -> Self { Self::from_parts( @@ -130,6 +182,30 @@ macro_rules! similarity_construction_impl( impl Similarity { /// Creates a new similarity from a translation, rotation axis-angle, and scaling /// factor. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity3, SimilarityMatrix3, Point3, Vector3}; + /// let axisangle = Vector3::y() * f32::consts::FRAC_PI_2; + /// let translation = Vector3::new(1.0, 2.0, 3.0); + /// // Point and vector being transformed in the tests. + /// let pt = Point3::new(4.0, 5.0, 6.0); + /// let vec = Vector3::new(4.0, 5.0, 6.0); + /// + /// // Similarity with its rotation part represented as a UnitQuaternion + /// let sim = Similarity3::new(translation, axisangle, 3.0); + /// assert_relative_eq!(sim * pt, Point3::new(19.0, 17.0, -9.0), epsilon = 1.0e-5); + /// assert_relative_eq!(sim * vec, Vector3::new(18.0, 15.0, -12.0), epsilon = 1.0e-5); + /// + /// // Similarity with its rotation part represented as a Rotation3 (a 3x3 rotation matrix). + /// let sim = SimilarityMatrix3::new(translation, axisangle, 3.0); + /// assert_relative_eq!(sim * pt, Point3::new(19.0, 17.0, -9.0), epsilon = 1.0e-5); + /// assert_relative_eq!(sim * vec, Vector3::new(18.0, 15.0, -12.0), epsilon = 1.0e-5); + /// ``` #[inline] pub fn new(translation: Vector3, axisangle: Vector3, scaling: N) -> Self { Self::from_isometry(Isometry::<_, U3, $Rot>::new(translation, axisangle), scaling) @@ -146,6 +222,28 @@ macro_rules! similarity_construction_impl( /// * target - The target position. /// * up - Vertical direction. The only requirement of this parameter is to not be collinear /// to `eye - at`. Non-collinearity is not checked. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity3, SimilarityMatrix3, Point3, Vector3}; + /// let eye = Point3::new(1.0, 2.0, 3.0); + /// let target = Point3::new(2.0, 2.0, 3.0); + /// let up = Vector3::y(); + /// + /// // Similarity with its rotation part represented as a UnitQuaternion + /// let sim = Similarity3::new_observer_frame(&eye, &target, &up, 3.0); + /// assert_eq!(sim * Point3::origin(), eye); + /// assert_relative_eq!(sim * Vector3::z(), Vector3::x() * 3.0, epsilon = 1.0e-6); + /// + /// // Similarity with its rotation part represented as Rotation3 (a 3x3 rotation matrix). + /// let sim = SimilarityMatrix3::new_observer_frame(&eye, &target, &up, 3.0); + /// assert_eq!(sim * Point3::origin(), eye); + /// assert_relative_eq!(sim * Vector3::z(), Vector3::x() * 3.0, epsilon = 1.0e-6); + /// ``` #[inline] pub fn new_observer_frame(eye: &Point3, target: &Point3, @@ -165,6 +263,26 @@ macro_rules! similarity_construction_impl( /// * target - The target position. /// * up - A vector approximately aligned with required the vertical axis. The only /// requirement of this parameter is to not be collinear to `target - eye`. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity3, SimilarityMatrix3, Point3, Vector3}; + /// let eye = Point3::new(1.0, 2.0, 3.0); + /// let target = Point3::new(2.0, 2.0, 3.0); + /// let up = Vector3::y(); + /// + /// // Similarity with its rotation part represented as a UnitQuaternion + /// let iso = Similarity3::look_at_rh(&eye, &target, &up, 3.0); + /// assert_relative_eq!(iso * Vector3::x(), -Vector3::z() * 3.0, epsilon = 1.0e-6); + /// + /// // Similarity with its rotation part represented as Rotation3 (a 3x3 rotation matrix). + /// let iso = SimilarityMatrix3::look_at_rh(&eye, &target, &up, 3.0); + /// assert_relative_eq!(iso * Vector3::x(), -Vector3::z() * 3.0, epsilon = 1.0e-6); + /// ``` #[inline] pub fn look_at_rh(eye: &Point3, target: &Point3, @@ -184,6 +302,26 @@ macro_rules! similarity_construction_impl( /// * target - The target position. /// * up - A vector approximately aligned with required the vertical axis. The only /// requirement of this parameter is to not be collinear to `target - eye`. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{Similarity3, SimilarityMatrix3, Point3, Vector3}; + /// let eye = Point3::new(1.0, 2.0, 3.0); + /// let target = Point3::new(2.0, 2.0, 3.0); + /// let up = Vector3::y(); + /// + /// // Similarity with its rotation part represented as a UnitQuaternion + /// let sim = Similarity3::look_at_lh(&eye, &target, &up, 3.0); + /// assert_relative_eq!(sim * Vector3::x(), Vector3::z() * 3.0, epsilon = 1.0e-6); + /// + /// // Similarity with its rotation part represented as Rotation3 (a 3x3 rotation matrix). + /// let sim = SimilarityMatrix3::look_at_lh(&eye, &target, &up, 3.0); + /// assert_relative_eq!(sim * Vector3::x(), Vector3::z() * 3.0, epsilon = 1.0e-6); + /// ``` #[inline] pub fn look_at_lh(eye: &Point3, target: &Point3,