midas-plotting 0.4.0__tar.gz → 0.5.0__tar.gz

{midas_plotting-0.4.0 → midas_plotting-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: midas-plotting
-Version: 0.4.0
+Version: 0.5.0
 Summary: Standard plots for MIDAS reconstructions - near-field, far-field and Laue: IPF maps and legends, grain maps, pole figures, strain and size distributions, and Laue texture diagnostics against their chance levels.
 Author-email: Hemant Sharma <hsharma@anl.gov>
 License: BSD-3-Clause

{midas_plotting-0.4.0 → midas_plotting-0.5.0}/midas_plotting/__init__.py

@@ -48,7 +48,7 @@ from .solutions import (
 )
 from .mic import MicMap, read_mic
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __all__ = [
     "MicMap", "read_mic", "GrainList", "read_grains", "ff", "laue",
     "LaueSolutions", "LaueSpots", "read_solutions", "read_spots",

{midas_plotting-0.4.0 → midas_plotting-0.5.0}/midas_plotting/ff.py

@@ -26,7 +26,8 @@ from typing import Optional, Sequence
 import numpy as np
 
 from .grains import GrainList, read_grains
-from .ipf import direction_rgb, ipf_rgb_from_matrix, laue_class, sym_matrices, CUBIC
+from .ipf import (direction_rgb, ipf_rgb_from_matrix, laue_class, sym_matrices,
+                  sector_deg, triangle_corners, CUBIC)
 
 __all__ = [
     "ipf_legend", "grain_map", "grain_map_3d", "grain_size_distribution",
@@ -96,11 +97,13 @@ def ipf_legend(space_group: int = 225, ax=None, *, n: int = 400,
 
     fam = laue_class(space_group)
     # Sample the stereographic plane, back-project to directions, keep the ones
-    # already inside the standard triangle.
-    if fam == CUBIC:
-        corners = np.array([[0, 0, 1.0], [1, 0, 1.0], [1, 1, 1.0]])
-    else:
-        corners = np.array([[0, 0, 1.0], [1, 0, 0.0], [np.sqrt(3) / 2, 0.5, 0.0]])
+    # already inside the standard triangle. Corners and the azimuthal sector
+    # come from midas_plotting.ipf, the SAME source the colour ramps fold by,
+    # so the key cannot describe a different triangle from the one drawn. The
+    # `else` branch here used to hard-code the 30 deg hexagonal triangle, which
+    # would have drawn a hexagonal key over a 4/mmm map once the tetragonal and
+    # orthorhombic triangles were added.
+    corners, labels = triangle_corners(space_group)
     # Normalise BEFORE projecting: the stereographic map is defined on unit
     # vectors. Projecting the raw index triple puts [111] at (0.5, 0.5)
     # instead of (0.366, 0.366), so the corner marker and its label sit
@@ -122,7 +125,8 @@ def ipf_legend(space_group: int = 225, ax=None, *, n: int = 400,
                  (d[:, 1] <= d[:, 0] + 1e-9) & (d[:, 0] <= d[:, 2] + 1e-9)
     else:
         az = np.degrees(np.arctan2(d[:, 1], d[:, 0]))
-        inside = (d[:, 2] >= -1e-9) & (az >= -1e-9) & (az <= 30.0 + 1e-9)
+        inside = (d[:, 2] >= -1e-9) & (az >= -1e-9) & \
+                 (az <= sector_deg(space_group) + 1e-9)
 
     rgb = np.ones((d.shape[0], 3))
     if inside.any():
@@ -132,8 +136,6 @@ def ipf_legend(space_group: int = 225, ax=None, *, n: int = 400,
 
     ax.imshow(img, origin="lower", alpha=alpha,
               extent=(x0, x1, y0, y1))
-    labels = (["[001]", "[101]", "[111]"] if fam == CUBIC
-              else ["[0001]", r"[10$\bar{1}$0]", r"[2$\bar{1}\bar{1}$0]"])
     for (px, py), lab in zip(zip(cx, cy), labels):
         ax.plot(px, py, "k.", ms=4)
         ax.annotate(lab, (px, py), textcoords="offset points",

midas_plotting-0.5.0/midas_plotting/ipf.py

@@ -0,0 +1,346 @@
+"""Inverse-pole-figure colouring.
+
+Colour encodes which crystal direction is parallel to a chosen sample axis, so
+one grain is one colour and boundaries appear as colour discontinuities. That is
+the property an Euler-to-RGB dump does NOT have: two orientations a fraction of
+a degree apart can land on very different Euler triplets (and hence very
+different colours) near the gimbal-lock line, which makes a single grain look
+like several.
+
+Symmetry operators come from :mod:`midas_stress`, never hand-listed here.
+"""
+from __future__ import annotations
+
+from typing import Sequence
+
+import math
+import numpy as np
+
+__all__ = ["ipf_rgb", "ipf_rgb_from_matrix", "direction_rgb", "laue_class",
+           "sym_matrices", "sector_deg", "triangle_corners",
+           "CUBIC", "HEXAGONAL", "TRIGONAL", "TETRAGONAL", "ORTHORHOMBIC"]
+
+CUBIC = "cubic"
+TETRAGONAL = "tetragonal"
+ORTHORHOMBIC = "orthorhombic"
+HEXAGONAL = "hexagonal"
+TRIGONAL = "trigonal"
+
+# Laue class per space-group range, for the ones MIDAS actually reconstructs.
+# Deliberately explicit rather than clever: a wrong guess here silently
+# recolours a map without any other symptom.
+#
+# The ranges are LAUE CLASSES, not crystal systems, and the two do not coincide
+# in the tetragonal case: 89-142 is 4/mmm, whose triangle closes at 45 deg on
+# [110], while 75-88 is 4/m, which has no in-plane mirror and whose triangle
+# spans the full 90 deg to [010]. Colouring a 4/m crystal with the 4/mmm
+# triangle folds by a 2-fold it does not have, so 75-88 is left OUT and refuses
+# rather than guessing. Implement `_rgb_tetragonal_4m` before widening it.
+_SG_LAUE = [
+    (195, 230, CUBIC),
+    (168, 194, HEXAGONAL),
+    (143, 167, TRIGONAL),
+    (89, 142, TETRAGONAL),      # 4/mmm only -- see the note above
+    (16, 74, ORTHORHOMBIC),
+]
+
+
+def laue_class(space_group: int) -> str:
+    """Laue family used for the IPF triangle.
+
+    Raises for space groups whose triangle is not implemented, rather than
+    falling back to cubic -- a silent fallback would produce a plausible-looking
+    but meaningless map.
+    """
+    for lo, hi, name in _SG_LAUE:
+        if lo <= int(space_group) <= hi:
+            return name
+    raise NotImplementedError(
+        f"IPF colouring for space group {space_group} is not implemented "
+        f"(have: cubic 195-230, hexagonal 168-194, trigonal 143-167, "
+        f"tetragonal 4/mmm 89-142, orthorhombic 16-74). Refusing to guess. "
+        f"Note 75-88 is Laue class 4/m, whose triangle spans 90 deg, not the "
+        f"45 deg of 4/mmm; it is deliberately not implemented."
+    )
+
+
+def sym_matrices(space_group: int) -> np.ndarray:
+    """``(n_sym, 3, 3)`` proper-rotation operators from midas_stress."""
+    from midas_stress.orientation import make_symmetries, quat_to_orient_mat
+
+    n, quats = make_symmetries(int(space_group))
+    q = np.asarray(quats)[: int(n)]
+    return np.stack([np.asarray(quat_to_orient_mat(qi)).reshape(3, 3) for qi in q])
+
+
+def _reduce_cubic(d: np.ndarray) -> np.ndarray:
+    """Fold directions into the standard [001]-[101]-[111] triangle."""
+    d = np.abs(d)
+    d = np.sort(d, axis=-1)                     # u <= v <= w
+    return d
+
+
+def _rgb_cubic(d: np.ndarray) -> np.ndarray:
+    u, v, w = d[:, 0], d[:, 1], d[:, 2]
+    rgb = np.stack([w - v, (v - u) * np.sqrt(2.0), u * np.sqrt(3.0)], axis=1)
+    return rgb
+
+
+
+def _rgb_tetragonal(d: np.ndarray) -> np.ndarray:
+    """Standard [001]-[100]-[110] triangle for Laue class 4/mmm.
+
+    Same construction as :func:`_rgb_hexagonal`: red is the c-axis component,
+    and the in-plane azimuth interpolates green -> blue across the triangle's
+    angular width, here 45 degrees rather than 30. Added for I4/mmm (SG 139),
+    the Ruddlesden-Popper subcell — before this the function raised, which was
+    correct: colouring a tetragonal crystal with the cubic triangle folds by a
+    3-fold the crystal does not have.
+    """
+    dz = np.abs(d[:, 2])
+    planar = np.hypot(d[:, 0], d[:, 1])
+    phi = np.degrees(np.arctan2(np.abs(d[:, 1]), np.abs(d[:, 0])))
+    phi = np.minimum(phi % 90.0, 90.0 - (phi % 90.0))      # fold to [0, 45]
+    t = np.clip(phi / 45.0, 0.0, 1.0)
+    return np.stack([dz, planar * (1.0 - t), planar * t], axis=1)
+
+
+def _rgb_orthorhombic(d: np.ndarray) -> np.ndarray:
+    """Standard [001]-[100]-[010] triangle for Laue class mmm.
+
+    The triangle spans a full 90 degrees of azimuth because mmm has no
+    in-plane rotation relating a to b. Added for Fmmm (SG 69).
+    """
+    dz = np.abs(d[:, 2])
+    planar = np.hypot(d[:, 0], d[:, 1])
+    phi = np.degrees(np.arctan2(np.abs(d[:, 1]), np.abs(d[:, 0])))
+    t = np.clip(phi / 90.0, 0.0, 1.0)
+    return np.stack([dz, planar * (1.0 - t), planar * t], axis=1)
+
+
+def _rgb_hexagonal(d: np.ndarray) -> np.ndarray:
+    """Standard [0001]-[10-10]-[2-1-10] triangle.
+
+    ``d`` is Cartesian with c along +z. After symmetry reduction the
+    representative has ``dz >= 0`` and azimuth in ``[0, 30]`` degrees.
+    """
+    dz = np.abs(d[:, 2])
+    planar = np.hypot(d[:, 0], d[:, 1])
+    phi = np.degrees(np.arctan2(np.abs(d[:, 1]), np.abs(d[:, 0])))
+    phi = np.minimum(phi % 60.0, 60.0 - (phi % 60.0))     # fold to [0, 30]
+    t = np.clip(phi / 30.0, 0.0, 1.0)
+    return np.stack([dz, planar * (1.0 - t), planar * t], axis=1)
+
+
+def _trigonal_sector_deg(sym: np.ndarray) -> float:
+    """Azimuthal fundamental-sector width, measured from the operators.
+
+    Counts the distinct upper-hemisphere azimuths a generic direction is sent
+    to by the group plus the Laue centre. For -3m that is 6 images, so 60 deg
+    -- twice the hexagonal 30. Measured rather than hard-coded so a change in
+    the operator set cannot silently mis-scale the colour ramp.
+    """
+    g = np.array([0.3411, 0.1297, 0.4271])       # generic, no special azimuth
+    g = g / np.linalg.norm(g)
+    both = np.concatenate([sym @ g, -(sym @ g)], axis=0)
+    up = both[both[:, 2] >= -1e-12]
+    phi = np.sort(np.degrees(np.arctan2(up[:, 1], up[:, 0])) % 360.0)
+    keep = [phi[0]]
+    for a in phi[1:]:
+        if a - keep[-1] > 1e-6:
+            keep.append(a)
+    return 360.0 / len(keep)
+
+
+def _rgb_trigonal(d_all: np.ndarray, sym: np.ndarray) -> np.ndarray:
+    """Standard [0001]-[10-10]-[01-10] triangle for Laue class -3m.
+
+    D3 has 6 proper rotations (3-fold about c, three 2-fold in the basal
+    plane) against 6/mmm's 12, so the sector spans 60 deg, not 30. Colouring
+    R-3m with the hexagonal triangle folds by a 6-fold axis the crystal does
+    not have and silently gives distinct orientations the same colour.
+
+    The azimuth is NOT hand-folded. Where MIDAS puts the 2-fold axes is a
+    convention, and assuming one sits at azimuth 0 gives a colouring that is
+    not symmetry invariant (measured: colour moved by up to 0.99 under
+    ``g -> S.g``). Instead take the whole orbit, add ``-d`` for the Laue
+    centre, keep the upper hemisphere and pick the smallest azimuth --
+    canonical whatever the operator convention.
+
+    ``d_all`` is ``(n, n_sym, 3)``, every symmetry image of each direction.
+    """
+    both = np.concatenate([d_all, -d_all], axis=1)              # (n, 2s, 3)
+    phi = np.degrees(np.arctan2(both[:, :, 1], both[:, :, 0])) % 360.0
+    phi = np.where(both[:, :, 2] >= -1e-12, phi, np.inf)        # upper only
+    k = np.argmin(phi, axis=1)
+    idx = np.arange(both.shape[0])
+    rep, phi_c = both[idx, k], phi[idx, k]
+    phi_c = np.where(np.isfinite(phi_c), phi_c, 0.0)
+    rep = rep / np.linalg.norm(rep, axis=1, keepdims=True)
+
+    dz = np.abs(rep[:, 2])
+    planar = np.hypot(rep[:, 0], rep[:, 1])
+    t = np.clip(phi_c / _trigonal_sector_deg(sym), 0.0, 1.0)
+    return np.stack([dz, planar * (1.0 - t), planar * t], axis=1)
+
+
+def ipf_rgb(
+    euler: np.ndarray,
+    space_group: int = 225,
+    axis: Sequence[float] = (0.0, 0.0, 1.0),
+    *,
+    gamma: float = 0.5,
+) -> np.ndarray:
+    """RGB per orientation for the crystal direction parallel to ``axis``.
+
+    Parameters
+    ----------
+    euler : (N, 3) array
+        Bunge ZXZ Euler angles in **radians** -- the MIDAS ``.mic`` convention.
+    space_group : int
+        Used for the symmetry operators and to pick the triangle.
+    axis : length-3
+        Sample-frame direction. ``(0,0,1)`` gives the usual IPF-Z.
+    gamma : float
+        Perceptual lift applied as ``rgb ** gamma``. 0.5 (sqrt) matches the
+        common convention; 1.0 disables it.
+
+    Returns
+    -------
+    (N, 3) float array in [0, 1].
+    """
+    from midas_stress.orientation import euler_to_orient_mat_batch
+
+    euler = np.asarray(euler, dtype=float).reshape(-1, 3)
+    if euler.size == 0:
+        return np.zeros((0, 3))
+    g = np.asarray(euler_to_orient_mat_batch(euler)).reshape(-1, 3, 3)
+    return ipf_rgb_from_matrix(g, space_group, axis, gamma=gamma)
+
+
+def ipf_rgb_from_matrix(
+    orient_mat: np.ndarray,
+    space_group: int = 225,
+    axis: Sequence[float] = (0.0, 0.0, 1.0),
+    *,
+    gamma: float = 0.5,
+) -> np.ndarray:
+    """RGB per orientation, from ``(N, 3, 3)`` orientation matrices.
+
+    The same colouring as :func:`ipf_rgb`, entered from the matrix rather than
+    from Euler angles. Far-field ``Grains.csv`` carries both (``O11..O33`` and
+    ``Eul0..2``); this avoids a needless matrix -> Euler -> matrix round trip,
+    which is lossy near the gimbal-lock configurations of the ZXZ convention.
+    """
+    g = np.asarray(orient_mat, dtype=float).reshape(-1, 3, 3)
+    if g.size == 0:
+        return np.zeros((0, 3))
+
+    a = np.asarray(axis, dtype=float)
+    n = np.linalg.norm(a)
+    if n == 0:
+        raise ValueError("axis must be non-zero")
+    a = a / n
+
+    # TRANSPOSE. MIDAS orientation matrices map CRYSTAL -> LAB (v_lab = g v_crystal),
+    # so the crystal direction parallel to the sample axis `a` is g^T a, not g a.
+    # This is not cosmetic: with g a, the colour is NOT symmetry-invariant for this
+    # convention -- the 24 equally valid representations of one grain spread over
+    # 0.96 in RGB, so a map's colour depended on which variant the indexer happened
+    # to store. Two grains agreeing to 0.5 deg came out 0.42 apart in RGB.
+    # Fixed 2026-09-03; see tests::test_ipf_colour_is_symmetry_invariant.
+    d = np.einsum("nji,j->ni", g, a)                 # crystal dir of the axis = g^T a
+    return direction_rgb(d, space_group, gamma=gamma)
+
+
+def direction_rgb(
+    dirs: np.ndarray, space_group: int = 225, *, gamma: float = 0.5,
+) -> np.ndarray:
+    """RGB for **crystal directions** -- the colouring core.
+
+    ``dirs`` is ``(N, 3)`` in crystal coordinates; it is normalised here.
+    Both :func:`ipf_rgb` and the legend drawn by
+    ``midas_plotting.ff.ipf_legend`` go through this, so the key on a figure
+    is guaranteed to match the colours in the map beside it. A legend computed
+    by a separate copy of the triangle maths is a legend that eventually lies.
+    """
+    d = np.asarray(dirs, dtype=float).reshape(-1, 3)
+    if d.size == 0:
+        return np.zeros((0, 3))
+    nrm = np.linalg.norm(d, axis=1, keepdims=True)
+    d = np.divide(d, nrm, out=np.zeros_like(d), where=nrm > 0)
+
+    fam = laue_class(space_group)
+    sym = sym_matrices(space_group)
+    d = np.einsum("sij,nj->nsi", sym, d)             # every equivalent
+
+    if fam == CUBIC:
+        red = _reduce_cubic(d)
+        pick = np.argmax(red[:, :, 2], axis=1)       # closest to [001]
+        red = red[np.arange(red.shape[0]), pick]
+        red /= np.linalg.norm(red, axis=1, keepdims=True)
+        rgb = _rgb_cubic(red)
+    elif fam == TRIGONAL:
+        rgb = _rgb_trigonal(d, sym)
+    elif fam in (TETRAGONAL, ORTHORHOMBIC):
+        dd = d.copy()
+        dd[:, :, 2] = np.abs(dd[:, :, 2])
+        pick = np.argmax(dd[:, :, 2], axis=1)          # closest to [001]
+        red = dd[np.arange(dd.shape[0]), pick]
+        red /= np.linalg.norm(red, axis=1, keepdims=True)
+        rgb = (_rgb_tetragonal(red) if fam == TETRAGONAL
+               else _rgb_orthorhombic(red))
+    else:
+        dd = d.copy()
+        dd[:, :, 2] = np.abs(dd[:, :, 2])
+        pick = np.argmax(dd[:, :, 2], axis=1)        # closest to [0001]
+        red = dd[np.arange(dd.shape[0]), pick]
+        red /= np.linalg.norm(red, axis=1, keepdims=True)
+        rgb = _rgb_hexagonal(red)
+
+    rgb = np.clip(rgb, 0.0, None)
+    mx = rgb.max(axis=1, keepdims=True)
+    rgb = np.where(mx > 0, rgb / mx, rgb)
+    return np.clip(rgb ** float(gamma), 0.0, 1.0)
+
+def sector_deg(space_group: int) -> float:
+    """Azimuthal width of the standard triangle, in degrees.
+
+    The SAME number the colour ramps fold by, so a legend built from this
+    cannot disagree with the map it explains. Cubic is excluded: its triangle
+    closes on [111], not on an in-plane direction, so an azimuth does not
+    describe it.
+    """
+    fam = laue_class(space_group)
+    if fam == CUBIC:
+        raise ValueError("the cubic triangle is not defined by an azimuth; "
+                         "its third corner is [111]")
+    if fam == TETRAGONAL:
+        return 45.0
+    if fam == ORTHORHOMBIC:
+        return 90.0
+    if fam == HEXAGONAL:
+        return 30.0
+    if fam == TRIGONAL:
+        return _trigonal_sector_deg(sym_matrices(space_group))
+    raise NotImplementedError(f"no triangle implemented for {fam}")
+
+
+def triangle_corners(space_group: int):
+    """``(corners, labels)`` for the standard triangle of this Laue class.
+
+    Cubic closes on [111]; every other implemented class is
+    [001] - [100] - (the in-plane direction at :func:`sector_deg`).
+    """
+    fam = laue_class(space_group)
+    if fam == CUBIC:
+        return (np.array([[0., 0., 1.], [1., 0., 1.], [1., 1., 1.]]),
+                ["[001]", "[101]", "[111]"])
+    phi = math.radians(sector_deg(space_group))
+    corners = np.array([[0., 0., 1.], [1., 0., 0.],
+                        [math.cos(phi), math.sin(phi), 0.]])
+    lab = {TETRAGONAL:   ["[001]", "[100]", "[110]"],
+           ORTHORHOMBIC: ["[001]", "[100]", "[010]"],
+           HEXAGONAL:    ["[0001]", r"[10$\bar{1}$0]", r"[2$\bar{1}\bar{1}$0]"],
+           TRIGONAL:     ["[0001]", r"[10$\bar{1}$0]", r"[01$\bar{1}$0]"]}[fam]
+    return corners, lab

{midas_plotting-0.4.0 → midas_plotting-0.5.0}/midas_plotting.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: midas-plotting
-Version: 0.4.0
+Version: 0.5.0
 Summary: Standard plots for MIDAS reconstructions - near-field, far-field and Laue: IPF maps and legends, grain maps, pole figures, strain and size distributions, and Laue texture diagnostics against their chance levels.
 Author-email: Hemant Sharma <hsharma@anl.gov>
 License: BSD-3-Clause

{midas_plotting-0.4.0 → midas_plotting-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "midas-plotting"
-version = "0.4.0"
+version = "0.5.0"
 description = "Standard plots for MIDAS reconstructions - near-field, far-field and Laue: IPF maps and legends, grain maps, pole figures, strain and size distributions, and Laue texture diagnostics against their chance levels."
 readme = "README.md"
 license = { text = "BSD-3-Clause" }

midas_plotting-0.5.0/tests/test_ipf.py

@@ -0,0 +1,204 @@
+"""IPF colouring.
+
+The property that matters: colour is a function of the crystal direction along
+a sample axis, so it is invariant under symmetry-equivalent descriptions of the
+same orientation. That is what makes one grain one colour, and it is what
+Euler->RGB does not give.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from midas_plotting.ipf import CUBIC, HEXAGONAL, ipf_rgb, laue_class, sym_matrices
+
+
+def test_laue_class_known_families():
+    assert laue_class(225) == CUBIC
+    assert laue_class(229) == CUBIC
+    assert laue_class(194) == HEXAGONAL
+    assert laue_class(168) == HEXAGONAL
+
+
+def test_laue_class_refuses_unimplemented_rather_than_guessing():
+    """A silent fallback to cubic would recolour a map with no other symptom.
+
+    SG 139 (tetragonal) and 69 (orthorhombic) were on this list until their
+    triangles were implemented; triclinic and monoclinic still are not, and the
+    contract is that they REFUSE rather than guess.
+
+    SG 75-88 is the subtle one. It is tetragonal by CRYSTAL SYSTEM but its Laue
+    class is 4/m, not 4/mmm: no in-plane mirror, so its triangle spans 90 deg to
+    [010] rather than 45 deg to [110]. Colouring it with the 4/mmm ramp folds by
+    a 2-fold the crystal does not have and yields a plausible, wrong map. It is
+    deliberately excluded until `_rgb_tetragonal_4m` exists.
+    """
+    for sg in (1, 2, 5, 15):                      # triclinic + monoclinic
+        with pytest.raises(NotImplementedError, match="not implemented"):
+            laue_class(sg)
+    for sg in (75, 81, 88):                       # Laue class 4/m, NOT 4/mmm
+        with pytest.raises(NotImplementedError, match="not implemented"):
+            laue_class(sg)
+
+
+def test_tetragonal_range_is_the_laue_class_not_the_crystal_system():
+    """4/mmm starts at 89. The boundary is the whole point of the split."""
+    from midas_plotting.ipf import laue_class, sector_deg, TETRAGONAL
+    with pytest.raises(NotImplementedError):
+        laue_class(88)
+    assert laue_class(89) == TETRAGONAL
+    assert sector_deg(89) == 45.0 and sector_deg(142) == 45.0
+
+
+def test_tetragonal_and_orthorhombic_triangles_are_distinct():
+    """4/mmm and mmm must not be the same colouring, and neither may be cubic.
+
+    The discriminator is [010]: under 4/mmm a 4-fold makes it equivalent to
+    [100] (both GREEN), while mmm has no in-plane rotation so [010] is the
+    third vertex (BLUE). A tetragonal map coloured with the mmm triangle -- or
+    with the cubic one, which folds by a 3-fold the crystal does not have --
+    would look plausible and be wrong.
+    """
+    import numpy as np
+    from midas_plotting.ipf import direction_rgb
+    dirs = np.array([[0., 0., 1.], [1., 0., 0.], [0., 1., 0.]])
+    tet = direction_rgb(dirs, space_group=139)
+    ort = direction_rgb(dirs, space_group=69)
+    assert tet[0, 0] > 0.9 and ort[0, 0] > 0.9        # [001] is red in both
+    assert np.allclose(tet[1], tet[2], atol=1e-6), "4/mmm: [100] and [010] must match"
+    assert not np.allclose(ort[1], ort[2], atol=0.5), "mmm: [100] and [010] must differ"
+    assert ort[2, 2] > 0.9, "mmm: [010] is the blue vertex"
+
+
+def test_sym_matrices_are_proper_rotations():
+    for sg, n_expected in ((225, 24), (194, 12)):
+        S = sym_matrices(sg)
+        assert S.shape == (n_expected, 3, 3), (sg, S.shape)
+        dets = np.linalg.det(S)
+        np.testing.assert_allclose(dets, 1.0, atol=1e-9)
+        for M in S:
+            np.testing.assert_allclose(M @ M.T, np.eye(3), atol=1e-9)
+
+
+def test_rgb_in_unit_range():
+    rng = np.random.default_rng(0)
+    e = rng.uniform(0, np.pi, size=(200, 3))
+    for sg in (225, 194):
+        rgb = ipf_rgb(e, sg)
+        assert rgb.shape == (200, 3)
+        assert rgb.min() >= 0.0 and rgb.max() <= 1.0
+        assert np.isfinite(rgb).all()
+
+
+def test_cube_on_axis_is_red():
+    """The identity orientation puts [001] along Z -> the [001] triangle corner."""
+    rgb = ipf_rgb(np.zeros((1, 3)), 225)[0]
+    assert rgb[0] > 0.9
+    assert rgb[1] < 0.2 and rgb[2] < 0.2
+
+
+def test_symmetry_equivalent_orientations_get_the_same_colour():
+    """The whole point: one grain, one colour.
+
+    Rotating by a symmetry operator describes the SAME crystal, so the colour
+    must not move. An Euler->RGB scheme fails this badly.
+    """
+    from midas_stress.orientation import (
+        euler_to_orient_mat_batch, orient_mat_to_euler,
+    )
+
+    rng = np.random.default_rng(3)
+    e0 = rng.uniform(0, np.pi, size=(12, 3))
+    g0 = np.asarray(euler_to_orient_mat_batch(e0)).reshape(-1, 3, 3)
+    S = sym_matrices(225)
+
+    base = ipf_rgb(e0, 225)
+    for op in S[1:6]:
+        # symmetry acts on the RIGHT for crystal->lab matrices (MIDAS convention):
+        # midas_stress.misorientation_om_batch calls g.S equivalent and S.g a
+        # DIFFERENT orientation (61 deg). Asserting the wrong side is what let the
+        # g-vs-g^T bug survive until 2026-09-03.
+        g1 = np.einsum("nij,jk->nik", g0, op)
+        e1 = np.array([np.asarray(orient_mat_to_euler(m.ravel().tolist())).ravel()
+                       for m in g1])
+        np.testing.assert_allclose(ipf_rgb(e1, 225), base, atol=1e-6)
+
+
+def test_empty_input():
+    assert ipf_rgb(np.zeros((0, 3)), 225).shape == (0, 3)
+
+
+def test_zero_axis_rejected():
+    with pytest.raises(ValueError, match="non-zero"):
+        ipf_rgb(np.zeros((1, 3)), 225, axis=(0, 0, 0))
+
+
+def test_gamma_one_disables_the_perceptual_lift():
+    e = np.array([[0.3, 0.4, 0.5]])
+    lin = ipf_rgb(e, 225, gamma=1.0)
+    sq = ipf_rgb(e, 225, gamma=0.5)
+    np.testing.assert_allclose(sq, np.sqrt(lin), atol=1e-9)
+
+
+def test_hexagonal_c_axis_along_z_is_red():
+    """[0001] || Z is the first corner of the hexagonal triangle."""
+    rgb = ipf_rgb(np.zeros((1, 3)), 194)[0]
+    assert rgb[0] > 0.9
+
+
+# --- trigonal (Laue -3m), added for NMC811 R-3m / SG 166 -------------------
+
+def _random_oms(n, seed=0):
+    rng = np.random.default_rng(seed)
+    q = rng.normal(size=(n, 4))
+    q /= np.linalg.norm(q, axis=1, keepdims=True)
+    w, x, y, z = q.T
+    return np.stack([
+        1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w),
+        2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w),
+        2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y),
+    ], axis=1).reshape(-1, 3, 3)
+
+
+@pytest.mark.parametrize("sg", [166, 194, 225])
+def test_ipf_colour_is_symmetry_invariant(sg):
+    """colour(S.g) == colour(g) for every proper rotation S.
+
+    This is the property that makes an IPF map mean anything: one grain, one
+    colour, whichever symmetrically equivalent orientation the indexer
+    happened to report. It is also what caught the first -3m triangle, which
+    hand-folded the azimuth assuming a 2-fold axis at 0 deg and moved the
+    colour by up to 0.99 under this test.
+    """
+    from midas_plotting.ipf import ipf_rgb_from_matrix, sym_matrices
+    g = _random_oms(2000, seed=sg)
+    base = ipf_rgb_from_matrix(g, sg)
+    for s in sym_matrices(sg):
+        got = ipf_rgb_from_matrix(np.einsum("nij,jk->nik", g, s), sg)
+        np.testing.assert_allclose(got, base, atol=1e-9)
+
+
+def test_trigonal_sector_is_twice_the_hexagonal_one():
+    """-3m has 6 proper rotations to 6/mmm's 12, so a 60 deg sector, not 30.
+
+    Measured from the operator set, so a change there cannot silently
+    mis-scale the ramp.
+    """
+    from midas_plotting.ipf import _trigonal_sector_deg, sym_matrices
+    assert _trigonal_sector_deg(sym_matrices(166)) == pytest.approx(60.0)
+    assert _trigonal_sector_deg(sym_matrices(194)) == pytest.approx(30.0)
+
+
+def test_trigonal_is_not_the_hexagonal_colouring():
+    """R-3m must not be quietly coloured as 6/mmm -- that merges orientations."""
+    from midas_plotting.ipf import ipf_rgb_from_matrix
+    g = _random_oms(3000, seed=7)
+    assert np.abs(ipf_rgb_from_matrix(g, 166)
+                  - ipf_rgb_from_matrix(g, 194)).mean() > 0.05
+
+
+def test_laue_class_still_refuses_what_it_cannot_draw():
+    from midas_plotting.ipf import laue_class
+    assert laue_class(166) == "trigonal"
+    with pytest.raises(NotImplementedError):
+        laue_class(2)          # triclinic: no triangle implemented

midas_plotting-0.4.0/midas_plotting/ipf.py

@@ -1,184 +0,0 @@
-"""Inverse-pole-figure colouring.
-
-Colour encodes which crystal direction is parallel to a chosen sample axis, so
-one grain is one colour and boundaries appear as colour discontinuities. That is
-the property an Euler-to-RGB dump does NOT have: two orientations a fraction of
-a degree apart can land on very different Euler triplets (and hence very
-different colours) near the gimbal-lock line, which makes a single grain look
-like several.
-
-Symmetry operators come from :mod:`midas_stress`, never hand-listed here.
-"""
-from __future__ import annotations
-
-from typing import Sequence
-
-import numpy as np
-
-__all__ = ["ipf_rgb", "sym_matrices", "CUBIC", "HEXAGONAL"]
-
-CUBIC = "cubic"
-HEXAGONAL = "hexagonal"
-
-# Laue class per space-group range, for the ones MIDAS actually reconstructs.
-# Deliberately explicit rather than clever: a wrong guess here silently
-# recolours a map without any other symptom.
-_SG_LAUE = [
-    (195, 230, CUBIC),
-    (168, 194, HEXAGONAL),
-]
-
-
-def laue_class(space_group: int) -> str:
-    """Laue family used for the IPF triangle.
-
-    Raises for space groups whose triangle is not implemented, rather than
-    falling back to cubic -- a silent fallback would produce a plausible-looking
-    but meaningless map.
-    """
-    for lo, hi, name in _SG_LAUE:
-        if lo <= int(space_group) <= hi:
-            return name
-    raise NotImplementedError(
-        f"IPF colouring for space group {space_group} is not implemented "
-        f"(have: cubic 195-230, hexagonal 168-194). Refusing to guess."
-    )
-
-
-def sym_matrices(space_group: int) -> np.ndarray:
-    """``(n_sym, 3, 3)`` proper-rotation operators from midas_stress."""
-    from midas_stress.orientation import make_symmetries, quat_to_orient_mat
-
-    n, quats = make_symmetries(int(space_group))
-    q = np.asarray(quats)[: int(n)]
-    return np.stack([np.asarray(quat_to_orient_mat(qi)).reshape(3, 3) for qi in q])
-
-
-def _reduce_cubic(d: np.ndarray) -> np.ndarray:
-    """Fold directions into the standard [001]-[101]-[111] triangle."""
-    d = np.abs(d)
-    d = np.sort(d, axis=-1)                     # u <= v <= w
-    return d
-
-
-def _rgb_cubic(d: np.ndarray) -> np.ndarray:
-    u, v, w = d[:, 0], d[:, 1], d[:, 2]
-    rgb = np.stack([w - v, (v - u) * np.sqrt(2.0), u * np.sqrt(3.0)], axis=1)
-    return rgb
-
-
-def _rgb_hexagonal(d: np.ndarray) -> np.ndarray:
-    """Standard [0001]-[10-10]-[2-1-10] triangle.
-
-    ``d`` is Cartesian with c along +z. After symmetry reduction the
-    representative has ``dz >= 0`` and azimuth in ``[0, 30]`` degrees.
-    """
-    dz = np.abs(d[:, 2])
-    planar = np.hypot(d[:, 0], d[:, 1])
-    phi = np.degrees(np.arctan2(np.abs(d[:, 1]), np.abs(d[:, 0])))
-    phi = np.minimum(phi % 60.0, 60.0 - (phi % 60.0))     # fold to [0, 30]
-    t = np.clip(phi / 30.0, 0.0, 1.0)
-    return np.stack([dz, planar * (1.0 - t), planar * t], axis=1)
-
-
-def ipf_rgb(
-    euler: np.ndarray,
-    space_group: int = 225,
-    axis: Sequence[float] = (0.0, 0.0, 1.0),
-    *,
-    gamma: float = 0.5,
-) -> np.ndarray:
-    """RGB per orientation for the crystal direction parallel to ``axis``.
-
-    Parameters
-    ----------
-    euler : (N, 3) array
-        Bunge ZXZ Euler angles in **radians** -- the MIDAS ``.mic`` convention.
-    space_group : int
-        Used for the symmetry operators and to pick the triangle.
-    axis : length-3
-        Sample-frame direction. ``(0,0,1)`` gives the usual IPF-Z.
-    gamma : float
-        Perceptual lift applied as ``rgb ** gamma``. 0.5 (sqrt) matches the
-        common convention; 1.0 disables it.
-
-    Returns
-    -------
-    (N, 3) float array in [0, 1].
-    """
-    from midas_stress.orientation import euler_to_orient_mat_batch
-
-    euler = np.asarray(euler, dtype=float).reshape(-1, 3)
-    if euler.size == 0:
-        return np.zeros((0, 3))
-    g = np.asarray(euler_to_orient_mat_batch(euler)).reshape(-1, 3, 3)
-    return ipf_rgb_from_matrix(g, space_group, axis, gamma=gamma)
-
-
-def ipf_rgb_from_matrix(
-    orient_mat: np.ndarray,
-    space_group: int = 225,
-    axis: Sequence[float] = (0.0, 0.0, 1.0),
-    *,
-    gamma: float = 0.5,
-) -> np.ndarray:
-    """RGB per orientation, from ``(N, 3, 3)`` orientation matrices.
-
-    The same colouring as :func:`ipf_rgb`, entered from the matrix rather than
-    from Euler angles. Far-field ``Grains.csv`` carries both (``O11..O33`` and
-    ``Eul0..2``); this avoids a needless matrix -> Euler -> matrix round trip,
-    which is lossy near the gimbal-lock configurations of the ZXZ convention.
-    """
-    g = np.asarray(orient_mat, dtype=float).reshape(-1, 3, 3)
-    if g.size == 0:
-        return np.zeros((0, 3))
-
-    a = np.asarray(axis, dtype=float)
-    n = np.linalg.norm(a)
-    if n == 0:
-        raise ValueError("axis must be non-zero")
-    a = a / n
-
-    d = np.einsum("nij,j->ni", g, a)                 # crystal dir of the axis
-    return direction_rgb(d, space_group, gamma=gamma)
-
-
-def direction_rgb(
-    dirs: np.ndarray, space_group: int = 225, *, gamma: float = 0.5,
-) -> np.ndarray:
-    """RGB for **crystal directions** -- the colouring core.
-
-    ``dirs`` is ``(N, 3)`` in crystal coordinates; it is normalised here.
-    Both :func:`ipf_rgb` and the legend drawn by
-    ``midas_plotting.ff.ipf_legend`` go through this, so the key on a figure
-    is guaranteed to match the colours in the map beside it. A legend computed
-    by a separate copy of the triangle maths is a legend that eventually lies.
-    """
-    d = np.asarray(dirs, dtype=float).reshape(-1, 3)
-    if d.size == 0:
-        return np.zeros((0, 3))
-    nrm = np.linalg.norm(d, axis=1, keepdims=True)
-    d = np.divide(d, nrm, out=np.zeros_like(d), where=nrm > 0)
-
-    fam = laue_class(space_group)
-    sym = sym_matrices(space_group)
-    d = np.einsum("sij,nj->nsi", sym, d)             # every equivalent
-
-    if fam == CUBIC:
-        red = _reduce_cubic(d)
-        pick = np.argmax(red[:, :, 2], axis=1)       # closest to [001]
-        red = red[np.arange(red.shape[0]), pick]
-        red /= np.linalg.norm(red, axis=1, keepdims=True)
-        rgb = _rgb_cubic(red)
-    else:
-        dd = d.copy()
-        dd[:, :, 2] = np.abs(dd[:, :, 2])
-        pick = np.argmax(dd[:, :, 2], axis=1)        # closest to [0001]
-        red = dd[np.arange(dd.shape[0]), pick]
-        red /= np.linalg.norm(red, axis=1, keepdims=True)
-        rgb = _rgb_hexagonal(red)
-
-    rgb = np.clip(rgb, 0.0, None)
-    mx = rgb.max(axis=1, keepdims=True)
-    rgb = np.where(mx > 0, rgb / mx, rgb)
-    return np.clip(rgb ** float(gamma), 0.0, 1.0)

midas_plotting-0.4.0/tests/test_ipf.py

@@ -1,100 +0,0 @@
-"""IPF colouring.
-
-The property that matters: colour is a function of the crystal direction along
-a sample axis, so it is invariant under symmetry-equivalent descriptions of the
-same orientation. That is what makes one grain one colour, and it is what
-Euler->RGB does not give.
-"""
-from __future__ import annotations
-
-import numpy as np
-import pytest
-
-from midas_plotting.ipf import CUBIC, HEXAGONAL, ipf_rgb, laue_class, sym_matrices
-
-
-def test_laue_class_known_families():
-    assert laue_class(225) == CUBIC
-    assert laue_class(229) == CUBIC
-    assert laue_class(194) == HEXAGONAL
-    assert laue_class(168) == HEXAGONAL
-
-
-def test_laue_class_refuses_unimplemented_rather_than_guessing():
-    """A silent fallback to cubic would recolour a map with no other symptom."""
-    with pytest.raises(NotImplementedError, match="not implemented"):
-        laue_class(2)          # triclinic
-    with pytest.raises(NotImplementedError):
-        laue_class(139)        # tetragonal
-
-
-def test_sym_matrices_are_proper_rotations():
-    for sg, n_expected in ((225, 24), (194, 12)):
-        S = sym_matrices(sg)
-        assert S.shape == (n_expected, 3, 3), (sg, S.shape)
-        dets = np.linalg.det(S)
-        np.testing.assert_allclose(dets, 1.0, atol=1e-9)
-        for M in S:
-            np.testing.assert_allclose(M @ M.T, np.eye(3), atol=1e-9)
-
-
-def test_rgb_in_unit_range():
-    rng = np.random.default_rng(0)
-    e = rng.uniform(0, np.pi, size=(200, 3))
-    for sg in (225, 194):
-        rgb = ipf_rgb(e, sg)
-        assert rgb.shape == (200, 3)
-        assert rgb.min() >= 0.0 and rgb.max() <= 1.0
-        assert np.isfinite(rgb).all()
-
-
-def test_cube_on_axis_is_red():
-    """The identity orientation puts [001] along Z -> the [001] triangle corner."""
-    rgb = ipf_rgb(np.zeros((1, 3)), 225)[0]
-    assert rgb[0] > 0.9
-    assert rgb[1] < 0.2 and rgb[2] < 0.2
-
-
-def test_symmetry_equivalent_orientations_get_the_same_colour():
-    """The whole point: one grain, one colour.
-
-    Rotating by a symmetry operator describes the SAME crystal, so the colour
-    must not move. An Euler->RGB scheme fails this badly.
-    """
-    from midas_stress.orientation import (
-        euler_to_orient_mat_batch, orient_mat_to_euler,
-    )
-
-    rng = np.random.default_rng(3)
-    e0 = rng.uniform(0, np.pi, size=(12, 3))
-    g0 = np.asarray(euler_to_orient_mat_batch(e0)).reshape(-1, 3, 3)
-    S = sym_matrices(225)
-
-    base = ipf_rgb(e0, 225)
-    for op in S[1:6]:
-        g1 = np.einsum("ij,njk->nik", op, g0)
-        e1 = np.array([np.asarray(orient_mat_to_euler(m.ravel().tolist())).ravel()
-                       for m in g1])
-        np.testing.assert_allclose(ipf_rgb(e1, 225), base, atol=1e-6)
-
-
-def test_empty_input():
-    assert ipf_rgb(np.zeros((0, 3)), 225).shape == (0, 3)
-
-
-def test_zero_axis_rejected():
-    with pytest.raises(ValueError, match="non-zero"):
-        ipf_rgb(np.zeros((1, 3)), 225, axis=(0, 0, 0))
-
-
-def test_gamma_one_disables_the_perceptual_lift():
-    e = np.array([[0.3, 0.4, 0.5]])
-    lin = ipf_rgb(e, 225, gamma=1.0)
-    sq = ipf_rgb(e, 225, gamma=0.5)
-    np.testing.assert_allclose(sq, np.sqrt(lin), atol=1e-9)
-
-
-def test_hexagonal_c_axis_along_z_is_red():
-    """[0001] || Z is the first corner of the hexagonal triangle."""
-    rgb = ipf_rgb(np.zeros((1, 3)), 194)[0]
-    assert rgb[0] > 0.9