including suggestions and updating example

Author: argerlt

examples/plotting/plot_non_euclidean_paths.py

@@ -1,83 +1,115 @@
 r"""
-========================
-Plot symmetry operations
-========================
+========================================
+Plot Paths Through Non-Euclidean Spaces
+========================================
 
-This example shows how to use the `from_path_ends` functions from
-:class:`~orix.vector.Vector3d`, :class:`~orix.quaternions.Rotation`, and
-:class:`~orix.quaternions.Orientation` to draw paths through thier
-respective non-Euclidean spaces.
+This example shows three variations on how 'from_path_ends' can be
+used to plot paths between points in rotational and vector spaces.
+
+This functionality is available in :class:`~orix.vector.Vector3d`,
+:class:`~orix.quaternions.Rotation`,
+:class:`~orix.quaternions.Orientation`,
+and :class:`~orix.quaternions.Misorientation`.
 """
 
 import matplotlib.pyplot as plt
+from matplotlib import cm
 import numpy as np
 
-from orix.quaternion import Orientation, Rotation
+from orix.quaternion import Misorientation, Orientation, Rotation
 from orix.quaternion.symmetry import D3, Oh
 from orix.vector import Vector3d
 
-fig = plt.figure()
+fig = plt.figure(figsize=(4, 8))
 
-# plot a path in homochoric space with no symmetry
-rot_path = Rotation(
+# ========= #
+# Example 1: Plotting a path of rotations with no symmetry in homochoric space
+# ========= #
+rots_along_path = Rotation(
     data=np.array(
         [
             [1, 0, 0, 0],
-            [1, 1, 0, 0],
-            [1, 0, 1, 0],
             [1, 0, 0, 1],
-            [1, 0, -1, 0],
-            [1, 0, 0, -1],
-            [1, 0, 0, -1],
+            [1, 1, 1, 1],
         ]
     )
 )
-rotation_path = Rotation.from_path_ends(rot_path, closed=True)
-# cast the rotation to a symmetry-less orientation for plotting purposes
-Orientation(rotation_path).scatter(
-    figure=fig, position=[2, 2, 1], marker=">", c=np.arange(700)
-)
+n_steps = 20
+rotation_path = Rotation.from_path_ends(rots_along_path, steps=n_steps)
+# create an Orientation loop using this path with no symmetry elements
+ori_path = Orientation(rotation_path)
+# plot the path in homochoric space
+segment_colors = cm.inferno(np.linspace(0, 1, n_steps))
 
-# plot a path in rodrigues space with m-3m (cubic) symmetry.
-m3m_path = Orientation(
+path_colors = np.vstack([segment_colors for x in range(rots_along_path.size - 1)])
+ori_path.scatter(figure=fig, position=[3, 1, 1], marker=">", c=path_colors)
+fig.axes[0].set_title(r"$90^\circ$ rotation around X, then Y")
+
+# ========= #
+# Example 2: Plotting the rotation of several orientations in m3m Rodrigues
+# space around the z axis.
+# ========= #
+oris = Orientation(
     data=np.array(
         [
-            [1, 0, 0, 0],
-            [2, 1, 0, 0],
-            [3, 0, 1, 0],
-            [4, 0, 0, 1],
-            [5, 0, -1, 0],
-            [6, 0, 0, -1],
-            [7, 0, 0, -1],
-            [8, 1, 0, 0],
-            [9, 0, 1, 0],
-            [10, 0, 0, 1],
-            [11, 0, -1, 0],
-            [12, 0, 0, -1],
-            [13, 0, 0, -1],
+            [0.69, 0.24, 0.68, 0.01],
+            [0.26, 0.59, 0.32, 0.7],
+            [0.07, 0.17, 0.93, 0.31],
+            [0.6, 0.03, 0.61, 0.52],
+            [0.51, 0.38, 0.34, 0.69],
+            [0.31, 0.86, 0.22, 0.35],
+            [0.68, 0.67, 0.06, 0.31],
+            [0.01, 0.12, 0.05, 0.99],
+            [0.39, 0.45, 0.34, 0.72],
+            [0.65, 0.59, 0.46, 0.15],
         ]
     ),
     symmetry=Oh,
+).reduce()
+# define a 20 degree rotation around the z axis
+shift = Orientation.from_axes_angles([0, 0, 1], np.pi / 9)
+segment_colors = cm.inferno(np.linspace(0, 1, 10))
+
+ori_paths = []
+for ori in oris:
+    shifted = (shift * ori).reduce()
+    to_from = Orientation.stack([ori, shifted]).flatten()
+    ori_paths.append(Orientation.from_path_ends(to_from, steps=10))
+# plot a path in roddrigues space with m-3m (cubic) symmetry.
+ori_path = Orientation.stack(ori_paths).flatten()
+ori_path.symmetry = Oh
+ori_path.scatter(
+    figure=fig,
+    position=[3, 1, 2],
+    marker=">",
+    c=np.tile(segment_colors, [10, 1]),
+    projection="rodrigues",
 )
-orientation_path = Orientation.from_path_ends(m3m_path.reduce(), closed=True).reduce()
-orientation_path.scatter(figure=fig, position=[2, 2, 2], marker=">", c=np.arange(1300))
+fig.axes[1].set_title(r"$20^{\circ}$ rotations around X-axis in m3m")
 
-# plot a second path in rodrigues space with symmetry, but while also crossing a
-# symmetry boundary
-fiber_start = Rotation.identity(1)
-fiber_middle = Rotation.from_axes_angles([1, 2, 3], np.pi)
-fiber_end = Rotation.from_axes_angles([1, 2, 3], 2 * np.pi)
-fiber_points = Orientation.stack([fiber_start, fiber_middle, fiber_end])
-fiber_points.symmetry = Oh
-fiber_path = Orientation.from_path_ends(fiber_points, closed=False).reduce()
-fiber_path.scatter(figure=fig, position=[2, 2, 3], marker=">", c=np.arange(200))
+# ========= #
+# Example 3: creating a customized Wulf Plotting the rotation of several orientations in m3m Rodrigues
+# space around the z axis.
+# ========= #
 
 
 # plot vectors
-ax4 = plt.subplot(2, 2, 4, projection="stereographic")
-vector_points = Vector3d(
-    np.array([[-1, 0, 0], [0, 1, 0.1], [1, 0, 0.2], [0, -1, 0.3], [-1, 0, 0.4]])
-)
+ax_upper = plt.subplot(3, 1, 3, projection="stereographic", hemisphere="upper")
+r90x = Rotation.from_axes_angles([1, -1, -1], [0, 60], degrees=True)
+x_axis_points = r90x * Vector3d.xvector()
+y_axis_points = r90x * Vector3d.yvector()
+z_axis_points = r90x * Vector3d.zvector()
+
+x_axis_path = Vector3d.from_path_ends(x_axis_points.unique())
+y_axis_path = Vector3d.from_path_ends(y_axis_points.unique())
+z_axis_path = Vector3d.from_path_ends(z_axis_points.unique())
+cx = cm.Reds(np.linspace(0.1, 1, x_axis_path.size))
+cy = cm.Greens(np.linspace(0.1, 1, y_axis_path.size))
+cz = cm.Blues(np.linspace(0.1, 1, z_axis_path.size))
+
+spx = ax_upper.scatter(x_axis_path, figure=fig, marker=">", c=cx, label="X")
+spy = ax_upper.scatter(y_axis_path, figure=fig, marker=">", c=cy, label="Y")
+spz = ax_upper.scatter(z_axis_path, figure=fig, marker=">", c=cz, label="Z")
+ax_upper.legend(loc="lower center", ncols=3)
 
-vector_path = Vector3d.from_path_ends(vector_points, steps=200)
-ax4.scatter(vector_path, figure=fig, marker=">", c=np.arange(vector_path.size))
+plt.tight_layout()

orix/quaternion/misorientation.py

@@ -270,31 +270,35 @@ def from_scipy_rotation(
     def from_path_ends(
         cls, points: Misorientation, closed: bool = False, steps: int = 100
     ) -> Misorientation:
-        """Return (mis)orientations tracing the shortest path between
+        """Return misorientations tracing the shortest path between
         two or more consecutive points.
 
         Parameters
         ----------
         points
-            Two or more (mis)orientations that define waypoints along
+            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 (mis)orientations to return along the path
+            Number of misorientations 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.
+            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)
-        # copy the symmetry if it exists.
-        if hasattr(points, "_symmetry"):
-            path._symmetry = points._symmetry
+        path._symmetry = points._symmetry
         return path
 
     @classmethod

orix/quaternion/orientation.py

@@ -346,6 +346,41 @@ 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: Union[int, tuple] = 1, symmetry: Optional[Symmetry] = None

orix/tests/quaternion/test_orientation.py

@@ -333,25 +333,48 @@ def test_from_path_ends():
     o = Orientation.random(10, Oh)
     m = Misorientation.random(10, [D3, Oh])
 
-    # make sure the result is the correct class.
+    # Quaternion sanity checks
     a = Quaternion.from_path_ends(q)
-    b = Rotation.from_path_ends(q)
-    c = Orientation.from_path_ends(r)
-    d = Quaternion.from_path_ends(o)
-    e = Orientation.from_path_ends(q)
-    f = Misorientation.from_path_ends(m)
-    g = Orientation.from_path_ends(o)
     assert isinstance(a, Quaternion)
-    assert isinstance(b, Rotation)
-    assert isinstance(c, Orientation)
+    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)
-    assert isinstance(e, Orientation)
-    assert isinstance(f, Misorientation)
-    assert isinstance(g, Orientation)
 
-    # make sure symmetry information is preserved.
-    assert f.symmetry == m.symmetry
-    assert g.symmetry == o.symmetry
+    # 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: