Document similarity_construction.rs.

This commit is contained in:
sebcrozet 2018-11-06 22:43:03 +01:00 committed by Sébastien Crozet
parent a8a9a3082a
commit b6d741c593
2 changed files with 144 additions and 2 deletions

View File

@ -27,10 +27,14 @@ where DefaultAllocator: Allocator<N, D>
/// # Example /// # Example
/// ///
/// ``` /// ```
/// # use nalgebra::{Isometry2, Point2}; /// # use nalgebra::{Isometry2, Point2, Isometry3, Point3};
///
/// let iso = Isometry2::identity(); /// let iso = Isometry2::identity();
/// let pt = Point2::new(1.0, 2.0); /// 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); /// assert_eq!(iso * pt, pt);
/// ``` /// ```
#[inline] #[inline]

View File

@ -25,6 +25,20 @@ where
DefaultAllocator: Allocator<N, D>, DefaultAllocator: Allocator<N, D>,
{ {
/// Creates a new identity similarity. /// 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] #[inline]
pub fn identity() -> Self { pub fn identity() -> Self {
Self::from_isometry(Isometry::identity(), N::one()) 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 /// The similarity that applies the scaling factor `scaling`, followed by the rotation `r` with
/// its axis passing through the point `p`. /// 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] #[inline]
pub fn rotation_wrt_point(r: R, p: Point<N, D>, scaling: N) -> Self { pub fn rotation_wrt_point(r: R, p: Point<N, D>, scaling: N) -> Self {
let shift = r.transform_vector(&-&p.coords); let shift = r.transform_vector(&-&p.coords);
@ -101,7 +129,19 @@ where
// 2D rotation. // 2D rotation.
impl<N: Real> Similarity<N, U2, Rotation2<N>> { impl<N: Real> Similarity<N, U2, Rotation2<N>> {
/// 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] #[inline]
pub fn new(translation: Vector2<N>, angle: N, scaling: N) -> Self { pub fn new(translation: Vector2<N>, angle: N, scaling: N) -> Self {
Self::from_parts( Self::from_parts(
@ -114,6 +154,18 @@ impl<N: Real> Similarity<N, U2, Rotation2<N>> {
impl<N: Real> Similarity<N, U2, UnitComplex<N>> { impl<N: Real> Similarity<N, U2, UnitComplex<N>> {
/// Creates a new similarity from a translation and a rotation angle. /// 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] #[inline]
pub fn new(translation: Vector2<N>, angle: N, scaling: N) -> Self { pub fn new(translation: Vector2<N>, angle: N, scaling: N) -> Self {
Self::from_parts( Self::from_parts(
@ -130,6 +182,30 @@ macro_rules! similarity_construction_impl(
impl<N: Real> Similarity<N, U3, $Rot> { impl<N: Real> Similarity<N, U3, $Rot> {
/// Creates a new similarity from a translation, rotation axis-angle, and scaling /// Creates a new similarity from a translation, rotation axis-angle, and scaling
/// factor. /// 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] #[inline]
pub fn new(translation: Vector3<N>, axisangle: Vector3<N>, scaling: N) -> Self { pub fn new(translation: Vector3<N>, axisangle: Vector3<N>, scaling: N) -> Self {
Self::from_isometry(Isometry::<_, U3, $Rot>::new(translation, axisangle), scaling) Self::from_isometry(Isometry::<_, U3, $Rot>::new(translation, axisangle), scaling)
@ -146,6 +222,28 @@ macro_rules! similarity_construction_impl(
/// * target - The target position. /// * target - The target position.
/// * up - Vertical direction. The only requirement of this parameter is to not be collinear /// * up - Vertical direction. The only requirement of this parameter is to not be collinear
/// to `eye - at`. Non-collinearity is not checked. /// 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] #[inline]
pub fn new_observer_frame(eye: &Point3<N>, pub fn new_observer_frame(eye: &Point3<N>,
target: &Point3<N>, target: &Point3<N>,
@ -165,6 +263,26 @@ macro_rules! similarity_construction_impl(
/// * target - The target position. /// * target - The target position.
/// * up - A vector approximately aligned with required the vertical axis. The only /// * up - A vector approximately aligned with required the vertical axis. The only
/// requirement of this parameter is to not be collinear to `target - eye`. /// 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] #[inline]
pub fn look_at_rh(eye: &Point3<N>, pub fn look_at_rh(eye: &Point3<N>,
target: &Point3<N>, target: &Point3<N>,
@ -184,6 +302,26 @@ macro_rules! similarity_construction_impl(
/// * target - The target position. /// * target - The target position.
/// * up - A vector approximately aligned with required the vertical axis. The only /// * up - A vector approximately aligned with required the vertical axis. The only
/// requirement of this parameter is to not be collinear to `target - eye`. /// 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] #[inline]
pub fn look_at_lh(eye: &Point3<N>, pub fn look_at_lh(eye: &Point3<N>,
target: &Point3<N>, target: &Point3<N>,