midas-plotting 0.3.0__py3-none-any.whl

midas_plotting/grains.py

@@ -0,0 +1,301 @@
+"""Reading MIDAS far-field ``Grains.csv``.
+
+The FF analogue of :mod:`midas_plotting.mic`: one place that knows the column
+layout so analysis scripts stop re-deriving it.
+
+Columns are looked up **by name** from the ``%ID ...`` header line, never by
+position. That matters more here than it looks: ``Grains.csv`` has grown to 47
+columns, and `midas-fit-grain` 0.5.6 shipped a cyclic rotation of the
+``DiffPos`` / ``DiffOme`` / ``DiffAngle`` columns (fixed in 0.5.7) that a
+positional reader would silently inherit -- one grain's ω residual read 223.87°
+where the true value was 0.054°.
+
+As a further guard, :func:`read_grains` recomputes the orientation matrix from
+the Euler angles and compares it against the ``O11..O33`` columns. Both describe
+the same orientation, so any disagreement means the row is being sliced wrong
+(or the file was written by a broken version), and it is far better to hear
+about that than to plot it.
+"""
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+__all__ = ["GrainList", "read_grains"]
+
+_OM_NAMES = [f"O{i}{j}" for i in (1, 2, 3) for j in (1, 2, 3)]
+_EUL_NAMES = ["Eul0", "Eul1", "Eul2"]
+_LATTICE_NAMES = ["a", "b", "c", "alpha", "beta", "gamma"]
+_FAB = [f"eFab{i}{j}" for i in (1, 2, 3) for j in (1, 2, 3)]
+_KEN = [f"eKen{i}{j}" for i in (1, 2, 3) for j in (1, 2, 3)]
+
+#: Euler/orientation-matrix agreement above this is treated as a real
+#: inconsistency. ``Grains.csv`` is written at ~6 significant figures, so
+#: round-trip differences of ~1e-6 are expected and harmless.
+OM_EULER_TOL = 1e-3
+
+
+@dataclass
+class GrainList:
+    """A parsed FF ``Grains.csv``.
+
+    Attributes
+    ----------
+    ids : (N,) int
+    pos : (N, 3) float
+        Grain centre-of-mass X, Y, Z in **micrometres**. Trustworthy to about
+        ~100 µm on a typical reconstruction -- do not read the six decimals the
+        file prints (``FF_HEDM_Lab_Notebook.md`` §2d).
+    euler : (N, 3) float
+        Bunge ZXZ Euler angles in **radians**, matching the ``.mic`` convention
+        so :func:`midas_plotting.ipf_rgb` accepts them directly.
+    orient_mat : (N, 3, 3) float
+    lattice : (N, 6) float
+        a, b, c (Å) and alpha, beta, gamma (degrees).
+    radius : (N,) float
+        ``GrainRadius`` in µm. Correct only with ``midas-process-grains``
+        >= 0.6.1; older versions report ~the sample-wide mean for every grain.
+    completeness : (N,) float
+    diff_pos, diff_ome, diff_angle : (N,) float
+        Residuals. Cyclically mislabeled by `midas-fit-grain` 0.5.6.
+    strain_fab, strain_ken : (N, 3, 3) float or None
+    rmse_strain : (N,) float or None
+    phase : (N,) int or None
+    header : dict
+        The ``%key value`` preamble (NumGrains, BeamCenter, ...).
+    columns : list of str
+    raw : (N, C) float
+    path : Path
+    """
+
+    ids: np.ndarray
+    pos: np.ndarray
+    euler: np.ndarray
+    orient_mat: np.ndarray
+    lattice: np.ndarray
+    radius: np.ndarray
+    completeness: np.ndarray
+    diff_pos: np.ndarray
+    diff_ome: np.ndarray
+    diff_angle: np.ndarray
+    strain_fab: Optional[np.ndarray]
+    strain_ken: Optional[np.ndarray]
+    rmse_strain: Optional[np.ndarray]
+    phase: Optional[np.ndarray]
+    header: dict
+    columns: list
+    raw: np.ndarray
+    path: Path
+
+    def __len__(self) -> int:
+        return int(self.ids.size)
+
+    @property
+    def space_group(self) -> Optional[int]:
+        """Space group from the file's own ``%\tSpaceGroup:`` line, if present.
+
+        Plot functions default to this rather than to a hard-coded 225, so a
+        hexagonal or tetragonal sample is not silently coloured with the cubic
+        IPF triangle -- which produces a plausible-looking figure that is
+        simply wrong.
+        """
+        v = self.header.get("SpaceGroup")
+        try:
+            return int(str(v).strip())
+        except (TypeError, ValueError):
+            return None
+
+    @property
+    def lattice_parameter(self) -> Optional[np.ndarray]:
+        """The header's reference lattice parameter (a, b, c, al, be, ga)."""
+        v = self.header.get("Lattice Parameter")
+        if not v:
+            return None
+        try:
+            arr = np.array([float(x) for x in str(v).split()], dtype=float)
+        except ValueError:
+            return None
+        return arr if arr.size == 6 else None
+
+    @property
+    def n_grains(self) -> int:
+        return len(self)
+
+    def strain(self, convention: str = "fab") -> np.ndarray:
+        """``(N, 3, 3)`` strain tensor in the requested convention."""
+        c = convention.lower()
+        if c in ("fab", "fable", "efab"):
+            s = self.strain_fab
+        elif c in ("ken", "kenesei", "eken"):
+            s = self.strain_ken
+        else:
+            raise ValueError(
+                f"unknown strain convention {convention!r}; use 'fab' or 'ken'")
+        if s is None:
+            raise ValueError(
+                f"{self.path.name} has no {c} strain columns "
+                "(ProcessGrains may have been run without strain output)")
+        return s
+
+
+def _parse(path: Path):
+    """Split a Grains.csv into (header dict, column names, data rows).
+
+    The preamble is not uniform. Real files contain all of:
+
+        %NumGrains 2
+        %PhaseInfo                      <- key with no value
+        %\tSpaceGroup:225               <- TAB-indented `key:value` continuation
+        %\tLattice Parameter:4.0782 ... <- key with spaces, colon-separated
+        %ID\tO11\t...                    <- the column header
+
+    so a naive `body.split()[0]` raises on the indented lines. The column
+    header is identified by content (it names the orientation-matrix columns)
+    rather than by position, since the number of preamble lines varies with
+    the number of phases.
+    """
+    header, columns, rows = {}, None, []
+    for line in Path(path).read_text().splitlines():
+        if not line.strip():
+            continue
+        if not line.startswith("%"):
+            rows.append(line.split("\t"))
+            continue
+
+        body = line[1:]
+        fields = [f.strip() for f in body.split("\t")]
+        # Column header: names O11 (and therefore the whole grain record).
+        if "O11" in fields or (fields and fields[0] in ("ID", "GrainID")
+                               and len(fields) > 5):
+            columns = fields
+            continue
+
+        stripped = body.strip()
+        if not stripped:
+            continue
+        if ":" in stripped:                      # `SpaceGroup:225`
+            k, _, v = stripped.partition(":")
+            header[k.strip()] = v.strip()
+        else:                                    # `NumGrains 2` / `PhaseInfo`
+            parts = stripped.split()
+            header[parts[0]] = " ".join(parts[1:])
+    return header, columns, rows
+
+
+def read_grains(path, *, check_orientation: bool = True) -> GrainList:
+    """Parse an FF ``Grains.csv``.
+
+    Parameters
+    ----------
+    path : str or Path
+    check_orientation : bool
+        Recompute the orientation matrix from the Euler columns and compare
+        against ``O11..O33``. A mismatch means the columns are being read
+        wrong; a warning is emitted rather than an exception, so a file written
+        by an old or unusual version can still be inspected -- but do not
+        trust orientation-derived output (including IPF colour) when it fires.
+    """
+    path = Path(path)
+    header, columns, rows = _parse(path)
+    if columns is None:
+        raise ValueError(
+            f"{path}: no column header found. Expected a line beginning "
+            "'%ID' or '%GrainID' listing tab-separated column names.")
+    if not rows:
+        raise ValueError(f"{path}: header present but no grain rows.")
+
+    idx = {name: i for i, name in enumerate(columns)}
+    arr = np.array([[float(v) for v in r] for r in rows], dtype=float)
+    if arr.shape[1] != len(columns):
+        raise ValueError(
+            f"{path}: {arr.shape[1]} data columns but {len(columns)} header "
+            "names -- the file is malformed or tab/space separated "
+            "inconsistently.")
+
+    def col(name, required=True):
+        if name not in idx:
+            if required:
+                raise ValueError(
+                    f"{path}: required column {name!r} not found. "
+                    f"Columns present: {columns}")
+            return None
+        return arr[:, idx[name]]
+
+    def block(names):
+        if not all(n in idx for n in names):
+            return None
+        return np.stack([arr[:, idx[n]] for n in names], axis=1)
+
+    id_name = "ID" if "ID" in idx else "GrainID"
+    ids = col(id_name).astype(int)
+    pos = np.stack([col("X"), col("Y"), col("Z")], axis=1)
+
+    om_flat = block(_OM_NAMES)
+    if om_flat is None:
+        raise ValueError(f"{path}: orientation matrix columns O11..O33 missing.")
+    orient_mat = om_flat.reshape(-1, 3, 3)
+
+    eul = block(_EUL_NAMES)
+    if eul is None:
+        # Older writers omitted the Euler columns; derive them so downstream
+        # (and ipf_rgb) has a single, consistent source.
+        from midas_stress.orientation import orient_mat_to_euler
+
+        eul = np.array([np.asarray(orient_mat_to_euler(m.reshape(-1).tolist()),
+                                   dtype=float).reshape(3)
+                        for m in orient_mat])
+
+    if check_orientation:
+        _check_orientation(path, eul, orient_mat)
+
+    lattice = block(_LATTICE_NAMES)
+    if lattice is None:
+        lattice = np.full((len(ids), 6), np.nan)
+
+    fab = block(_FAB)
+    ken = block(_KEN)
+    return GrainList(
+        ids=ids,
+        pos=pos,
+        euler=eul,
+        orient_mat=orient_mat,
+        lattice=lattice,
+        radius=col("GrainRadius", required=False),
+        completeness=col("Confidence", required=False),
+        diff_pos=col("DiffPos", required=False),
+        diff_ome=col("DiffOme", required=False),
+        diff_angle=col("DiffAngle", required=False),
+        strain_fab=None if fab is None else fab.reshape(-1, 3, 3),
+        strain_ken=None if ken is None else ken.reshape(-1, 3, 3),
+        rmse_strain=col("RMSErrorStrain", required=False),
+        phase=None if "PhaseNr" not in idx else col("PhaseNr").astype(int),
+        header=header,
+        columns=columns,
+        raw=arr,
+        path=path,
+    )
+
+
+def _check_orientation(path, euler, orient_mat) -> None:
+    """Euler and O11..O33 must describe the same orientation."""
+    try:
+        from midas_stress.orientation import euler_to_orient_mat_batch
+    except Exception:                                      # noqa: BLE001
+        return
+    rec = np.asarray(euler_to_orient_mat_batch(euler)).reshape(-1, 3, 3)
+    dev = float(np.abs(rec - orient_mat).max())
+    if dev > OM_EULER_TOL:
+        warnings.warn(
+            f"{path.name}: Euler angles and the O11..O33 matrix disagree by "
+            f"{dev:.3g} (tolerance {OM_EULER_TOL:g}). The columns are probably "
+            "being read wrong, or the file was written by a version with a "
+            "column-ordering bug -- `midas-fit-grain` 0.5.6 shipped one. Do "
+            "NOT trust orientation-derived output (IPF colour, pole figures, "
+            "misorientation) from this file until it is resolved.",
+            RuntimeWarning,
+            stacklevel=3,
+        )

midas_plotting/ipf.py

@@ -0,0 +1,184 @@
+"""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)