de-ebsd 0.2.0__py3-none-any.whl

de_ebsd/viz/figures.py

@@ -0,0 +1,67 @@
+"""Shared anyplotlib primitives.
+
+Every ``.show()`` in de_ebsd renders through :mod:`de_ebsd.viz`, so the
+package has one way to draw. Helpers return an ``anyplotlib.Figure``:
+interactive in Jupyter, exportable via ``figure.save_html(path)``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["apl", "bar_figure", "image_figure", "label", "to_uint8_rgb"]
+
+
+def apl():
+    """Import anyplotlib lazily so headless jobs never pay for the display stack."""
+    try:
+        import anyplotlib
+    except ImportError as error:  # pragma: no cover
+        raise ImportError(
+            "anyplotlib is required for .show(); install it with `pip install anyplotlib`"
+        ) from error
+    return anyplotlib
+
+
+def label(panel, title: str) -> None:
+    """Attach a title to a plot panel if the panel supports one."""
+    if not title:
+        return
+    for method in ("set_title", "set_label"):
+        setter = getattr(panel, method, None)
+        if callable(setter):
+            try:
+                setter(title)
+            except Exception:  # noqa: BLE001 - a missing title must never break .show()
+                pass
+            return
+
+
+def to_uint8_rgb(image: np.ndarray) -> np.ndarray:
+    """Normalize a 2D array to a grayscale (H, W, 3) uint8 texture."""
+    image = np.asarray(image, dtype=np.float64)
+    lo, hi = float(np.nanmin(image)), float(np.nanmax(image))
+    scale = 255.0 / (hi - lo) if hi > lo else 0.0
+    gray = ((image - lo) * scale).astype(np.uint8)
+    return np.repeat(gray[..., None], 3, axis=-1)
+
+
+def bar_figure(values, labels, title: str = "", colors=None):
+    """Bar chart of one value per labeled item (structure factors, reflections)."""
+    values = np.asarray(values, dtype=np.float64)
+    fig, ax = apl().subplots(1, 1, figsize=(max(560, 18 * len(values)), 340))
+    kwargs = {"x_labels": list(labels), "show_values": False}
+    if colors is not None:
+        kwargs["colors"] = list(colors)
+    else:
+        kwargs["color"] = "#4fc3f7"
+    label(ax.bar(values, **kwargs), title)
+    return fig
+
+
+def image_figure(image: np.ndarray, title: str = "", cmap: str = "gray"):
+    """Single image panel. Row 0 is drawn at the bottom (Lambert +Y up)."""
+    image = np.asarray(image, dtype=np.float64)
+    fig, ax = apl().subplots(1, 1, figsize=(520, 520))
+    label(ax.imshow(image, cmap=cmap, origin="lower"), title)
+    return fig

de_ebsd/viz/maps.py

@@ -0,0 +1,277 @@
+"""Indexing result figures: pattern match, orientation map, SO(3) correlation."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from de_ebsd.core.constants import DIVISION_FLOOR
+from de_ebsd.viz.figures import apl, label
+
+__all__ = ["show_correlation", "show_map", "show_match", "show_refinement"]
+
+
+def _to_numpy(x) -> np.ndarray:
+    detach = getattr(x, "detach", None)
+    if detach is not None:
+        x = detach().cpu().numpy()
+    return np.asarray(x, dtype=np.float64)
+
+
+def _to_image(x) -> np.ndarray:
+    image = np.squeeze(_to_numpy(x))
+    if image.ndim != 2:
+        raise ValueError(f"expected a 2-D pattern, got shape {image.shape}")
+    return image
+
+
+def _standardize(image: np.ndarray) -> np.ndarray:
+    image = image - image.mean()
+    std = float(image.std())
+    return image / std if std > DIVISION_FLOOR else image
+
+
+def _ncc(a: np.ndarray, b: np.ndarray) -> float:
+    a0 = a - a.mean()
+    b0 = b - b.mean()
+    na = float(np.linalg.norm(a0))
+    nb = float(np.linalg.norm(b0))
+    if na < DIVISION_FLOOR or nb < DIVISION_FLOOR:
+        return 0.0
+    return float(np.vdot(a0, b0) / (na * nb))
+
+
+def show_match(experimental, master, detector, orientation, energy_kev=None):
+    """The indexing sanity check: experimental vs simulated pattern at the fit.
+
+    Renders three panels side by side -- the experimental pattern, the pattern
+    :meth:`de_ebsd.sim.MasterPattern.project` produces at the indexed
+    ``orientation``, and their (contrast-standardized) difference -- so a viewer
+    can see at a glance whether the orientation is right. The middle panel is
+    titled with the normalized cross-correlation (:func:`_ncc`) between the
+    experimental and simulated patterns: a contrast-invariant number in
+    ``[-1, 1]`` that quantifies the match (``~1`` is a good index).
+
+    Parameters
+    ----------
+    experimental
+        The measured detector image ``(H, W)`` (numpy array or torch tensor;
+        a leading length-1 axis is squeezed).
+    master
+        The :class:`de_ebsd.sim.MasterPattern` used for indexing.
+    detector
+        The :class:`de_ebsd.sim.detector.EBSDDetector` geometry.
+    orientation
+        The indexed orientation as a length-1 :class:`orix.quaternion.Rotation`
+        (e.g. a single element of :meth:`SphericalIndexer.index`'s output).
+    energy_kev
+        Energy bin to project (default: the master's highest).
+
+    Returns
+    -------
+    anyplotlib.Figure
+        A 1x3 figure (experimental | simulated | difference).
+    """
+    exp = _to_image(experimental)
+    sim = _to_image(master.project(detector, orientation, energy_kev=energy_kev))
+    if sim.shape != exp.shape:
+        raise ValueError(
+            f"simulated pattern {sim.shape} does not match experimental {exp.shape}; "
+            "check the detector shape and orientation length (must be 1)"
+        )
+    diff = _standardize(exp) - _standardize(sim)
+    score = _ncc(exp, sim)
+
+    fig, axes = apl().subplots(1, 3, figsize=(1140, 400))
+    ax_e, ax_s, ax_d = np.ravel(axes)[:3]
+    label(ax_e.imshow(exp, cmap="gray", origin="lower"), "experimental")
+    label(ax_s.imshow(sim, cmap="gray", origin="lower"), f"simulated  |  NCC = {score:.3f}")
+    label(ax_d.imshow(diff, cmap="coolwarm", origin="lower"), "difference")
+    fig.match_ncc = score
+    return fig
+
+
+def _ipf_rgb(crystal_map) -> np.ndarray:
+    from orix.plot import IPFColorKeyTSL
+    from orix.vector import Vector3d
+
+    point_group = crystal_map.phases[crystal_map.phase_id[0]].point_group
+    key = IPFColorKeyTSL(point_group, direction=Vector3d.zvector())
+    rgb = key.orientation2color(crystal_map.rotations)  # (N, 3) floats in [0, 1]
+    rgb = np.asarray(rgb, dtype=np.float64).reshape(*crystal_map.shape, 3)
+    return (np.clip(rgb, 0.0, 1.0) * 255.0).astype(np.uint8)
+
+
+def _quality_image(crystal_map) -> np.ndarray:
+    if "quality" not in crystal_map.prop:
+        raise KeyError("crystal_map.prop has no 'quality'; index_scan stores it there")
+    return np.asarray(crystal_map.prop["quality"], dtype=np.float64).reshape(crystal_map.shape)
+
+
+def show_map(crystal_map, value: str = "ipf"):
+    """Show an indexed scan (orix ``CrystalMap``) as an IPF and/or quality map.
+
+    Parameters
+    ----------
+    crystal_map
+        The :class:`orix.crystal_map.CrystalMap` from
+        :meth:`SphericalIndexer.index_scan` (single phase, ``prop['quality']``
+        holding the per-point score).
+    value
+        Which map(s) to draw:
+
+        * ``"ipf"`` (default) -- the IPF-z orientation map (orix TSL coloring);
+        * ``"quality"`` -- the ``prop['quality']`` field, sequential colormap;
+        * ``"both"`` -- the two side by side in a 1x2 figure.
+
+    Returns
+    -------
+    anyplotlib.Figure
+        A single-panel figure (``"ipf"`` / ``"quality"``) or a 1x2 figure
+        (``"both"``). Row 0 of the scan is drawn at the top (``origin="upper"``).
+    """
+    if value not in ("ipf", "quality", "both"):
+        raise ValueError("value must be 'ipf', 'quality', or 'both'")
+
+    if value == "both":
+        fig, axes = apl().subplots(1, 2, figsize=(1000, 480))
+        ax_ipf, ax_q = np.ravel(axes)[:2]
+        label(ax_ipf.imshow(_ipf_rgb(crystal_map), origin="upper"), "IPF-z")
+        panel_q = ax_q.imshow(_quality_image(crystal_map), cmap="viridis", origin="upper")
+        label(panel_q, "quality")
+        _colorbar_label(panel_q, "quality")
+        return fig
+
+    fig, ax = apl().subplots(1, 1, figsize=(560, 520))
+    if value == "ipf":
+        label(ax.imshow(_ipf_rgb(crystal_map), origin="upper"), "IPF-z orientation map")
+    else:
+        panel = ax.imshow(_quality_image(crystal_map), cmap="viridis", origin="upper")
+        label(panel, "quality map")
+        _colorbar_label(panel, "quality")
+    return fig
+
+
+def _colorbar_label(panel, text: str) -> None:
+    setter = getattr(panel, "set_colorbar_label", None)
+    if callable(setter):
+        try:
+            setter(text)
+        except Exception:  # noqa: BLE001 - a missing colorbar must never break .show()
+            pass
+
+
+def show_correlation(correlation):
+    """Render the SO(3) cross-correlation volume as a legible 2-D heatmap.
+
+    The cross-correlation from
+    :func:`de_ebsd.index.spherical.correlation.so3_cross_correlation` is a function on
+    all of SO(3), sampled on the ``(alpha, beta, gamma)`` grid (shape
+    ``(N, N, N)``). This reduces it to an ``(alpha, gamma)`` heatmap by taking
+    the maximum over the ``beta`` axis (so the global peak survives the
+    projection), marks the peak cell, and titles the panel with the peak value
+    and its ``(alpha, beta, gamma)`` grid indices.
+
+    Parameters
+    ----------
+    correlation
+        The correlation grid, shape ``(N, N, N)`` for a single pattern, or a
+        stack ``(Np, N, N, N)`` whose **first** pattern is shown (numpy array or
+        torch tensor). Obtain it from
+        :meth:`~de_ebsd.index.spherical.indexer.SphericalIndexer.index` with
+        ``return_surface=True`` (the third returned element).
+
+    Returns
+    -------
+    anyplotlib.Figure
+        A single heatmap panel with the peak marked. The peak grid indices and
+        value are also attached to the figure as ``fig.peak_index`` (an
+        ``(alpha, beta, gamma)`` tuple) and ``fig.peak_value`` for programmatic
+        access.
+    """
+    corr = _to_numpy(correlation)
+    if corr.ndim == 4:
+        corr = corr[0]
+    if corr.ndim != 3:
+        raise ValueError(f"correlation must be (N, N, N) or (Np, N, N, N), got shape {corr.shape}")
+
+    a_idx, b_idx, g_idx = (int(i) for i in np.unravel_index(int(np.argmax(corr)), corr.shape))
+    peak = float(corr[a_idx, b_idx, g_idx])
+    projection = corr.max(axis=1)  # (alpha, gamma), max over beta -- keeps the global peak
+
+    fig, ax = apl().subplots(1, 1, figsize=(620, 560))
+    panel = ax.imshow(projection, cmap="magma", origin="lower")
+    label(
+        panel,
+        f"SO(3) correlation (max over beta)  |  peak {peak:.4g} "
+        f"at (a, b, g) = ({a_idx}, {b_idx}, {g_idx})",
+    )
+    _ax_setter(panel, "set_xlabel", "gamma index")
+    _ax_setter(panel, "set_ylabel", "alpha index")
+    # mark the peak: heatmap x is the gamma index, y is the alpha index
+    try:
+        panel.add_points([(g_idx, a_idx)], color="#4fc3f7", sizes=14, alpha=0.9)
+    except Exception:  # noqa: BLE001 - the title already reports the peak location
+        pass
+
+    fig.peak_index = (a_idx, b_idx, g_idx)
+    fig.peak_value = peak
+    return fig
+
+
+def _ax_setter(panel, method: str, value: str) -> None:
+    setter = getattr(panel, method, None)
+    if callable(setter):
+        try:
+            setter(value)
+        except Exception:  # noqa: BLE001 - a missing axis label must never break .show()
+            pass
+
+
+def show_refinement(history):
+    """Plot the refinement NCC trajectory (convergence) vs iteration.
+
+    Parameters
+    ----------
+    history
+        The per-iteration NCC trajectory from
+        :func:`de_ebsd.index.refine.orientation.refine_orientation` (``return_history=True``),
+        shape ``(n_iterations, Np)`` -- one column per pattern -- or ``(n_iterations,)`` for a
+        single pattern (numpy array or torch tensor). ``history[0]`` is the seed's
+        score at ``w = 0``.
+
+    Returns
+    -------
+    anyplotlib.Figure
+        A line plot of NCC against iteration: one thin curve per pattern, plus a
+        thick mean curve when more than one pattern is refined.
+    """
+    hist = _to_numpy(history)
+    if hist.ndim == 1:
+        hist = hist[:, None]
+    if hist.ndim != 2:
+        raise ValueError(
+            f"history must be (n_iterations, Np) or (n_iterations,), got shape {hist.shape}"
+        )
+    n_iterations, n_p = hist.shape
+    iters = np.arange(n_iterations, dtype=np.float64)
+
+    fig, ax = apl().subplots(1, 1, figsize=(680, 420))
+    per_pattern_label = "per pattern" if n_p > 1 else "NCC"
+    plot = ax.plot(
+        hist[:, 0],
+        axes=[iters],
+        units="iteration",
+        y_units="NCC",
+        color="#4fc3f7",
+        linewidth=1.0 if n_p > 1 else 2.0,
+        alpha=0.5 if n_p > 1 else 1.0,
+        label=per_pattern_label,
+    )
+    for p in range(1, n_p):
+        plot.add_line(hist[:, p], x_axis=iters, color="#4fc3f7", linewidth=1.0, alpha=0.5)
+    if n_p > 1:
+        plot.add_line(hist.mean(axis=1), x_axis=iters, color="#ff7043", linewidth=2.5, label="mean")
+    _ax_setter(plot, "set_title", "Refinement convergence")
+    _ax_setter(plot, "set_xlabel", "iteration")
+    _ax_setter(plot, "set_ylabel", "NCC")
+    return fig

de_ebsd/viz/patterns.py

@@ -0,0 +1,164 @@
+"""Master-pattern, crystal-structure and direction-sampling figures."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from de_ebsd.viz.figures import apl, label, to_uint8_rgb
+
+__all__ = [
+    "crystal_structure_figure",
+    "hemispheres_figure",
+    "phase_overview_figure",
+    "sampling_sphere_figure",
+    "sphere_figure",
+]
+
+_ELEMENT_COLORS = {
+    "H": (1.00, 1.00, 1.00),
+    "C": (0.36, 0.40, 0.45),
+    "N": (0.25, 0.40, 0.95),
+    "O": (0.93, 0.20, 0.22),
+    "Al": (0.75, 0.65, 0.65),
+    "Si": (0.94, 0.66, 0.48),
+    "Ti": (0.75, 0.76, 0.78),
+    "Cr": (0.54, 0.60, 0.78),
+    "Mn": (0.61, 0.48, 0.78),
+    "Fe": (0.88, 0.40, 0.20),
+    "Co": (0.94, 0.56, 0.63),
+    "Ni": (0.31, 0.82, 0.31),
+    "Cu": (0.78, 0.50, 0.20),
+    "Zn": (0.49, 0.50, 0.69),
+}
+_DEFAULT_COLOR = (0.40, 0.75, 0.90)
+
+
+def hemispheres_figure(north: np.ndarray, south: np.ndarray, title: str = "", cmap: str = "gray"):
+    """North and south hemisphere maps side by side."""
+    fig, axes = apl().subplots(1, 2, figsize=(940, 470))
+    ax_n, ax_s = np.ravel(axes)[:2]
+    panel_n = ax_n.imshow(np.asarray(north, dtype=np.float64), cmap=cmap, origin="lower")
+    panel_s = ax_s.imshow(np.asarray(south, dtype=np.float64), cmap=cmap, origin="lower")
+    label(panel_n, f"{title} - north" if title else "north")
+    label(panel_s, f"{title} - south" if title else "south")
+    return fig
+
+
+def sphere_figure(
+    equirectangular: np.ndarray,
+    title: str = "",
+    azimuth: float = -60.0,
+    elevation: float = 30.0,
+    n_grid: int = 96,
+):
+    """The master pattern textured onto an interactive 3D sphere.
+
+    ``equirectangular`` is sampled on a latitude/longitude grid: row 0 is the
+    north pole, columns span longitude -pi..pi (``MasterPattern.to_equirectangular``).
+    """
+    fig, ax = apl().subplots(1, 1, figsize=(560, 560))
+    _sphere_panel(ax, equirectangular, title, azimuth, elevation, n_grid)
+    return fig
+
+
+def _sphere_panel(ax, equirectangular, title, azimuth, elevation, n_grid):
+    theta = np.linspace(0.0, np.pi, n_grid)
+    phi = np.linspace(-np.pi, np.pi, 2 * n_grid)
+    t, p = np.meshgrid(theta, phi, indexing="ij")
+    x = np.sin(t) * np.cos(p)
+    y = np.sin(t) * np.sin(p)
+    z = np.cos(t)
+
+    surface = ax.plot_surface(
+        x, y, z, bounds=((-1.0, 1.0),) * 3, azimuth=azimuth, elevation=elevation, gpu="auto"
+    )
+    surface.set_texture(to_uint8_rgb(equirectangular), cull_backfaces=True)
+    label(surface, title)
+    return surface
+
+
+def phase_overview_figure(crystal, equirectangular: np.ndarray, *, name="Phase", n_grid=96):
+    """Dominant master pattern and compact structure in one figure.
+
+    One figure means one anywidget in Jupyter and one registration through
+    SpyDE's Electron bridge.
+    """
+    fig, axes = apl().subplots(1, 2, figsize=(820, 400), width_ratios=[1.45, 1.0])
+    master_ax, crystal_ax = np.ravel(axes)[:2]
+    _sphere_panel(master_ax, equirectangular, f"{name} master pattern", -60.0, 30.0, n_grid)
+    _crystal_structure_panel(crystal_ax, crystal, f"{name} structure")
+    return fig
+
+
+def crystal_structure_figure(crystal, title: str = ""):
+    """Expanded atoms of one unit cell as a 3-D plot, in Cartesian nanometres."""
+    fig, ax = apl().subplots(1, 1, figsize=(480, 420))
+    _crystal_structure_panel(ax, crystal, title or "Crystal structure")
+    return fig
+
+
+def _crystal_structure_panel(ax, crystal, title: str):
+    fractional = np.concatenate(crystal.positions, axis=0)
+    elements = [
+        site.element
+        for site, positions in zip(crystal.sites, crystal.positions, strict=True)
+        for _ in positions
+    ]
+    cartesian = fractional @ crystal.direct_structure_matrix.T
+    colors = np.asarray([_ELEMENT_COLORS.get(e, _DEFAULT_COLOR) for e in elements])
+
+    # include the cell corners so non-orthogonal cells are not clipped
+    corners = np.asarray([[i, j, k] for i in (0.0, 1.0) for j in (0.0, 1.0) for k in (0.0, 1.0)])
+    extent = np.vstack((cartesian, corners @ crystal.direct_structure_matrix.T))
+    lo, hi = extent.min(axis=0), extent.max(axis=0)
+    padding = 0.08 * np.maximum(hi - lo, 1e-6)
+    bounds = tuple((float(a), float(b)) for a, b in zip(lo - padding, hi + padding, strict=True))
+
+    points = ax.scatter3d(
+        cartesian[:, 0],
+        cartesian[:, 1],
+        cartesian[:, 2],
+        colors=colors,
+        point_size=max(5.0, min(12.0, 48.0 / np.sqrt(len(cartesian)))),
+        bounds=bounds,
+        x_label="x (nm)",
+        y_label="y (nm)",
+        z_label="z (nm)",
+        azimuth=-55.0,
+        elevation=24.0,
+        gpu="auto",
+    )
+    label(points, title)
+    return points
+
+
+def sampling_sphere_figure(directions: np.ndarray, title: str = "Incident-direction sampling"):
+    """Sampled unit directions on an interactive reference sphere.
+
+    The first half of ``directions`` is colored as the northern hemisphere and
+    the second half as the southern, matching ``KVectorGrid.flat``.
+    """
+    directions = np.asarray(directions, dtype=np.float64).reshape(-1, 3)
+    if directions.size == 0 or directions.shape[1] != 3:
+        raise ValueError("directions must have shape (N, 3) and contain at least one vector")
+
+    n_north = directions.shape[0] // 2
+    colors = np.empty((directions.shape[0], 3), dtype=np.float64)
+    colors[:n_north] = (0.35, 0.71, 0.98)
+    colors[n_north:] = (0.98, 0.63, 0.36)
+
+    fig, ax = apl().subplots(1, 1, figsize=(560, 560))
+    points = ax.scatter3d(
+        directions[:, 0],
+        directions[:, 1],
+        directions[:, 2],
+        colors=colors,
+        point_size=3.0,
+        bounds=((-1.0, 1.0),) * 3,
+        azimuth=-60.0,
+        elevation=30.0,
+        gpu="auto",
+    )
+    points.set_sphere(radius=1.0, color="#9aa4b2", alpha=0.10, wireframe=True)
+    label(points, title)
+    return fig

de_ebsd/viz/setup_widget.js

@@ -0,0 +1,171 @@
+// Detector geometry mirrors core.geometry.sample_to_detector_matrix (row vectors).
+// Exported separately so parity with Python can be tested without a browser.
+export function setupGeometry(s) {
+  const rad = a => a * Math.PI / 180;
+  const cross = (a,b) => [a[1]*b[2]-a[2]*b[1],a[2]*b[0]-a[0]*b[2],a[0]*b[1]-a[1]*b[0]];
+  let basis = [[0,1,0],[0,0,1],[1,0,0]];
+  for (const [axis, angle] of [[0,-s.sample_tilt],[0,s.detector_tilt],[1,-s.azimuthal],[2,-s.twist]]) {
+    const u=basis[axis], c=Math.cos(rad(angle)), sn=Math.sin(rad(angle));
+    basis=basis.map(v => {
+      const uv=cross(u,v), dot=u.reduce((sum,x,i)=>sum+x*v[i],0);
+      return v.map((x,i)=>x*c+uv[i]*sn+u[i]*dot*(1-c));
+    });
+  }
+  const H=s.detector_rows*s.px_size/1000, W=s.detector_cols*s.px_size/1000, L=s.pcz*H;
+  const toSample = v => [0,1,2].map(j => v.reduce((sum,x,i)=>sum+x*basis[i][j],0));
+  const c=Math.cos(rad(s.sample_tilt)), sn=Math.sin(rad(s.sample_tilt));
+  // Laboratory X horizontal, Z vertical; positive sample tilt slopes down right.
+  const toLab = v => [c*v[0]+sn*v[2],v[1],-sn*v[0]+c*v[2]];
+  const corners=[[-s.pcx*W,s.pcy*H,L],[(1-s.pcx)*W,s.pcy*H,L],
+    [(1-s.pcx)*W,-(1-s.pcy)*H,L],[-s.pcx*W,-(1-s.pcy)*H,L]].map(toSample);
+  const pc=toSample([0,0,L]);
+  return {H,W,L,corners,lab:corners.map(toLab),pc,pcLab:toLab(pc),normal:[sn,0,c],
+    tangent:[c,0,-sn], center:corners[0].map((_,j)=>corners.reduce((sum,v)=>sum+v[j],0)/4),
+    planeAngle:Math.acos(Math.min(1,Math.abs(basis[2][2])))*180/Math.PI,
+    footprint:s.probe_diameter_nm>0 && c>1e-12 ? [s.probe_diameter_nm/c,s.probe_diameter_nm] : null};
+}
+
+function render({model,el}) {
+  const host=el.shadowRoot || el.attachShadow({mode:"open"});
+  host.innerHTML=`<style>
+    :host {display:block; max-width:580px; color-scheme:light dark}
+    * {box-sizing:border-box}
+    .setup {--fg:var(--spyde-fg,var(--jp-ui-font-color1,light-dark(#242a33,#d8dee9)));
+      --bg:var(--spyde-panel-bg,var(--jp-layout-color1,light-dark(#f6f7f9,#20242d)));
+      --line:var(--spyde-border,var(--jp-border-color2,light-dark(#ccd0d7,#4c5565)));
+      --beam:var(--spyde-accent,light-dark(#1672b8,#5ba7f7)); --sample:light-dark(#a45c17,#e5a05c);
+      --screen:light-dark(#197349,#66c58a); --pc:light-dark(#ad2858,#f080a6);
+      color:var(--fg);background:var(--bg);border:1px solid var(--line);border-radius:6px;
+      font:12px var(--jp-ui-font-family,system-ui,sans-serif);overflow:hidden}
+    header {padding:9px 12px;border-bottom:1px solid var(--line);display:flex;gap:10px;flex-wrap:wrap}
+    header span {margin-left:auto} svg {display:block;width:100%;font:12px system-ui;touch-action:manipulation}
+    svg text {fill:var(--fg)} .insets {display:grid;grid-template-columns:1fr 1fr;border-top:1px solid var(--line)}
+    .controls {padding:10px 12px;display:grid;grid-template-columns:1fr 1fr;gap:7px 14px;border-top:1px solid var(--line)}
+    label {display:flex;align-items:center;justify-content:space-between;gap:6px;min-width:0}
+    input {font:inherit;color:inherit;background:var(--bg);border:1px solid var(--line);border-radius:3px;
+      width:84px;min-width:0;padding:3px 5px} .facts,.note {padding:7px 12px;line-height:1.55}
+    .facts {border-top:1px solid var(--line);font-variant-numeric:tabular-nums} .note {font-size:11px}
+    @media(max-width:400px) {.insets {grid-template-columns:1fr}.controls {gap:7px}.controls label {flex-wrap:wrap}.controls input {width:100%}}
+  </style><section class="setup"><header><strong>Microscope / detector</strong><span></span></header>
+  <svg class="geometry" height="250" role="img" aria-label="Laboratory side view: beam, sample normal and detector"></svg>
+  <div class="insets"><svg class="face" height="175" role="img" aria-label="Detector face and Bruker pattern center"></svg>
+  <svg class="probe" height="175" role="img" aria-label="Geometric probe footprint on the sample"></svg></div>
+  <div class="facts" aria-live="polite"></div><div class="controls"></div>
+  <div class="note">Geometry editor only: existing simulation results do not change. In Jupyter, read edits with
+  <code>to_microscope()</code> / <code>to_detector()</code>, then recompute. Screen pitch includes binning.</div></section>`;
+  const root=host.querySelector('.setup'), main=host.querySelector('.geometry'), face=host.querySelector('.face'),
+    probe=host.querySelector('.probe'), controls=host.querySelector('.controls'), facts=host.querySelector('.facts');
+  const fields=[['energy_kev','Beam (keV)',0.001,null,0.1],['sample_tilt','Incidence (°)',0,90,0.1],
+    ['probe_diameter_nm','Probe Ø (nm; 0 = unset)',0,null,1],['detector_tilt','Screen tilt from vertical (°)',-90,90,0.1],
+    ['pcx','PCx / width',null,null,0.001],['pcy','PCy / height',null,null,0.001],
+    ['pcz','PCz / height',0.000001,null,0.001],['px_size','Screen pitch (µm)',0.000001,null,1],
+    ['detector_rows','Rows',1,null,1],['detector_cols','Columns',1,null,1],
+    ['azimuthal','Azimuth (°)',-180,180,0.1],['twist','Screen twist (°)',-180,180,0.1]];
+  const inputs=new Map();
+  for (const [key,label,min,max,step] of fields) {
+    const wrapper=document.createElement('label'), input=document.createElement('input');
+    wrapper.append(document.createTextNode(label)); input.type='number'; input.step=step;
+    if(min!==null) input.min=min; if(max!==null) input.max=max;
+    input.setAttribute('aria-label',label); wrapper.append(input); controls.append(wrapper); inputs.set(key,input);
+    input.addEventListener('change',()=>{
+      if(input.value.trim()==='' || !input.checkValidity() || !Number.isFinite(input.valueAsNumber)) {
+        input.reportValidity(); input.value=model.get(key); return;
+      }
+      model.set(key,input.valueAsNumber); model.save_changes();
+    });
+  }
+  const node=(svg,tag,attrs={},text='')=>{
+    const n=document.createElementNS('http://www.w3.org/2000/svg',tag);
+    for(const [k,v] of Object.entries(attrs)) n.setAttribute(k,v);
+    n.textContent=text; svg.append(n); return n;
+  };
+  const text=(svg,x,y,value,anchor='start')=>node(svg,'text',{x,y,'text-anchor':anchor},value);
+  const line=(svg,a,b,color,width=1,dash='')=>node(svg,'line',
+    {x1:a[0],y1:a[1],x2:b[0],y2:b[1],stroke:color,'stroke-width':width,'stroke-dasharray':dash});
+  const arrow=(svg,a,b,color)=>{
+    line(svg,a,b,color,2); const angle=Math.atan2(b[1]-a[1],b[0]-a[0]);
+    const p=[b,[b[0]-8*Math.cos(angle-.4),b[1]-8*Math.sin(angle-.4)],
+      [b[0]-8*Math.cos(angle+.4),b[1]-8*Math.sin(angle+.4)]];
+    node(svg,'polygon',{points:p.map(v=>v.join(',')).join(' '),fill:color});
+  };
+  const fmt=n=>Number(n).toFixed(2);
+  function draw() {
+    const s=Object.fromEntries(fields.map(([key])=>[key,Number(model.get(key))]));
+    const g=setupGeometry(s), has=model.get('has_detector');
+    const css=getComputedStyle(root), beam=css.getPropertyValue('--beam'), sample=css.getPropertyValue('--sample'),
+      screen=css.getPropertyValue('--screen'), pcColor=css.getPropertyValue('--pc');
+    for(const [key,input] of inputs) if(input!==host.activeElement) input.value=s[key];
+    host.querySelector('header span').textContent=`${model.get('crystal_label') || 'Sample'} · ${fmt(s.energy_kev)} keV`;
+    for(const svg of [main,face,probe]) {svg.replaceChildren(); svg.setAttribute('viewBox',`0 0 ${svg.clientWidth || 280} ${svg.getAttribute('height')}`);}
+    const w=main.clientWidth||560, H=250, size=has?Math.max(g.H,g.W,g.L):1;
+    const scaleVec=(v,n)=>v.map(x=>x*n);
+    const a=scaleVec(g.tangent,-size*.42), b=scaleVec(g.tangent,size*.42),
+      normal=scaleVec(g.normal,size*.40), source=[0,0,size*.72];
+    const all=[a,b,normal,source,[0,0,0],...(has?g.lab:[])];
+    const xmin=Math.min(...all.map(p=>p[0])),xmax=Math.max(...all.map(p=>p[0]));
+    const zmin=Math.min(...all.map(p=>p[2])),zmax=Math.max(...all.map(p=>p[2]));
+    const k=Math.min((w-96)/(xmax-xmin),(H-76)/(zmax-zmin));
+    const P=v=>[48+(w-96-(xmax-xmin)*k)/2+(v[0]-xmin)*k,40+(zmax-v[2])*k];
+    const origin=P([0,0,0]), A=P(a), B=P(b);
+    text(main,12,18,'Laboratory side view · equal mm scale');
+    const back=v=>v.map((x,i)=>x-size*.07*g.normal[i]);
+    node(main,'polygon',{points:[a,b,back(b),back(a)].map(v=>P(v).join(',')).join(' '),fill:sample,opacity:.25});
+    line(main,A,B,sample,4); arrow(main,origin,P(normal),sample); arrow(main,P(source),origin,beam);
+    text(main,P(source)[0]-8,P(source)[1]+9,'beam','end');
+    text(main,P(normal)[0]+5,P(normal)[1]+4,'n');
+    text(main,12,H-10,`Incidence ${s.sample_tilt.toFixed(1)}° from n · grazing ${(90-s.sample_tilt).toFixed(1)}°`);
+    const r=28, end=[origin[0]+r*g.normal[0],origin[1]-r*g.normal[2]];
+    node(main,'path',{d:`M ${origin[0]} ${origin[1]-r} A ${r} ${r} 0 0 1 ${end[0]} ${end[1]}`,
+      fill:'none',stroke:sample,'stroke-width':1.5});
+    node(main,'circle',{cx:origin[0],cy:origin[1],r:3,fill:beam});
+    if(has) {
+      node(main,'polygon',{points:g.lab.map(v=>P(v).join(',')).join(' '),fill:screen,'fill-opacity':.2,stroke:screen,'stroke-width':3});
+      const pc=P(g.pcLab); line(main,origin,pc,pcColor,1.5,'4 3');
+      node(main,'circle',{cx:pc[0],cy:pc[1],r:4,fill:pcColor}); text(main,pc[0]+7,pc[1]-7,'PC');
+      text(main,w-12,34,`normal distance ${fmt(g.L)} mm`,'end');
+      text(main,w-12,51,`screen / sample planes: ${g.planeAngle.toFixed(1)}°`,'end');
+    }
+    // Detector face, independent of the side projection; row zero is the top.
+    const fw=face.clientWidth||280, fh=175;
+    text(face,12,20,has?'Detector face · Bruker PC':'No detector supplied');
+    if(has) {
+      const maxX=Math.max(1,s.pcx),minX=Math.min(0,s.pcx),maxY=Math.max(1,s.pcy),minY=Math.min(0,s.pcy);
+      const kf=Math.min((fw-60)/(g.W*(maxX-minX)),98/(g.H*(maxY-minY)));
+      const left=30-minX*g.W*kf, top=40-minY*g.H*kf, ww=g.W*kf, hh=g.H*kf;
+      node(face,'rect',{x:left,y:top,width:ww,height:hh,fill:screen,'fill-opacity':.13,stroke:screen});
+      const x=left+s.pcx*ww,y=top+s.pcy*hh;
+      line(face,[x-7,y],[x+7,y],pcColor,2);line(face,[x,y-7],[x,y+7],pcColor,2);
+      text(face,fw/2,fh-20,`${s.detector_cols} × ${s.detector_rows} pixels`,'middle');
+      text(face,fw/2,fh-4,`${fmt(g.W)} × ${fmt(g.H)} mm · row 0 at top`,'middle');
+      face.style.cursor='crosshair';
+      face.onclick=event=>{
+        const rect=face.getBoundingClientRect();
+        model.set('pcx',Math.min(1,Math.max(0,(event.clientX-rect.left-left)/ww)));
+        model.set('pcy',Math.min(1,Math.max(0,(event.clientY-rect.top-top)/hh)));model.save_changes();
+      };
+    }
+    const pw=probe.clientWidth||280;
+    text(probe,12,20,'Probe footprint · sample-plane inset');
+    if(g.footprint) {
+      const [major,minor]=g.footprint, rx=Math.min((pw-48)/2,82), ry=rx*minor/major;
+      node(probe,'ellipse',{cx:pw/2,cy:83,rx,ry,fill:beam,'fill-opacity':.18,stroke:beam,'stroke-width':2});
+      line(probe,[pw/2-rx,83],[pw/2+rx,83],beam,1,'3 3');
+      text(probe,pw/2,143,`${fmt(major)} × ${fmt(minor)} nm`,'middle');
+      text(probe,pw/2,161,'Parallel circular probe · separate scale','middle');
+    } else {
+      text(probe,pw/2,78,s.probe_diameter_nm?'No finite footprint at 90°':'Probe diameter not specified','middle');
+      text(probe,pw/2,99,'Not an interaction-volume model','middle');
+    }
+    const centerLab=g.lab.reduce((sum,p)=>sum+p[2],0)/4;
+    const minHeight=Math.min(...g.corners.map(p=>p[2]));
+    facts.textContent=has?`PC (${s.pcx.toFixed(3)}, ${s.pcy.toFixed(3)}, ${s.pcz.toFixed(3)}) · screen center: ${fmt(centerLab)} mm above impact (lab), ${fmt(g.center[2])} mm above the sample plane (normal). `+
+      (minHeight<0?'Warning: part of the screen lies behind the extended sample plane. ':'')+
+      'Click the detector face to set PCx / PCy.':
+      'Sample normal points out of the material. Probe size is descriptive metadata, not a solver input.';
+  }
+  const names=[...fields.map(f=>f[0]),'crystal_label','has_detector'];
+  for(const name of names) model.on(`change:${name}`,draw);
+  const observer=new ResizeObserver(draw); observer.observe(root); draw();
+  return ()=>{observer.disconnect();for(const name of names) model.off(`change:${name}`,draw);};
+}
+export default {render};