Add from_path_ends plus example

Author: argerlt

orix/quaternion/misorientation.py

@@ -273,6 +273,39 @@ def from_scipy_rotation(
             M.symmetry = symmetry
         return M
 
+    @classmethod
+    def from_path_ends(
+        cls, points: Misorientation, closed: bool = False, steps: int = 100
+    ) -> Misorientation:
+        """Return misorientations tracing the shortest path between
+        two or more consecutive points.
+        Parameters
+        ----------
+        points
+            Two or more misorientations that define waypoints along
+            a path through rotation space (SO3).
+        closed
+            Option to add a final trip from the last waypoint back to
+            the first, thus closing the loop. The default is False.
+        steps
+            Number of misorientations to return along the path
+            between each pair of waypoints. The default is 100.
+        Returns
+        -------
+        path
+            misorientations that map a path between the given waypoints.
+        """
+        # Confirm `points` are (mis)orientations.
+        if not isinstance(points, Misorientation):
+            raise TypeError(
+                f"Points must be a Misorientation, not of type {type(points)}"
+            )
+        # Create a path through Quaternion space, then reapply the symmetry.
+        out = super().from_path_ends(points=points, closed=closed, steps=steps)
+        path = cls(out.data)
+        path._symmetry = points._symmetry
+        return path
+
     @classmethod
     def random(
         cls,

orix/quaternion/orientation.py

@@ -352,6 +352,39 @@ def from_scipy_rotation(
             O.symmetry = symmetry
         return O
 
+    @classmethod
+    def from_path_ends(
+        cls, points: Orientation, closed: bool = False, steps: int = 100
+    ) -> Misorientation:
+        """Return orientations tracing the shortest path between
+        two or more consecutive points.
+        Parameters
+        ----------
+        points
+            Two or more orientations that define waypoints along
+            a path through rotation space (SO3).
+        closed
+            Option to add a final trip from the last waypoint back to
+            the first, thus closing the loop. The default is False.
+        steps
+            Number of orientations to return along the path
+            between each pair of waypoints. The default is 100.
+        Returns
+        -------
+        path
+            orientations that map a path between the given waypoints.
+        """
+        # Confirm `points` are orientations.
+        if not isinstance(points, Orientation):
+            raise TypeError(
+                f"Points must be an Orientation instance, not of type {type(points)}"
+            )
+        # Create a path through Quaternion space, then reapply the symmetry.
+        out = super().from_path_ends(points=points, closed=closed, steps=steps)
+        path = cls(out.data)
+        path._symmetry = points._symmetry
+        return path
+
     @classmethod
     def random(
         cls, shape: int | tuple[int, ...] = 1, symmetry: Symmetry | None = None

orix/quaternion/quaternion.py

@@ -691,6 +691,47 @@ def from_align_vectors(
 
         return out[0] if len(out) == 1 else tuple(out)
 
+    @classmethod
+    def from_path_ends(
+        cls, points: Quaternion, closed: bool = False, steps: int = 100
+    ) -> Quaternion:
+        """Return quaternions tracing the shortest path between two or
+        more consecutive points.
+        Parameters
+        ----------
+        points
+            Two or more quaternions that define points along a path
+            through rotation space (SO3).
+        closed
+            Option to add a final trip from the last waypoint back to
+            the first, thus closing the loop. The default is False.
+        steps
+            Number of quaternions to return along the path between each
+            pair of waypoints. The default is 100.
+        Returns
+        -------
+        path
+            quaternions that map a path between the given waypoints.
+        """
+        points = points.flatten()
+        n = points.size
+        if not closed:
+            n = n - 1
+
+        path_list = []
+        for i in range(n):
+            # get start and end for this leg of the trip
+            q1 = points[i]
+            q2 = points[(i + 1) % (points.size)]
+            # find the ax/ang describing the trip between points
+            ax, ang = _conversions.qu2ax((~q1 * q2).data)
+            # get 'steps=n' steps along the trip and add them to the journey
+            trip = Quaternion.from_axes_angles(ax, np.linspace(0, ang, steps))
+            path_list.append((q1 * (trip.flatten())).data)
+        path_data = np.concatenate(path_list, axis=0)
+        path = cls(path_data)
+        return path
+
     @classmethod
     def triple_cross(cls, q1: Quaternion, q2: Quaternion, q3: Quaternion) -> Quaternion:
         """Pointwise cross product of three quaternions.

orix/tests/test_quaternion/test_orientation.py

@@ -311,6 +311,61 @@ def test_symmetry_property_wrong_number_of_values_misorientation(error_type, val
         o.symmetry = value
 
 
+def test_from_path_ends():
+    """check from_path_ends returns what you would expect and
+    preserves symmetry information.
+    In particular, ensure the class of the returned object matches the class
+    used for creating it, NOT the class of the object passed in.
+    """
+    q = Quaternion.random(10)
+    r = Rotation.random(10)
+    o = Orientation.random(10, Oh)
+    m = Misorientation.random(10, [D3, Oh])
+
+    # Quaternion sanity checks
+    a = Quaternion.from_path_ends(q)
+    assert isinstance(a, Quaternion)
+    b = Quaternion.from_path_ends(r)
+    assert isinstance(b, Quaternion)
+    c = Quaternion.from_path_ends(o)
+    assert isinstance(c, Quaternion)
+    d = Quaternion.from_path_ends(m)
+    assert isinstance(d, Quaternion)
+
+    # Rotation sanity checks
+    a = Rotation.from_path_ends(q)
+    assert isinstance(a, Rotation)
+    b = Rotation.from_path_ends(r)
+    assert isinstance(b, Rotation)
+    c = Rotation.from_path_ends(o)
+    assert isinstance(c, Rotation)
+    d = Rotation.from_path_ends(m)
+    assert isinstance(d, Rotation)
+
+    # Misorientation sanity checks
+    with pytest.raises(TypeError, match="Points must be a Misorientation"):
+        a = Misorientation.from_path_ends(q)
+    with pytest.raises(TypeError, match="Points must be a Misorientation"):
+        b = Misorientation.from_path_ends(r)
+    c = Misorientation.from_path_ends(o)
+    assert isinstance(c, Misorientation)
+    d = Misorientation.from_path_ends(m)
+    assert isinstance(d, Misorientation)
+    assert c.symmetry[1] == o.symmetry
+    assert d.symmetry == m.symmetry
+
+    # Orientation sanity checks
+    with pytest.raises(TypeError, match="Points must be an Orientation"):
+        a = Orientation.from_path_ends(q)
+    with pytest.raises(TypeError, match="Points must be an Orientation"):
+        b = Orientation.from_path_ends(r)
+    c = Orientation.from_path_ends(o)
+    assert c.symmetry == o.symmetry
+    assert isinstance(c, Orientation)
+    with pytest.raises(TypeError, match="Points must be an Orientation"):
+        d = Orientation.from_path_ends(m)
+
+
 class TestMisorientation:
     def test_get_distance_matrix(self):
         """Compute distance between every misorientation in an instance
@@ -811,6 +866,11 @@ def test_in_fundamental_region(self):
             region = np.radians(pg.euler_fundamental_region)
             assert np.all(np.max(ori.in_euler_fundamental_region(), axis=0) <= region)
 
+    def test_from_path_ends(self):
+        # generate paths with orientations to check symmetry copying
+        wp_o = Orientation(data=np.eye(4)[:2], symmetry=Oh)
+        assert Orientation.from_path_ends(wp_o)._symmetry == (C1, Oh)
+
     def test_inverse(self):
         O1 = Orientation([np.sqrt(2) / 2, np.sqrt(2) / 2, 0, 0], D6)
         O2 = ~O1

orix/tests/test_quaternion/test_quaternion.py

@@ -336,6 +336,33 @@ def test_equality(self):
         assert Q1 != Q2
         assert Q1 == Q2.inv()
 
+                [
+                    [1, 0, 0, 0],
+                    [1, 0, 0, 0],
+                    [1, 1, 0, 0],
+                    [1, 0, 1, 0],
+                    [1, 0, 0, 1],
+                    [1, 0, 0, 1],
+                    [-1, 0, 0, -1],
+                    [-1, 0, 0, 1],
+                ]
+            )
+        )
+        path = Quaternion.from_path_ends(waypoints)
+        loop = Quaternion.from_path_ends(waypoints, closed=True, steps=11)
+        path_spacing = [(x[1:]).dot(x[:-1]) for x in path.reshape(11, 100)]
+        loop_spacing = [(x[1:]).dot(x[:-1]) for x in loop.reshape(12, 11)]
+        assert np.all(np.std(path_spacing, axis=1) < 1e-12)
+        assert np.all(np.std(loop_spacing, axis=1) < 1e-12)
+
+    def test_from_path_ends_fiber(self):
+        # check that a linear path in quaternion space follows an explicitly defined
+        Q2 = Quaternion.from_axes_angles([1, 1, 1], 60, degrees=True)
+        Q12 = Quaternion.stack((Q1, Q2))
+        Q_path1 = Quaternion.from_axes_angles([1, 1, 1], np.arange(59), degrees=True)
+        Q_path2 = Quaternion.from_path_ends(Q12, steps=Q_path1.size)
+        assert np.allclose(Q_path1.dot(Q_path2), 1, atol=1e-3)
+
 
 class TestToFromEuler:
     """These tests address .to_euler() and .from_euler()."""