midas-plotting 0.3.0__tar.gz

midas_plotting-0.3.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: midas-plotting
+Version: 0.3.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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.22
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: midas-stress>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: scipy>=1.9; extra == "dev"
+
+# midas-plotting
+
+Standard plots for MIDAS reconstructions.
+
+```python
+from midas_plotting import read_mic, orientation_map, compare_maps
+
+m = read_mic("Ce5Y_mr.2.mic")
+print(m.summary())
+orientation_map(m, space_group=225, cmin=0.3)
+```
+
+```bash
+midas-plot Ce5Y.0.mic Ce5Y_sum3thr2.0.mic --kind orientation --cmin 0.3 \
+    --titles "baseline|sum3+thr2" -o compare.png
+```
+
+## Why
+
+IPF colouring, `.mic` parsing and map plotting had been re-implemented in
+several one-off analysis scripts, each with its own conventions. Two things that
+kept going wrong and are now handled in one place:
+
+- **Euler→RGB is not an orientation map.** Two orientations a fraction of a
+  degree apart can produce very different Euler triplets near gimbal lock, so a
+  single grain renders as several colours. `ipf_rgb` colours by the crystal
+  direction along a sample axis instead.
+- **A permissive confidence cut fills the whole grid.** The fit returns *an*
+  orientation for every voxel it evaluates, so plotting at C ≥ 0.1 shows
+  plausible microstructure whether or not material is there. `orientation_map`
+  annotates the figure when asked to plot below `TRUST_FLOOR` (0.3).
+
+Symmetry operators come from `midas_stress`; nothing is hand-listed here.
+
+Implemented Laue families: cubic (SG 195–230) and hexagonal (168–194).
+Anything else raises rather than silently falling back to cubic.
+
+## Far-field (`Grains.csv`)
+
+```python
+from midas_plotting import ff, read_grains
+
+g = read_grains("Grains.csv")
+print(len(g), g.space_group)        # symmetry is read from the file's header
+
+ff.summary(g)                        # one-page overview
+ff.grain_map(g, color="ipf")         # IPF-coloured grain centres
+ff.ipf_legend(g.space_group)         # the colour key
+ff.pole_figure(g, hkl=(1, 1, 1))
+ff.strain_map(g, kind="vonmises")
+```
+
+```bash
+midas-plot Grains.csv --kind summary -o overview.png
+midas-plot Grains.csv --kind pole --hkl 1,1,1
+midas-plot Grains.csv --kind strain --strain-kind hydrostatic
+```
+
+FF output is a **grain list**, not a voxel grid, so these are scatter and
+distribution plots. They are namespaced under `ff` rather than exported flat
+because both modalities have a `grain_map` and they mean different things:
+`maps.grain_map` labels a near-field voxel grid, `ff.grain_map` scatters
+far-field grain centres.
+
+Things the module will not let you get wrong:
+
+* **Symmetry comes from the file.** `Grains.csv` states its space group in the
+  preamble; the plots use it. Defaulting to cubic would colour a hexagonal
+  sample with the wrong IPF triangle and produce a plausible, wrong figure.
+* **Columns are read by name.** `Grains.csv` has 47 columns and
+  `midas-fit-grain` 0.5.6 shipped a cyclic rotation of three of them; a
+  positional reader inherits that silently.
+* **Euler angles are cross-checked against `O11..O33`.** They describe the same
+  orientation, so disagreement means the row is being sliced wrong — you get a
+  warning instead of a wrong colour.
+* **Strain is already microstrain.** The `eFab`/`eKen` columns are not
+  dimensionless; they are not rescaled.
+
+Two caveats the plots cannot fix: FF grain positions are good to ~100 µm (not
+the six decimals the file prints), and `GrainRadius` is only correct with
+`midas-process-grains >= 0.6.1`.
+
+## Laue (`solutions.txt`, `spots.txt`)
+
+```python
+from midas_plotting import laue, read_solutions, read_spots
+
+sol = read_solutions("solutions.txt")     # one row per orientation PER FRAME
+print(sol.summary())                      # ... 4,746 distinct orientations ...
+sol = sol.gate(11)                        # the measured null for THAT scan
+
+c = laue.cluster(sol, 1.0, space_group=194)
+print(c)          # <GrainClusters 631 grains at 1.0deg (of 636 clusters,
+                  #  5 spanning >half the map), n_eff 309.5>
+
+reps = c.representatives(sol.orient_mat)  # one orientation per grain
+laue.tilt_histogram(reps)                 # against the random reference
+laue.texture_strength(reps)               # (peak, chance, peak/chance)
+laue.summary(sol)
+```
+
+```bash
+midas-plot solutions.txt --kind tilt --gate 11 --sg 194
+midas-plot validated.npz --kind summary --sg 194 --tol 1.0
+```
+
+Laue output is neither a voxel grid nor a grain list: it is one row per
+*orientation per frame*, so a crystal seen at twenty positions appears twenty
+times. Nothing is a grain until it has been clustered, and every grain count
+here carries the tolerance that produced it.
+
+Four things the module will not let you get wrong:
+
+* **Half of a random population lies more than 60° from any fixed direction.**
+  That is solid angle, not texture. `tilt_histogram` draws
+  `random_tilt_fractions()` beside the data by default, because "70% of grains
+  lie near the surface plane" reads as a strong texture and is very nearly
+  random — and 30% there is a *depletion*.
+* **A raw pole density is not comparable between datasets.** A small grain
+  population peaks higher by chance alone, and its chance level rises to match.
+  `texture_strength` returns the ratio to its own measured null, which is what
+  makes 85 grains and 631 grains commensurable.
+* **An orientation present at every raster position is not a grain.** The beam
+  moves a micron or two between frames. `cluster` flags anything spanning more
+  than half the map; on one dataset a single such object held 59% of all
+  measurements and dragged the effective sample size from 29 to 2.5. The Kish
+  effective n sits next to every grain count for the same reason.
+* **`orientationRowNr` is column 34 and `misOrientationPostRefinement` is 33.**
+  Reading 33 for 34 does not raise — it returns a near-zero float for every
+  row, so distinct-orientation counts collapse to single digits and the scan
+  looks like it found one crystal. Columns are read by name.
+
+Geometry is explicit, never assumed: `SURFACE_NORMAL_34IDE` and the `COS45`
+stage correction are module constants with 34-ID-E defaults, and every function
+takes `normal=`. The out-of-plane stage axis sits at 45°, so quoting its raw
+extent as a map size understates it by 1.41× — a 200 × 100 µm map reads as
+200 × 71.
+
+The acceptance gate has **no default**. It is the largest number of reflections
+a randomly oriented crystal achieves on those frames, it is a property of the
+scan, and `midas-plot` says so when you omit `--gate` rather than picking one.

midas_plotting-0.3.0/README.md

@@ -0,0 +1,141 @@
+# midas-plotting
+
+Standard plots for MIDAS reconstructions.
+
+```python
+from midas_plotting import read_mic, orientation_map, compare_maps
+
+m = read_mic("Ce5Y_mr.2.mic")
+print(m.summary())
+orientation_map(m, space_group=225, cmin=0.3)
+```
+
+```bash
+midas-plot Ce5Y.0.mic Ce5Y_sum3thr2.0.mic --kind orientation --cmin 0.3 \
+    --titles "baseline|sum3+thr2" -o compare.png
+```
+
+## Why
+
+IPF colouring, `.mic` parsing and map plotting had been re-implemented in
+several one-off analysis scripts, each with its own conventions. Two things that
+kept going wrong and are now handled in one place:
+
+- **Euler→RGB is not an orientation map.** Two orientations a fraction of a
+  degree apart can produce very different Euler triplets near gimbal lock, so a
+  single grain renders as several colours. `ipf_rgb` colours by the crystal
+  direction along a sample axis instead.
+- **A permissive confidence cut fills the whole grid.** The fit returns *an*
+  orientation for every voxel it evaluates, so plotting at C ≥ 0.1 shows
+  plausible microstructure whether or not material is there. `orientation_map`
+  annotates the figure when asked to plot below `TRUST_FLOOR` (0.3).
+
+Symmetry operators come from `midas_stress`; nothing is hand-listed here.
+
+Implemented Laue families: cubic (SG 195–230) and hexagonal (168–194).
+Anything else raises rather than silently falling back to cubic.
+
+## Far-field (`Grains.csv`)
+
+```python
+from midas_plotting import ff, read_grains
+
+g = read_grains("Grains.csv")
+print(len(g), g.space_group)        # symmetry is read from the file's header
+
+ff.summary(g)                        # one-page overview
+ff.grain_map(g, color="ipf")         # IPF-coloured grain centres
+ff.ipf_legend(g.space_group)         # the colour key
+ff.pole_figure(g, hkl=(1, 1, 1))
+ff.strain_map(g, kind="vonmises")
+```
+
+```bash
+midas-plot Grains.csv --kind summary -o overview.png
+midas-plot Grains.csv --kind pole --hkl 1,1,1
+midas-plot Grains.csv --kind strain --strain-kind hydrostatic
+```
+
+FF output is a **grain list**, not a voxel grid, so these are scatter and
+distribution plots. They are namespaced under `ff` rather than exported flat
+because both modalities have a `grain_map` and they mean different things:
+`maps.grain_map` labels a near-field voxel grid, `ff.grain_map` scatters
+far-field grain centres.
+
+Things the module will not let you get wrong:
+
+* **Symmetry comes from the file.** `Grains.csv` states its space group in the
+  preamble; the plots use it. Defaulting to cubic would colour a hexagonal
+  sample with the wrong IPF triangle and produce a plausible, wrong figure.
+* **Columns are read by name.** `Grains.csv` has 47 columns and
+  `midas-fit-grain` 0.5.6 shipped a cyclic rotation of three of them; a
+  positional reader inherits that silently.
+* **Euler angles are cross-checked against `O11..O33`.** They describe the same
+  orientation, so disagreement means the row is being sliced wrong — you get a
+  warning instead of a wrong colour.
+* **Strain is already microstrain.** The `eFab`/`eKen` columns are not
+  dimensionless; they are not rescaled.
+
+Two caveats the plots cannot fix: FF grain positions are good to ~100 µm (not
+the six decimals the file prints), and `GrainRadius` is only correct with
+`midas-process-grains >= 0.6.1`.
+
+## Laue (`solutions.txt`, `spots.txt`)
+
+```python
+from midas_plotting import laue, read_solutions, read_spots
+
+sol = read_solutions("solutions.txt")     # one row per orientation PER FRAME
+print(sol.summary())                      # ... 4,746 distinct orientations ...
+sol = sol.gate(11)                        # the measured null for THAT scan
+
+c = laue.cluster(sol, 1.0, space_group=194)
+print(c)          # <GrainClusters 631 grains at 1.0deg (of 636 clusters,
+                  #  5 spanning >half the map), n_eff 309.5>
+
+reps = c.representatives(sol.orient_mat)  # one orientation per grain
+laue.tilt_histogram(reps)                 # against the random reference
+laue.texture_strength(reps)               # (peak, chance, peak/chance)
+laue.summary(sol)
+```
+
+```bash
+midas-plot solutions.txt --kind tilt --gate 11 --sg 194
+midas-plot validated.npz --kind summary --sg 194 --tol 1.0
+```
+
+Laue output is neither a voxel grid nor a grain list: it is one row per
+*orientation per frame*, so a crystal seen at twenty positions appears twenty
+times. Nothing is a grain until it has been clustered, and every grain count
+here carries the tolerance that produced it.
+
+Four things the module will not let you get wrong:
+
+* **Half of a random population lies more than 60° from any fixed direction.**
+  That is solid angle, not texture. `tilt_histogram` draws
+  `random_tilt_fractions()` beside the data by default, because "70% of grains
+  lie near the surface plane" reads as a strong texture and is very nearly
+  random — and 30% there is a *depletion*.
+* **A raw pole density is not comparable between datasets.** A small grain
+  population peaks higher by chance alone, and its chance level rises to match.
+  `texture_strength` returns the ratio to its own measured null, which is what
+  makes 85 grains and 631 grains commensurable.
+* **An orientation present at every raster position is not a grain.** The beam
+  moves a micron or two between frames. `cluster` flags anything spanning more
+  than half the map; on one dataset a single such object held 59% of all
+  measurements and dragged the effective sample size from 29 to 2.5. The Kish
+  effective n sits next to every grain count for the same reason.
+* **`orientationRowNr` is column 34 and `misOrientationPostRefinement` is 33.**
+  Reading 33 for 34 does not raise — it returns a near-zero float for every
+  row, so distinct-orientation counts collapse to single digits and the scan
+  looks like it found one crystal. Columns are read by name.
+
+Geometry is explicit, never assumed: `SURFACE_NORMAL_34IDE` and the `COS45`
+stage correction are module constants with 34-ID-E defaults, and every function
+takes `normal=`. The out-of-plane stage axis sits at 45°, so quoting its raw
+extent as a map size understates it by 1.41× — a 200 × 100 µm map reads as
+200 × 71.
+
+The acceptance gate has **no default**. It is the largest number of reflections
+a randomly oriented crystal achieves on those frames, it is a property of the
+scan, and `midas-plot` says so when you omit `--gate` rather than picking one.

midas_plotting-0.3.0/midas_plotting/__init__.py

@@ -0,0 +1,59 @@
+"""Standard plots for MIDAS reconstructions.
+
+    from midas_plotting import read_mic, orientation_map
+    orientation_map("Ce5Y.0.mic", space_group=225, cmin=0.3)
+
+Far-field ``Grains.csv`` lives in the ``ff`` submodule::
+
+    from midas_plotting import ff, read_grains
+    g = read_grains("Grains.csv")
+    ff.summary(g)                      # one-page overview
+    ff.grain_map(g, color="ipf")       # IPF-coloured grain scatter
+    ff.ipf_legend(g.space_group)       # the colour key
+
+FF plots are namespaced rather than exported flat because both modalities have
+a ``grain_map`` and they mean different things: ``maps.grain_map`` labels a
+near-field voxel grid, ``ff.grain_map`` scatters far-field grain centres.
+
+Laue microdiffraction lives in ``laue``, and reads the indexer's text output::
+
+    from midas_plotting import laue, read_solutions
+    sol = read_solutions("solutions.txt")          # one row per frame, not per grain
+    sol = sol.gate(11)                             # the measured random-orientation null
+    c = laue.cluster(sol, 1.0, space_group=194)    # grains, with full-field objects flagged
+    laue.tilt_histogram(c.representatives(sol.orient_mat))   # vs the random reference
+    laue.summary(sol)
+
+or from the shell::
+
+    midas-plot Ce5Y.0.mic --kind orientation --cmin 0.3 --sg 225
+    midas-plot Grains.csv --kind summary
+
+Written after the same IPF colouring, .mic parsing and map plotting were
+re-implemented several times in one-off analysis scripts, each time with its own
+conventions.
+"""
+from .ipf import (
+    CUBIC, HEXAGONAL, direction_rgb, ipf_rgb, ipf_rgb_from_matrix,
+    laue_class, sym_matrices,
+)
+from .maps import (
+    TRUST_FLOOR, compare_maps, confidence_map, grain_labels, grain_map,
+    orientation_map,
+)
+from . import ff, laue
+from .grains import GrainList, read_grains
+from .solutions import (
+    LaueSolutions, LaueSpots, read_solutions, read_spots, read_validated,
+)
+from .mic import MicMap, read_mic
+
+__version__ = "0.3.0"
+__all__ = [
+    "MicMap", "read_mic", "GrainList", "read_grains", "ff", "laue",
+    "LaueSolutions", "LaueSpots", "read_solutions", "read_spots",
+    "read_validated", "ipf_rgb", "ipf_rgb_from_matrix", "direction_rgb",
+    "sym_matrices", "laue_class",
+    "CUBIC", "HEXAGONAL", "orientation_map", "confidence_map", "grain_map",
+    "grain_labels", "compare_maps", "TRUST_FLOOR", "__version__",
+]

midas_plotting-0.3.0/midas_plotting/cli.py

@@ -0,0 +1,264 @@
+"""``midas-plot`` — one-shot reconstruction figures from the shell."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="midas-plot",
+        description="Standard MIDAS reconstruction maps (orientation, "
+                    "confidence, grains).")
+    ap.add_argument("mics", nargs="+",
+                    help="near-field .mic file(s), a far-field Grains.csv, or a "
+                         "Laue solutions.txt / validated .npz")
+    ap.add_argument("--kind", default=None,
+                    help="NF: orientation | confidence | grain. "
+                         "FF: summary | orientation | pole | strain | size | "
+                         "completeness | 3d. "
+                         "Laue: summary | orientation | pole | tilt | size | "
+                         "sweep. "
+                         "Default: orientation for NF, summary for FF/Laue.")
+    ap.add_argument("--plane", default="xy",
+                    help="FF only: projection plane (xy, xz, yz)")
+    ap.add_argument("--hkl", default="0,0,1",
+                    help="FF pole figure: crystal direction")
+    ap.add_argument("--strain-kind", default="hydrostatic",
+                    help="FF strain: hydrostatic | vonmises | 11 | 33 | ...")
+    ap.add_argument("--sg", default=None,
+                    help="space group; a single value, or one per .mic "
+                         "comma-separated when comparing PHASES (colouring a "
+                         "cubic map with hexagonal symmetry silently produces "
+                         "a meaningless figure). Unset: 225 for near-field, "
+                         "the file's own header for far-field, 194 for Laue.")
+    ap.add_argument("--cmin", type=float, default=0.3,
+                    help="confidence cut (default 0.3, the trust floor)")
+    ap.add_argument("--axis", default="0,0,1", help="IPF sample axis")
+    ap.add_argument("--titles", default=None, help="'|'-separated")
+    ap.add_argument("--suptitle", default=None)
+    ap.add_argument("-o", "--out", default="midas_plot.png")
+    ap.add_argument("--dpi", type=int, default=145)
+    ap.add_argument("--gate", type=int, default=None,
+                    help="Laue: keep solutions matching MORE than this many "
+                         "reflections. No default -- it is the measured "
+                         "random-orientation null for that scan, not a "
+                         "universal constant.")
+    ap.add_argument("--tol", type=float, default=1.0,
+                    help="Laue: grain clustering tolerance in degrees")
+    a = ap.parse_args(argv)
+
+    import matplotlib
+    matplotlib.use("Agg")
+
+    if all(_looks_like_laue(m) for m in a.mics):
+        return _run_laue(a, ap)
+    if all(_looks_like_ff(m) for m in a.mics):
+        return _run_ff(a, ap)
+    if a.kind is None:
+        a.kind = "orientation"
+    if a.kind not in ("orientation", "confidence", "grain"):
+        ap.error(f"--kind {a.kind!r} is not valid for near-field .mic input")
+    from .maps import compare_maps
+    from .mic import read_mic
+
+    mics = [read_mic(m) for m in a.mics]
+    for m in mics:
+        print(f"{m.path.name}: {m.summary()}")
+
+    sgs = [int(v) for v in str(a.sg if a.sg is not None else "225").split(",")]
+    if len(sgs) == 1:
+        sgs *= len(mics)
+    elif len(sgs) != len(mics):
+        ap.error(f"--sg has {len(sgs)} values for {len(mics)} .mic files; "
+                 "give one value or one per file")
+
+    titles = a.titles.split("|") if a.titles else [None] * len(mics)
+    axis = tuple(float(v) for v in a.axis.split(","))
+
+    import matplotlib.pyplot as plt
+    from .maps import confidence_map, grain_map, orientation_map
+    fn = {"orientation": orientation_map, "confidence": confidence_map,
+          "grain": grain_map}[a.kind]
+    fig, axes = plt.subplots(1, len(mics), figsize=(6.2 * len(mics), 6.4),
+                             squeeze=False)
+    for ax, m, t, sg in zip(axes[0], mics, titles, sgs):
+        kw = {}
+        if a.kind == "orientation":
+            kw = dict(space_group=sg, cmin=a.cmin, axis=axis)
+        elif a.kind == "grain":
+            kw = dict(space_group=sg, cmin=a.cmin)
+        fn(m, ax=ax, title=t, **kw)
+    if a.suptitle:
+        fig.suptitle(a.suptitle, fontsize=12)
+    # `kind` (bare) used to be referenced here; it is only ever bound in the FF
+    # branch, so every near-field CLI run raised NameError after doing all the
+    # work and before writing the file. No test covered the CLI path.
+    fig.tight_layout()
+    fig.savefig(a.out, dpi=a.dpi, bbox_inches="tight")
+    print(f"wrote {Path(a.out).resolve()}")
+    return 0
+
+
+def _looks_like_ff(path) -> bool:
+    """Far-field Grains.csv, by content not by filename.
+
+    Users rename these constantly (Grains_layer1.csv, au3_grains.csv), so sniff
+    for the header MIDAS actually writes instead of matching a name.
+    """
+    p = Path(path)
+    if not p.is_file():
+        return False
+    try:
+        with p.open() as fh:
+            for _ in range(40):
+                line = fh.readline()
+                if not line:
+                    break
+                if line.startswith("%NumGrains") or "\tO11\t" in line:
+                    return True
+    except OSError:
+        return False
+    return False
+
+
+def _looks_like_laue(path) -> bool:
+    """Laue solutions.txt or a validated .npz, by content not by filename."""
+    p = Path(path)
+    if not p.is_file():
+        return False
+    if p.suffix == ".npz":
+        try:
+            import numpy as np
+            with np.load(p, allow_pickle=True) as d:
+                return {"oms", "X", "Z", "nhit"} <= set(d.files)
+        except Exception:
+            return False
+    try:
+        with p.open() as fh:
+            head = fh.readline()
+    except OSError:
+        return False
+    return head.startswith("%ImageNr") and "OrientMatrix0" in head
+
+
+def _run_laue(a, ap) -> int:
+    """Laue plotting branch."""
+    import matplotlib.pyplot as plt
+
+    from . import laue
+    from .solutions import read_solutions, read_validated
+
+    kind = a.kind or "summary"
+    if a.sg is None:
+        sg = 194
+        print("note: --sg not given, using 194 (hexagonal). The wrong symmetry "
+              "silently changes grain counts, so pass it for another phase.")
+    else:
+        sg = int(str(a.sg).split(",")[0])
+    hkl = tuple(float(v) for v in a.hkl.split(","))
+
+    sols = [read_validated(m) if str(m).endswith(".npz") else read_solutions(m)
+            for m in a.mics]
+    for s in sols:
+        print(f"{Path(s.path).name}: {s.summary()}")
+    if a.gate is not None:
+        sols = [s.gate(a.gate) for s in sols]
+        for s in sols:
+            print(f"  after gate >{a.gate}: {len(s)} solutions")
+    else:
+        print("note: no --gate given, so every solution is plotted including "
+              "ones a randomly oriented crystal could produce.")
+
+    if kind == "summary":
+        if len(sols) != 1:
+            ap.error("--kind summary takes exactly one Laue input")
+        fig = laue.summary(sols[0], tolerance=a.tol, space_group=sg, hkl=hkl)
+    else:
+        fig, axes = plt.subplots(1, len(sols),
+                                 figsize=(6.2 * len(sols), 5.4), squeeze=False)
+        for ax, s in zip(axes[0], sols):
+            if kind == "orientation":
+                laue.orientation_map(s, ax, hkl=hkl)
+            elif kind in ("pole", "tilt", "size"):
+                c = laue.cluster(s, a.tol, space_group=sg)
+                reps = c.representatives(s.orient_mat)
+                if kind == "pole":
+                    laue.pole_figure(reps, ax, hkl=hkl)
+                elif kind == "tilt":
+                    laue.tilt_histogram(reps, ax, hkl=hkl)
+                else:
+                    laue.grain_size_distribution(c, ax)
+            elif kind == "sweep":
+                laue.tolerance_sweep(s, ax, space_group=sg)
+            else:
+                ap.error(f"--kind {kind!r} is not valid for Laue input; use "
+                         "summary, orientation, pole, tilt, size or sweep")
+        fig.tight_layout()
+    if a.suptitle:
+        fig.suptitle(a.suptitle, fontsize=12)
+    fig.savefig(a.out, dpi=a.dpi, bbox_inches="tight")
+    print(f"wrote {Path(a.out).resolve()}")
+    return 0
+
+
+def _run_ff(a, ap) -> int:
+    """Far-field plotting branch."""
+    import matplotlib.pyplot as plt
+
+    from . import ff
+    from .grains import read_grains
+
+    kind = a.kind or "summary"
+    axis = tuple(float(v) for v in a.axis.split(","))
+    # Unset means "use the file's own header" -- Grains.csv states its space
+    # group, and overriding it with a default would colour a hexagonal sample
+    # through the cubic triangle and produce a plausible, wrong figure.
+    sg = None if a.sg in (None, "", "auto") else int(str(a.sg).split(",")[0])
+
+    grains = [read_grains(m) for m in a.mics]
+    for g in grains:
+        print(f"{g.path.name}: {len(g)} grains, space group "
+              f"{g.space_group if sg is None else sg}")
+
+    if kind == "summary":
+        if len(grains) != 1:
+            ap.error("--kind summary takes exactly one Grains.csv")
+        fig = ff.summary(grains[0], space_group=sg, cmin=a.cmin, axis=axis)
+    else:
+        fns = {
+            "orientation": lambda g, ax: ff.grain_map(
+                g, ax, plane=a.plane, space_group=sg, axis=axis, cmin=a.cmin),
+            "pole": lambda g, ax: ff.pole_figure(
+                g, ax, hkl=tuple(float(v) for v in a.hkl.split(",")),
+                space_group=sg, cmin=a.cmin, axis=axis),
+            "strain": lambda g, ax: ff.strain_map(
+                g, ax, kind=a.strain_kind, plane=a.plane, cmin=a.cmin),
+            "size": lambda g, ax: ff.grain_size_distribution(g, ax, cmin=a.cmin),
+            "completeness": lambda g, ax: ff.completeness_hist(g, ax),
+        }
+        if kind == "3d":
+            fig = plt.figure(figsize=(6.6 * len(grains), 6.0))
+            for k, g in enumerate(grains):
+                ax = fig.add_subplot(1, len(grains), k + 1, projection="3d")
+                ff.grain_map_3d(g, ax, space_group=sg, axis=axis, cmin=a.cmin)
+        elif kind in fns:
+            fig, axes = plt.subplots(1, len(grains),
+                                     figsize=(6.2 * len(grains), 5.6),
+                                     squeeze=False)
+            for ax, g in zip(axes[0], grains):
+                fns[kind](g, ax)
+        else:
+            ap.error(f"--kind {kind!r} is not valid for far-field input; use "
+                     "summary, orientation, pole, strain, size, completeness "
+                     "or 3d")
+    if a.suptitle:
+        fig.suptitle(a.suptitle, fontsize=12)
+    fig.tight_layout()
+    fig.savefig(a.out, dpi=a.dpi, bbox_inches="tight")
+    print(f"wrote {Path(a.out).resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())