Merge pull request #527 from manuelmauro/master

Rename ::new_observer_frame to ::face_towards

src/base/cg.rs

@@ -130,8 +130,14 @@ impl<N: Real> Matrix4<N> {
     /// It maps the view direction `target - eye` to the positive `z` axis and the origin to the
     /// `eye`.
     #[inline]
+    pub fn face_towards(eye: &Point3<N>, target: &Point3<N>, up: &Vector3<N>) -> Self {
+        IsometryMatrix3::face_towards(eye, target, up).to_homogeneous()
+    }
+
+    /// Deprecated: Use [Matrix4::face_towards] instead.
+    #[deprecated(note="renamed to `face_towards`")]
     pub fn new_observer_frame(eye: &Point3<N>, target: &Point3<N>, up: &Vector3<N>) -> Self {
-        IsometryMatrix3::new_observer_frame(eye, target, up).to_homogeneous()
+        Matrix4::face_towards(eye, target, up)
     }
 
     /// Builds a right-handed look-at view matrix.

src/geometry/isometry_construction.rs

@@ -214,23 +214,32 @@ macro_rules! isometry_construction_impl(
             /// let up = Vector3::y();
             ///
             /// // Isometry with its rotation part represented as a UnitQuaternion
-            /// let iso = Isometry3::new_observer_frame(&eye, &target, &up);
+            /// let iso = Isometry3::face_towards(&eye, &target, &up);
             /// assert_eq!(iso * Point3::origin(), eye);
             /// assert_relative_eq!(iso * Vector3::z(), Vector3::x());
             ///
             /// // Isometry with its rotation part represented as Rotation3 (a 3x3 rotation matrix).
-            /// let iso = IsometryMatrix3::new_observer_frame(&eye, &target, &up);
+            /// let iso = IsometryMatrix3::face_towards(&eye, &target, &up);
             /// assert_eq!(iso * Point3::origin(), eye);
             /// assert_relative_eq!(iso * Vector3::z(), Vector3::x());
             /// ```
             #[inline]
-            pub fn new_observer_frame(eye:    &Point3<N>,
+            pub fn face_towards(eye:    &Point3<N>,
                                       target: &Point3<N>,
                                       up:     &Vector3<N>)
                                       -> Self {
                 Self::from_parts(
                     Translation::from(eye.coords.clone()),
-                    $RotId::new_observer_frame(&(target - eye), up))
+                    $RotId::face_towards(&(target - eye), up))
+            }
+
+            /// Deprecated: Use [Isometry::face_towards] instead.
+            #[deprecated(note="renamed to `face_towards`")]
+            pub fn new_observer_frame(eye:    &Point3<N>,
+                                      target: &Point3<N>,
+                                      up:     &Vector3<N>)
+                                      -> Self {
+                Self::face_towards(eye, target, up)
             }
 
             /// Builds a right-handed look-at view matrix.

src/geometry/quaternion_construction.rs

@@ -452,16 +452,26 @@ impl<N: Real> UnitQuaternion<N> {
     /// let dir = Vector3::new(1.0, 2.0, 3.0);
     /// let up = Vector3::y();
     ///
-    /// let q = UnitQuaternion::new_observer_frame(&dir, &up);
+    /// let q = UnitQuaternion::face_towards(&dir, &up);
     /// assert_relative_eq!(q * Vector3::z(), dir.normalize());
     /// ```
     #[inline]
-    pub fn new_observer_frame<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
+    pub fn face_towards<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
     where
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
     {
-        Self::from_rotation_matrix(&Rotation::<N, U3>::new_observer_frame(dir, up))
+        Self::from_rotation_matrix(&Rotation::<N, U3>::face_towards(dir, up))
+    }
+
+    /// Deprecated: Use [UnitQuaternion::face_towards] instead.
+    #[deprecated(note="renamed to `face_towards`")]
+    pub fn new_observer_frames<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
+    where
+        SB: Storage<N, U3>,
+        SC: Storage<N, U3>,
+    {
+        Self::face_towards(dir, up)
     }
 
     /// Builds a right-handed look-at view matrix without translation.
@@ -493,7 +503,7 @@ impl<N: Real> UnitQuaternion<N> {
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
     {
-        Self::new_observer_frame(&-dir, up).inverse()
+        Self::face_towards(&-dir, up).inverse()
     }
 
     /// Builds a left-handed look-at view matrix without translation.
@@ -525,7 +535,7 @@ impl<N: Real> UnitQuaternion<N> {
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
     {
-        Self::new_observer_frame(dir, up).inverse()
+        Self::face_towards(dir, up).inverse()
     }
 
     /// Creates a new unit quaternion rotation from a rotation axis scaled by the rotation angle.

src/geometry/rotation_specialization.rs

@@ -409,11 +409,11 @@ impl<N: Real> Rotation3<N> {
     /// let dir = Vector3::new(1.0, 2.0, 3.0);
     /// let up = Vector3::y();
     ///
-    /// let rot = Rotation3::new_observer_frame(&dir, &up);
+    /// let rot = Rotation3::face_towards(&dir, &up);
     /// assert_relative_eq!(rot * Vector3::z(), dir.normalize());
     /// ```
     #[inline]
-    pub fn new_observer_frame<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
+    pub fn face_towards<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
     where
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
@@ -427,6 +427,16 @@ impl<N: Real> Rotation3<N> {
         ))
     }
 
+    /// Deprecated: Use [Rotation3::face_towards] instead.
+    #[deprecated(note="renamed to `face_towards`")]
+    pub fn new_observer_frames<SB, SC>(dir: &Vector<N, U3, SB>, up: &Vector<N, U3, SC>) -> Self
+    where
+        SB: Storage<N, U3>,
+        SC: Storage<N, U3>,
+    {
+        Self::face_towards(dir, up)
+    }
+
     /// Builds a right-handed look-at view matrix without translation.
     ///
     /// It maps the view direction `dir` to the **negative** `z` axis.
@@ -456,7 +466,7 @@ impl<N: Real> Rotation3<N> {
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
     {
-        Self::new_observer_frame(&dir.neg(), up).inverse()
+        Self::face_towards(&dir.neg(), up).inverse()
     }
 
     /// Builds a left-handed look-at view matrix without translation.
@@ -488,7 +498,7 @@ impl<N: Real> Rotation3<N> {
         SB: Storage<N, U3>,
         SC: Storage<N, U3>,
     {
-        Self::new_observer_frame(dir, up).inverse()
+        Self::face_towards(dir, up).inverse()
     }
 
     /// The rotation matrix required to align `a` and `b` but with its angle.

src/geometry/similarity_construction.rs

@@ -235,22 +235,32 @@ macro_rules! similarity_construction_impl(
             /// let up = Vector3::y();
             ///
             /// // Similarity with its rotation part represented as a UnitQuaternion
-            /// let sim = Similarity3::new_observer_frame(&eye, &target, &up, 3.0);
+            /// let sim = Similarity3::face_towards(&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);
+            /// let sim = SimilarityMatrix3::face_towards(&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<N>,
+            pub fn face_towards(eye:    &Point3<N>,
                                       target: &Point3<N>,
                                       up:     &Vector3<N>,
                                       scaling: N)
                                       -> Self {
-                Self::from_isometry(Isometry::<_, U3, $Rot>::new_observer_frame(eye, target, up), scaling)
+                Self::from_isometry(Isometry::<_, U3, $Rot>::face_towards(eye, target, up), scaling)
+            }
+
+            /// Deprecated: Use [SimilarityMatrix3::face_towards] instead.
+            #[deprecated(note="renamed to `face_towards`")]
+            pub fn new_observer_frames(eye:    &Point3<N>,
+                                      target: &Point3<N>,
+                                      up:     &Vector3<N>,
+                                      scaling: N)
+                                      -> Self {
+                Self::face_towards(eye, target, up, scaling)
             }
 
             /// Builds a right-handed look-at view matrix including scaling factor.

tests/geometry/isometry.rs

@@ -30,7 +30,7 @@ quickcheck!(
     }
 
     fn observer_frame_3(eye: Point3<f64>, target: Point3<f64>, up: Vector3<f64>) -> bool {
-        let observer = Isometry3::new_observer_frame(&eye, &target, &up);
+        let observer = Isometry3::face_towards(&eye, &target, &up);
 
         let origin = Point3::origin();
         relative_eq!(observer * origin, eye, epsilon = 1.0e-7) &&