update changelog and cleanup example for from_path_ends

Author: argerlt

CHANGELOG.rst

@@ -34,6 +34,8 @@ Added
   An example of a custom projection is the :class:`~orix.plot.StereographicPlot`.
   This function replaces the previous behavior of relying on a side-effect of importing
   the :mod:`orix.plot` module, which also registered the projections.
+- :func:`~orix.quaternion.Rotation.from_path_ends` returns evenly spaced points
+  mapping the shortest path betwen two or more rotations.
 
 Changed
 -------

examples/plotting/paths_through_orientation_space.py renamed to examples/plotting/visualizing_crystallographic_paths.py

@@ -1,16 +1,22 @@
 r"""
 =========================================
- Plot Paths In Rotation and Vector Space
+Visualizing crystallographic paths
 =========================================
-This example shows how paths though either rotation or vector space
-can be plotted using ORIX. These are the shortest paths through their
-respective spaces, and thus not always straight lines in euclidean
-projections (axis-angle, stereographic, etc.).
+
+This example shows how define and plot paths through either
+rotation or vector space.This is akin to describing crystallographic
+fiber textures in metallurgy, or the shortest arcs connecting points on
+the surface of a unit sphere.
+
+In both cases, "shortest" is defined as the route that minimizes the
+movement required to transform from point to point, which is typically
+not a stright line when plotted into a euclidean projection
+(axis-angle, stereographic, etc.).
+
 This functionality is available in :class:`~orix.vector.Vector3d`,
 :class:`~orix.quaternions.Rotation`,
 :class:`~orix.quaternions.Orientation`,
-and :class:`~orix.quaternions.Misorientation`.
-"""
+and :class:`~orix.quaternions.Misorientation`."""
 
 from matplotlib import cm
 import matplotlib.pyplot as plt
@@ -31,16 +37,18 @@
 fig = plt.figure(figsize=(6, 6))
 n_steps = 30
 
-# ========= #
+# ============ #
 # Example 1: Plotting multiple paths into a user defined axis
-# ========= #
+
 # This subplot shows several paths through the cubic (m3m) fundamental zone
 # created by rotating 20 randomly chosen points 30 degrees around the z axis.
 # these paths are drawn in rodrigues space, which is an equal-angle projection
 # of rotation space. As such, notice how all lines tracing out axial rotations
 # are straight, but lines starting closer to the center of the fundamental zone
 # appear shorter.
+
 # the sampe paths are then also plotted on an Inverse Pole Figure (IPF) plot.
+
 rod_ax = fig.add_subplot(2, 2, 1, projection="rodrigues", proj_type="ortho")
 ipf_ax = fig.add_subplot(2, 2, 2, projection="ipf", symmetry=Oh)
 
@@ -86,20 +94,22 @@
 ipf_ax.set_title(r"IPF, multiple paths        ")
 
 
-# %%
-# ========= #
+# ============ #
 # Example 2: Plotting a path using `Rotation.scatter'
-# ========= #
 # This subplot traces the path of an object rotated 90 degrees around the
 # X axis, then 90 degrees around the Y axis.
+
 rots = Orientation.from_axes_angles(
     [[1, 0, 0], [1, 0, 0], [0, 1, 0]], [0, 90, 90], degrees=True, symmetry=C1
 )
 rots[2] = rots[1] * rots[2]
 path = Orientation.from_path_ends(rots, steps=n_steps)
 # create a list of RGBA color values for a gradient red line and blue line
 path_colors = np.vstack(
-    [cm.Reds(np.linspace(0.5, 1, n_steps)), cm.Blues(np.linspace(0.5, 1, n_steps))]
+    [
+        cm.Reds(np.linspace(0.5, 1, n_steps)),
+        cm.Blues(np.linspace(0.5, 1, n_steps)),
+    ]
 )
 
 # Here, we instead use the in-built plotting tool from
@@ -108,11 +118,10 @@
 path.scatter(figure=fig, position=[2, 2, 3], marker=">", c=path_colors)
 fig.axes[2].set_title(r"Axis-Angle, two $90^\circ$ rotations")
 
-# %%
 
-# ========= #
+# ============ #
 # Example 3: paths in stereographic plots
-# ========= #
+
 # This is similar to the second example, but now vectors are being rotated
 # 30 degrees around the [1,1,1] axis on a stereographic plot.
 

orix/quaternion/misorientation.py

@@ -277,33 +277,33 @@ def from_scipy_rotation(
     def from_path_ends(
         cls, points: Misorientation, closed: bool = False, steps: int = 100
     ) -> Misorientation:
-        """Return misorientations tracing the shortest path (ignoring
-        symmetry) between two or more consecutive points.
+        """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).
+            Two or more misorientations that define points along the
+            path.
         closed
-            Option to add a final trip from the last waypoint back to
+            Option to add a final trip from the last point 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.
+            Number of misorientations to return between each point
+            along the path defined by `points`. The default is 100.
 
         Returns
         -------
         path
-            misorientations that map a path between the given waypoints.
+            regularly spaced misorientations following the shortest
+            path.
 
-        Note
-        -------
-        This function traces a path between points in SO(3), in which there
-        is one and only one direct path between every point. The equivalent
-        is not well-defined for misorientations, which define multiple
-        symmetrically-equivalent points in SO(3) with non-equivalent paths
-        between them.
+        Notes
+        -----
+        This function traces the shortest path between points without
+        any regard to symmetry. Concept of "shortest path" is not
+        well-defined for misorientations, which can define multiple
+        symmetrically equivalent points with non-equivalent paths.
         """
         # Confirm `points` are misorientations.
         if type(points) is not cls:

orix/quaternion/orientation.py

@@ -356,33 +356,32 @@ def from_scipy_rotation(
     def from_path_ends(
         cls, points: Orientation, closed: bool = False, steps: int = 100
     ) -> Misorientation:
-        """Return orientations tracing the shortest path (ignoring
-        symmetry) between two or more consecutive points.
+        """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).
+            Two or more orientations that define points along the
+            path.
         closed
-            Option to add a final trip from the last waypoint back to
+            Option to add a final trip from the last point 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.
+            Number of orientations to return between each point
+            along the path defined by `points`. The default is 100.
 
         Returns
         -------
         path
-            orientations that map a path between the given waypoints.
+            regularly spaced orientations following the shortest path.
 
-        Note
-        -------
-        This function traces a path between points in SO(3), in which there
-        is one and only one direct path between every point. The equivalent
-        is not well-defined for orientations, which define multiple
-        symmetrically-equivalent points in SO(3) with non-equivalent paths
-        between them.
+        Notes
+        -----
+        This function traces the shortest path between points without
+        any regard to symmetry. Concept of "shortest path" is not
+        well-defined for orientations, which can define multiple
+        symmetrically equivalent points with non-equivalent paths.
         """
         if type(points) is not cls:
             raise TypeError(

orix/quaternion/quaternion.py

@@ -697,21 +697,22 @@ def from_path_ends(
     ) -> 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).
+            Two or more quaternions that define points along the path.
         closed
-            Option to add a final trip from the last waypoint back to
+            Option to add a final trip from the last point 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.
+            Number of quaternions to return between each point along
+            the path defined by `points`. The default is 100.
+
         Returns
         -------
         path
-            quaternions that map a path between the given waypoints.
+            regularly spaced quaternions following the shortest path.
         """
         points = points.flatten()
         n = points.size