pyextal.acom.plotting
=====================

.. py:module:: pyextal.acom.plotting

.. autoapi-nested-parse::

   Visualising an orientation solve.

   Two views: the indexed pattern itself, and a symmetry-reduced map of how every
   candidate zone axis scored. The second matters because the orientation is only
   ever determined up to the Laue symmetry of the crystal -- plotting the raw
   candidate list shows the same solution several times over, which reads as
   ambiguity that is not really there.



Functions
---------

.. autoapisummary::

   pyextal.acom.plotting.symmetry_operators
   pyextal.acom.plotting.reduce_zone
   pyextal.acom.plotting.stereographic
   pyextal.acom.plotting.plot_zone_map
   pyextal.acom.plotting.plot_indexed


Module Contents
---------------

.. py:function:: symmetry_operators()

   Rotation parts of the crystal's symmetry operators, plus inversion.

   Read from the Fortran `spgr` common block, so the space group must already
   have been parsed. Inversion is appended when the group is centrosymmetric,
   which is what makes the map a Laue-symmetry map rather than a point-group one.

   :returns: (n, 3, 3) integer rotation matrices.
   :rtype: np.ndarray

   :raises ValueError: If no space group has been parsed yet.


.. py:function:: reduce_zone(uvw, ops, D=None)

   Canonical representative of a zone axis under the symmetry.

   With a direct-space frame the representative is the equivalent pointing
   furthest along +z, then +y, then +x, which for a cubic crystal lands
   <100> on [001] and <110> on [011] -- the usual inverse-pole-figure triangle.
   Without one the lexicographic maximum is used, which groups correctly but
   scatters the representatives around the projection.

   :param uvw: Zone axis, direct-space indices.
   :type uvw: array-like
   :param ops: (n, 3, 3) symmetry rotations.
   :type ops: np.ndarray
   :param D: Direct basis matrix from `cartesian_frames`.
   :type D: np.ndarray, optional

   :returns: The group label.
   :rtype: tuple[int, int, int]


.. py:function:: stereographic(vectors)

   Stereographic projection of unit vectors from the southern pole.

   :param vectors: (n, 3) Cartesian vectors; need not be normalised.
   :type vectors: np.ndarray

   :returns: (n, 2) projected coordinates inside the unit circle.
   :rtype: np.ndarray


.. py:function:: plot_zone_map(result, param, ax=None, annotate=6, cmap='viridis', show_all=False)

   Plots candidate zone axes on a symmetry-reduced stereographic map.

   Every zone axis in `result.ranking` is folded onto its symmetry
   representative and the best score of each group is kept, so a cubic crystal
   shows one point for <100> rather than three. Zones in `result.failed`, tried
   but left without a mapping, are drawn as grey crosses so the map shows every
   axis the search tested.

   A wide search packs its axes closely: to index 15 a cubic crystal gives 624
   distinct orientations inside the fundamental triangle, and neighbouring
   high-index axes sit a fraction of a degree apart. The view is zoomed to the
   region the points occupy, and each marker is sized to its nearest neighbour,
   so close axes stay separate instead of hiding under one another.

   :param result: A solved orientation carrying `ranking`.
   :type result: AcomResult
   :param param: Parsed parameters, for the direct-space frame.
   :type param: SimParams
   :param ax: Axes to draw on; created if None.
   :type ax: matplotlib.axes.Axes, optional
   :param annotate: Label this many top groups. Defaults to 6.
   :type annotate: int, optional
   :param cmap: Colormap for the score. Defaults to 'viridis'.
   :type cmap: str, optional
   :param show_all: Draw every equivalent instead of reducing.
                    Defaults to False.
   :type show_all: bool, optional

   :returns: ``(ax, groups)`` where `groups` maps representative zone to score.
   :rtype: tuple


.. py:function:: plot_indexed(image, result, ax=None, max_label=12, vmax_pct=99.5, include_holz=True)

   Overlays the indexed reflections on the diffraction pattern.

   Predicted reflections are drawn whether or not a peak was detected there,
   which is the point: the weak ones are exactly what a peak finder misses and
   what the integration still needs.

   :param image: The averaged pattern that was indexed.
   :type image: np.ndarray
   :param result: The solved orientation.
   :type result: AcomResult
   :param ax: Axes to draw on.
   :type ax: matplotlib.axes.Axes, optional
   :param max_label: Label this many of the strongest predicted
                     reflections. Defaults to 12.
   :type max_label: int, optional
   :param vmax_pct: Display ceiling percentile. Defaults to 99.5.
   :type vmax_pct: float, optional
   :param include_holz: Include HOLZ. Defaults to True.
   :type include_holz: bool, optional

   :returns: The axes drawn on.
   :rtype: matplotlib.axes.Axes