midas-distortion 0.2.0__tar.gz

midas_distortion-0.2.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: midas-distortion
+Version: 0.2.0
+Summary: Canonical MIDAS radial-distortion model: layout tables, v1<->v2 coefficient mapping, and a backend-agnostic (numpy/torch) distortion kernel.
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
+Classifier: Development Status :: 4 - Beta
+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
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: torch>=2.0; extra == "dev"
+
+# midas-distortion
+
+Canonical MIDAS radial-distortion model — the single source of truth for the
+detector distortion layout and the v1↔v2 coefficient mapping, shared by:
+
+- **midas-calibrate-v2** — fits the distortion (v2 canonical names).
+- **midas-peakfit** — applies it to spot geometry (numpy).
+- **midas-transforms** — applies it to spot geometry (torch).
+
+## Model
+
+Multiplicative factor on the projected radius `R` (with `ρ = R / RhoD`,
+`η' = 90° − η`):
+
+```
+D(ρ, η) = 1
+    + iso_R2·ρ² + iso_R4·ρ⁴ + iso_R6·ρ⁶              (isotropic)
+    + a1·ρ⁴·cos( η' + phi1)                           (1-fold; ρ⁴ is a v1 quirk)
+    + a2·ρ²·cos(2η' + phi2)
+    + a3·ρ³·cos(3η' + phi3)
+    + a4·ρ⁴·cos(4η' + phi4)
+    + a5·ρ⁵·cos(5η' + phi5)
+    + a6·ρ⁶·cos(6η' + phi6)
+```
+
+The legacy v1 ordering (`p0..p14`, phases scattered) is `v1_term_layout()`;
+v1↔v2 reindexing is exact (`v1_to_v2_coeffs` / `v2_to_v1_coeffs`).
+
+## Backend-agnostic kernel
+
+`distortion_factor(R_norm, eta_deg, p_coeffs, terms=...)` dispatches `cos` /
+`ones_like` on the input's own array library, so numpy and torch consumers
+evaluate bit-for-bit the same model (up to floating-point reassociation).
+
+```python
+import numpy as np
+from midas_distortion import distortion_factor, v1_term_layout, v1_to_v2_coeffs
+
+p_v1 = np.zeros(15)          # legacy paramstest p0..p14
+D = distortion_factor(R/RhoD, eta_deg, p_v1, terms=v1_term_layout())
+# …or convert once and use the v2 layout (default):
+D = distortion_factor(R/RhoD, eta_deg, v1_to_v2_coeffs(p_v1))
+```

midas_distortion-0.2.0/README.md

@@ -0,0 +1,43 @@
+# midas-distortion
+
+Canonical MIDAS radial-distortion model — the single source of truth for the
+detector distortion layout and the v1↔v2 coefficient mapping, shared by:
+
+- **midas-calibrate-v2** — fits the distortion (v2 canonical names).
+- **midas-peakfit** — applies it to spot geometry (numpy).
+- **midas-transforms** — applies it to spot geometry (torch).
+
+## Model
+
+Multiplicative factor on the projected radius `R` (with `ρ = R / RhoD`,
+`η' = 90° − η`):
+
+```
+D(ρ, η) = 1
+    + iso_R2·ρ² + iso_R4·ρ⁴ + iso_R6·ρ⁶              (isotropic)
+    + a1·ρ⁴·cos( η' + phi1)                           (1-fold; ρ⁴ is a v1 quirk)
+    + a2·ρ²·cos(2η' + phi2)
+    + a3·ρ³·cos(3η' + phi3)
+    + a4·ρ⁴·cos(4η' + phi4)
+    + a5·ρ⁵·cos(5η' + phi5)
+    + a6·ρ⁶·cos(6η' + phi6)
+```
+
+The legacy v1 ordering (`p0..p14`, phases scattered) is `v1_term_layout()`;
+v1↔v2 reindexing is exact (`v1_to_v2_coeffs` / `v2_to_v1_coeffs`).
+
+## Backend-agnostic kernel
+
+`distortion_factor(R_norm, eta_deg, p_coeffs, terms=...)` dispatches `cos` /
+`ones_like` on the input's own array library, so numpy and torch consumers
+evaluate bit-for-bit the same model (up to floating-point reassociation).
+
+```python
+import numpy as np
+from midas_distortion import distortion_factor, v1_term_layout, v1_to_v2_coeffs
+
+p_v1 = np.zeros(15)          # legacy paramstest p0..p14
+D = distortion_factor(R/RhoD, eta_deg, p_v1, terms=v1_term_layout())
+# …or convert once and use the v2 layout (default):
+D = distortion_factor(R/RhoD, eta_deg, v1_to_v2_coeffs(p_v1))
+```

midas_distortion-0.2.0/midas_distortion/__init__.py

@@ -0,0 +1,57 @@
+"""midas_distortion — canonical MIDAS radial-distortion model (single source).
+
+Shared by midas_calibrate_v2 (calibration), midas_peakfit (numpy spot geometry)
+and midas_transforms (torch spot geometry) so all three evaluate one definition
+of the distortion layout + the v1↔v2 coefficient mapping.
+"""
+from .core import (
+    HarmonicTerm,
+    P_COEF_NAMES,
+    PHASE_NAMES,
+    ISO_NAMES,
+    AMP_NAMES,
+    v1_term_layout,
+    v2_term_layout,
+    extended_term_layout,
+    extended_p_coef_names,
+    V1_TO_V2_DISTORTION,
+    V2_TO_V1_DISTORTION,
+    V2_TO_V1_PNAME,
+    v1_to_v2_coeffs,
+    v2_to_v1_coeffs,
+    v2_coeffs_from_named,
+    distortion_factor,
+    apply_distortion,
+)
+from .rhod import (
+    detector_max_corner_dist_um,
+    check_rho_d_um,
+    resolve_rho_d_um,
+    resolve_rho_d_um_warn,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "HarmonicTerm",
+    "P_COEF_NAMES",
+    "PHASE_NAMES",
+    "ISO_NAMES",
+    "AMP_NAMES",
+    "v1_term_layout",
+    "v2_term_layout",
+    "extended_term_layout",
+    "extended_p_coef_names",
+    "V1_TO_V2_DISTORTION",
+    "V2_TO_V1_DISTORTION",
+    "V2_TO_V1_PNAME",
+    "v1_to_v2_coeffs",
+    "v2_to_v1_coeffs",
+    "v2_coeffs_from_named",
+    "distortion_factor",
+    "apply_distortion",
+    "detector_max_corner_dist_um",
+    "check_rho_d_um",
+    "resolve_rho_d_um",
+    "resolve_rho_d_um_warn",
+]

midas_distortion-0.2.0/midas_distortion/core.py

@@ -0,0 +1,235 @@
+"""Canonical MIDAS radial-distortion model — the single source of truth.
+
+This leaf holds the distortion *layout* (which coefficient drives which η-fold
+at which radial power) and the v1↔v2 coefficient mapping. Bugs in a distortion
+model live in the layout/mapping — a wrong index, swapped phase, wrong fold —
+not in the trivial arithmetic. Centralising the layout here lets
+``midas_calibrate_v2`` (calibration), ``midas_peakfit`` (numpy) and
+``midas_transforms`` (torch) all evaluate the *same* model from one definition.
+
+Model (multiplicative factor on the projected radius)::
+
+    D(ρ, η) = 1
+        + iso_R2·ρ² + iso_R4·ρ⁴ + iso_R6·ρ⁶                 (isotropic)
+        + a1·ρ⁴·cos( η' + phi1)                              (1-fold; ρ⁴ is a
+        + a2·ρ²·cos(2η' + phi2)                                v1-physics quirk)
+        + a3·ρ³·cos(3η' + phi3)
+        + a4·ρ⁴·cos(4η' + phi4)
+        + a5·ρ⁵·cos(5η' + phi5)
+        + a6·ρ⁶·cos(6η' + phi6)
+
+with η' = 90° − η (degrees in, converted internally). ``distortion_factor`` is
+backend-agnostic: pass numpy arrays or torch tensors and it dispatches cos /
+ones_like / zeros_like on the input's own library, so the math is identical
+across consumers (down to floating-point reassociation).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List
+
+_DEG2RAD = 0.017453292519943295
+
+
+# ───────────────────────────────────────────────────────────── canonical names
+# 15 names, in the SAME order as the v2 p_coeffs vector slots.
+P_COEF_NAMES: List[str] = [
+    "iso_R2", "iso_R4", "iso_R6",   # 0,1,2  isotropic radial (no η)
+    "a1", "phi1",                   # 3,4    1-fold (ρ⁴)
+    "a2", "phi2",                   # 5,6    2-fold (ρ²)
+    "a3", "phi3",                   # 7,8    3-fold (ρ³)
+    "a4", "phi4",                   # 9,10   4-fold (ρ⁴)
+    "a5", "phi5",                   # 11,12  5-fold (ρ⁵)
+    "a6", "phi6",                   # 13,14  6-fold (ρ⁶)
+]
+PHASE_NAMES = ("phi1", "phi2", "phi3", "phi4", "phi5", "phi6")
+ISO_NAMES = ("iso_R2", "iso_R4", "iso_R6")
+AMP_NAMES = ("a1", "a2", "a3", "a4", "a5", "a6")
+_NAME_TO_V2IDX = {nm: i for i, nm in enumerate(P_COEF_NAMES)}
+
+
+# ─────────────────────────────────────────────────────────────── harmonic term
+@dataclass
+class HarmonicTerm:
+    """One additive contribution to the multiplicative distortion D.
+
+    Isotropic radial term ``c·ρⁿ`` → ``fold=0, phase_idx=-1``; polar harmonic
+    ``c·ρⁿ·cos(k η' + φ)`` → ``fold=k``.
+    """
+
+    coef_idx: int      # index into p_coeffs for the amplitude
+    phase_idx: int     # index into p_coeffs for the phase (-1 if isotropic)
+    radial_power: int  # n in ρⁿ
+    fold: int          # k in cos(k η' + φ); 0 = isotropic
+
+
+def v2_term_layout() -> List[HarmonicTerm]:
+    """v2 canonical ordering — fold-monotonic, isotropic terms grouped first."""
+    return [
+        HarmonicTerm(0, -1, 2, 0),   # iso_R2
+        HarmonicTerm(1, -1, 4, 0),   # iso_R4
+        HarmonicTerm(2, -1, 6, 0),   # iso_R6
+        HarmonicTerm(3, 4, 4, 1),    # a1, phi1  (1-fold uses ρ⁴)
+        HarmonicTerm(5, 6, 2, 2),    # a2, phi2
+        HarmonicTerm(7, 8, 3, 3),    # a3, phi3
+        HarmonicTerm(9, 10, 4, 4),   # a4, phi4
+        HarmonicTerm(11, 12, 5, 5),  # a5, phi5
+        HarmonicTerm(13, 14, 6, 6),  # a6, phi6
+    ]
+
+
+def v1_term_layout() -> List[HarmonicTerm]:
+    """Legacy v1 ordering on the v1 p₀..p₁₄ vector (kept for paramstest parity).
+
+    p₀ amp ρ²fold2(φ=p₆) | p₁ amp ρ⁴fold4(φ=p₃) | p₂ iso ρ² | p₄ iso ρ⁶ |
+    p₅ iso ρ⁴ | p₇ amp ρ⁴fold1(φ=p₈) | p₉ amp ρ³fold3(φ=p₁₀) |
+    p₁₁ amp ρ⁵fold5(φ=p₁₂) | p₁₃ amp ρ⁶fold6(φ=p₁₄).
+    """
+    return [
+        HarmonicTerm(0, 6, 2, 2),
+        HarmonicTerm(1, 3, 4, 4),
+        HarmonicTerm(2, -1, 2, 0),
+        HarmonicTerm(4, -1, 6, 0),
+        HarmonicTerm(5, -1, 4, 0),
+        HarmonicTerm(7, 8, 4, 1),
+        HarmonicTerm(9, 10, 3, 3),
+        HarmonicTerm(11, 12, 5, 5),
+        HarmonicTerm(13, 14, 6, 6),
+    ]
+
+
+def extended_term_layout(max_fold: int = 8) -> List[HarmonicTerm]:
+    """v2 base layout plus (a_k, phi_k) for k = 7..max_fold, each at radial ρᵏ.
+
+    Caller must size the p_coeffs vector to ``15 + 2·(max_fold − 6)``.
+    """
+    if max_fold <= 6:
+        return v2_term_layout()
+    base = v2_term_layout()
+    nxt = 15
+    for k in range(7, max_fold + 1):
+        base.append(HarmonicTerm(nxt, nxt + 1, k, k))
+        nxt += 2
+    return base
+
+
+def extended_p_coef_names(max_fold: int = 8) -> List[str]:
+    if max_fold <= 6:
+        return list(P_COEF_NAMES)
+    out = list(P_COEF_NAMES)
+    for k in range(7, max_fold + 1):
+        out.extend([f"a{k}", f"phi{k}"])
+    return out
+
+
+# ───────────────────────────────────────────────────────────────── v1 ↔ v2 map
+# v1 p-index → v2 canonical name.
+V1_TO_V2_DISTORTION: Dict[int, str] = {
+    0: "a2", 1: "a4", 2: "iso_R2", 3: "phi4", 4: "iso_R6", 5: "iso_R4",
+    6: "phi2", 7: "a1", 8: "phi1", 9: "a3", 10: "phi3", 11: "a5",
+    12: "phi5", 13: "a6", 14: "phi6",
+}
+# v2 canonical name → v1 p-index.
+V2_TO_V1_DISTORTION: Dict[str, int] = {v: k for k, v in V1_TO_V2_DISTORTION.items()}
+# v2 canonical name → v1 p-name ("p0".."p14"), for paramstest field setting.
+V2_TO_V1_PNAME: Dict[str, str] = {v: f"p{k}" for k, v in V1_TO_V2_DISTORTION.items()}
+
+
+# Fixed gather permutations (pure indexing → differentiable + device-portable,
+# unlike an in-place assignment loop). ``_PERM_V1_TO_V2[slot]`` is the v1 index
+# feeding v2 slot ``slot``; ``_PERM_V2_TO_V1[v1_idx]`` is the v2 slot feeding it.
+_PERM_V1_TO_V2 = [V2_TO_V1_DISTORTION[name] for name in P_COEF_NAMES]
+_PERM_V2_TO_V1 = [_NAME_TO_V2IDX[V1_TO_V2_DISTORTION[i]] for i in range(15)]
+
+
+def v1_to_v2_coeffs(p_v1):
+    """Reindex a v1 p₀..p₁₄ coefficient vector into v2 canonical order.
+
+    A pure gather (``p_v1[perm]``) — works for numpy arrays and torch tensors,
+    returns the same type, and stays differentiable for autograd.
+    """
+    return p_v1[_PERM_V1_TO_V2]
+
+
+def v2_to_v1_coeffs(p_v2):
+    """Reindex a v2 canonical coefficient vector into v1 p₀..p₁₄ order."""
+    return p_v2[_PERM_V2_TO_V1]
+
+
+def v2_coeffs_from_named(named, *, default: float = 0.0):
+    """Build the canonical 15-vector (v2 :data:`P_COEF_NAMES` order) from a
+    mapping that uses **v2 names** (``iso_R2``, ``a1``, ``phi1``, …) — with
+    legacy ``p0``..``p14`` accepted only as a fallback for old inputs.
+
+    v2 names win over any same-slot ``pN`` (so a v2-named source is honoured
+    exactly; a pure-v1 source still works). Returns a numpy float64[15].
+    Missing entries default to ``default`` (0.0). ``None`` values are skipped.
+    """
+    import numpy as np
+    out = np.full(15, float(default), dtype=np.float64)
+    # legacy p-names first, so v2 names override on any collision
+    for k, v in named.items():
+        if v is None:
+            continue
+        if isinstance(k, str) and len(k) > 1 and k[0] == "p" and k[1:].isdigit():
+            i = int(k[1:])
+            if 0 <= i < 15:
+                out[_NAME_TO_V2IDX[V1_TO_V2_DISTORTION[i]]] = float(v)
+    for k, v in named.items():
+        if v is None:
+            continue
+        if k in _NAME_TO_V2IDX:
+            out[_NAME_TO_V2IDX[k]] = float(v)
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────── evaluation
+def _is_torch(x) -> bool:
+    return type(x).__module__.split(".")[0] == "torch"
+
+
+def _backend(x):
+    """Return (cos, ones_like, zeros_like) bound to x's array library."""
+    if _is_torch(x):
+        import torch
+        return torch.cos, torch.ones_like, torch.zeros_like
+    import numpy as np
+    return np.cos, np.ones_like, np.zeros_like
+
+
+def _zeros_like(x):
+    return _backend(x)[2](x)
+
+
+def distortion_factor(R_norm, eta_deg, p_coeffs, *, terms: Iterable[HarmonicTerm] = None):
+    """Multiplicative distortion factor D(ρ, η).
+
+    Parameters
+    ----------
+    R_norm : ρ = R / RhoD, numpy array or torch tensor (broadcastable).
+    eta_deg : azimuthal angle in degrees (atan2(-y, z) convention).
+    p_coeffs : coefficient vector; indexing is defined by ``terms``
+        (v2 order by default, v1 order if ``terms=v1_term_layout()``).
+    terms : layout; defaults to :func:`v2_term_layout`.
+    """
+    if terms is None:
+        terms = v2_term_layout()
+    cos, ones_like, _ = _backend(R_norm)
+    eta_T = (90.0 - eta_deg) * _DEG2RAD
+    D = ones_like(R_norm)
+    for t in terms:
+        amp = p_coeffs[t.coef_idx]
+        rad = R_norm ** t.radial_power
+        if t.fold == 0:
+            D = D + amp * rad
+        else:
+            phase = p_coeffs[t.phase_idx] * _DEG2RAD
+            D = D + amp * rad * cos(t.fold * eta_T + phase)
+    return D
+
+
+def apply_distortion(R, eta_deg, p_coeffs, rho_d, *, terms: Iterable[HarmonicTerm] = None):
+    """Multiplicatively apply the distortion to a projected radius ``R`` (same
+    units as ``rho_d``)."""
+    R_norm = R / rho_d
+    return R * distortion_factor(R_norm, eta_deg, p_coeffs, terms=terms)

midas_distortion-0.2.0/midas_distortion/rhod.py

@@ -0,0 +1,175 @@
+"""RhoD unit self-consistency — the single source of truth for all MIDAS packages.
+
+``RhoD`` (the radial-distortion normalisation radius) appears only inside
+``ρ = R / RhoD`` (see :func:`midas_distortion.core.apply_distortion`). It MUST
+therefore be in the **same units as R**, i.e. **micrometres**. Different MIDAS
+workflows have historically stored it in µm *or* in pixels, and a wrong-unit
+value silently corrupts the distortion stage:
+
+* RhoD too small (pixels passed as µm) → ρ ≈ pixel-pitch× too large → the
+  distortion polynomial explodes → pixels scatter into the wrong radial bins →
+  powder rings wash out (the failure mode that cost real debugging time).
+* RhoD too large → ρ ≈ 0 → distortion silently nulled.
+
+These helpers remove the ambiguity once and for all. ``resolve_rho_d_um``
+auto-detects the units and returns micrometres; ``check_rho_d_um`` validates a
+value that is *supposed* to already be in µm. Both take detector context
+(pixel count, beam centre, pixel pitch) because the sane scale for RhoD is the
+beam-centre-to-farthest-corner distance in µm.
+
+This module is intentionally dependency-free (pure ``math``) so every package
+— ``midas_calibrate_v2``, ``midas_integrate_v2``, ``midas_integrate`` — can
+call exactly the same logic.
+"""
+from __future__ import annotations
+
+import math
+import warnings
+from typing import Optional
+
+
+def detector_max_corner_dist_um(
+    NrPixelsY: int, NrPixelsZ: int,
+    BC_y: float, BC_z: float,
+    pxY: float, pxZ: Optional[float] = None,
+) -> float:
+    """Max distance from the beam centre to any detector corner, in µm —
+    the natural upper-bound scale for ``RhoD``.
+    """
+    if pxZ is None:
+        pxZ = pxY
+    if NrPixelsY <= 0 or NrPixelsZ <= 0:
+        raise ValueError(
+            f"NrPixelsY/NrPixelsZ must be positive; got {NrPixelsY}x{NrPixelsZ}"
+        )
+    corners_px = [
+        (0.0, 0.0),
+        (NrPixelsY - 1.0, 0.0),
+        (0.0, NrPixelsZ - 1.0),
+        (NrPixelsY - 1.0, NrPixelsZ - 1.0),
+    ]
+    return max(
+        math.sqrt(((y - BC_y) * pxY) ** 2 + ((z - BC_z) * pxZ) ** 2)
+        for (y, z) in corners_px
+    )
+
+
+def check_rho_d_um(
+    RhoD_um: float,
+    NrPixelsY: int, NrPixelsZ: int,
+    BC_y: float, BC_z: float,
+    pxY: float, pxZ: Optional[float] = None,
+    *,
+    low_factor: float = 0.5,
+    high_factor: float = 5.0,
+    strict: bool = True,
+) -> Optional[str]:
+    """Raise (or return a warning) if ``RhoD_um`` looks like a unit mistake.
+
+    The healthy range is roughly the detector-corner distance from the beam
+    centre (in µm). Outside ``[low_factor·dmax, high_factor·dmax]`` we treat
+    the value as a likely unit mix-up — most often RhoD passed in **pixels**,
+    which is ``dmax / px`` ≈ 1/px-pitch of the expected µm magnitude.
+
+    Returns ``None`` if healthy. With ``strict=False`` and an out-of-range
+    value, returns the diagnostic string; with ``strict=True`` raises
+    ``ValueError``.
+    """
+    if RhoD_um <= 0:
+        msg = f"RhoD must be positive; got {RhoD_um}"
+        if strict:
+            raise ValueError(msg)
+        return msg
+    dmax = detector_max_corner_dist_um(NrPixelsY, NrPixelsZ, BC_y, BC_z, pxY, pxZ)
+    lo, hi = low_factor * dmax, high_factor * dmax
+    if RhoD_um < lo or RhoD_um > hi:
+        pxY_eff = float(pxY)
+        as_px_hint = ""
+        if RhoD_um < lo and pxY_eff > 0 and 0.3 * dmax < RhoD_um * pxY_eff < 3 * dmax:
+            as_px_hint = (f"  HINT: RhoD * px = {RhoD_um * pxY_eff:.1f} µm "
+                          f"looks reasonable — did you pass RhoD in pixels?")
+        msg = (
+            f"RhoD = {RhoD_um:.4g} µm is outside the sane range "
+            f"[{lo:.1f}, {hi:.1f}] µm for a {NrPixelsY}×{NrPixelsZ} detector at "
+            f"px=({pxY},{pxZ if pxZ is not None else pxY}), BC=({BC_y},{BC_z}) "
+            f"(max corner distance = {dmax:.1f} µm).{as_px_hint}"
+        )
+        if strict:
+            raise ValueError(msg)
+        return msg
+    return None
+
+
+def resolve_rho_d_um(
+    rho_d,
+    NrPixelsY: int, NrPixelsZ: int,
+    BC_y: float, BC_z: float,
+    pxY: float, pxZ: Optional[float] = None,
+    *,
+    low_factor: float = 0.5,
+    high_factor: float = 5.0,
+) -> "tuple[float, str]":
+    """Resolve a ``RhoD`` of ambiguous units to micrometres.
+
+    Tries ``{rho_d, rho_d·px, rho_d/px}`` and returns the first that falls in
+    the sane window ``[low_factor·dmax, high_factor·dmax]`` (preferring the
+    as-is interpretation), where ``dmax`` is the beam-centre-to-farthest-corner
+    distance in µm. When no candidate is sane (or ``rho_d`` is missing /
+    non-positive) it falls back to ``dmax`` — the natural default RhoD.
+
+    Returns ``(rho_d_um, how)`` where ``how`` documents the chosen branch.
+    """
+    dmax = detector_max_corner_dist_um(NrPixelsY, NrPixelsZ, BC_y, BC_z, pxY, pxZ)
+    lo, hi = low_factor * dmax, high_factor * dmax
+    px = float(pxY) if (pxZ is None or pxZ <= 0) else 0.5 * (float(pxY) + float(pxZ))
+    try:
+        val = float(rho_d)
+    except (TypeError, ValueError):
+        val = 0.0
+    if val > 0 and px > 0:
+        for how, cand in (("as-is (µm)", val),
+                          ("×px (was pixels)", val * px),
+                          ("÷px", val / px)):
+            if lo <= cand <= hi:
+                return cand, how
+    return dmax, "default = BC-to-farthest-edge"
+
+
+def resolve_rho_d_um_warn(
+    rho_d,
+    NrPixelsY: int, NrPixelsZ: int,
+    BC_y: float, BC_z: float,
+    pxY: float, pxZ: Optional[float] = None,
+    *,
+    where: str = "",
+    rel_tol: float = 1e-3,
+    **kwargs,
+) -> float:
+    """Like :func:`resolve_rho_d_um` but emit a ``RuntimeWarning`` when the
+    value had to be corrected (units were not already µm), and return just the
+    resolved µm value. Intended for ``validate()``/build hooks so a wrong-unit
+    RhoD is fixed *and* surfaced rather than silently mangling the distortion.
+    """
+    resolved, how = resolve_rho_d_um(
+        rho_d, NrPixelsY, NrPixelsZ, BC_y, BC_z, pxY, pxZ, **kwargs)
+    try:
+        orig = float(rho_d)
+    except (TypeError, ValueError):
+        orig = 0.0
+    if orig <= 0 or abs(resolved - orig) > rel_tol * max(resolved, 1.0):
+        loc = f" in {where}" if where else ""
+        warnings.warn(
+            f"RhoD{loc} resolved to {resolved:.1f} µm ({how}); supplied value "
+            f"was {orig:.4g}. RhoD must be in micrometres (ρ = R_µm / RhoD); a "
+            f"pixel-valued RhoD silently corrupts the distortion. Auto-corrected.",
+            RuntimeWarning, stacklevel=3,
+        )
+    return resolved
+
+
+__all__ = [
+    "detector_max_corner_dist_um",
+    "check_rho_d_um",
+    "resolve_rho_d_um",
+    "resolve_rho_d_um_warn",
+]

midas_distortion-0.2.0/midas_distortion.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: midas-distortion
+Version: 0.2.0
+Summary: Canonical MIDAS radial-distortion model: layout tables, v1<->v2 coefficient mapping, and a backend-agnostic (numpy/torch) distortion kernel.
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
+Classifier: Development Status :: 4 - Beta
+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
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: torch>=2.0; extra == "dev"
+
+# midas-distortion
+
+Canonical MIDAS radial-distortion model — the single source of truth for the
+detector distortion layout and the v1↔v2 coefficient mapping, shared by:
+
+- **midas-calibrate-v2** — fits the distortion (v2 canonical names).
+- **midas-peakfit** — applies it to spot geometry (numpy).
+- **midas-transforms** — applies it to spot geometry (torch).
+
+## Model
+
+Multiplicative factor on the projected radius `R` (with `ρ = R / RhoD`,
+`η' = 90° − η`):
+
+```
+D(ρ, η) = 1
+    + iso_R2·ρ² + iso_R4·ρ⁴ + iso_R6·ρ⁶              (isotropic)
+    + a1·ρ⁴·cos( η' + phi1)                           (1-fold; ρ⁴ is a v1 quirk)
+    + a2·ρ²·cos(2η' + phi2)
+    + a3·ρ³·cos(3η' + phi3)
+    + a4·ρ⁴·cos(4η' + phi4)
+    + a5·ρ⁵·cos(5η' + phi5)
+    + a6·ρ⁶·cos(6η' + phi6)
+```
+
+The legacy v1 ordering (`p0..p14`, phases scattered) is `v1_term_layout()`;
+v1↔v2 reindexing is exact (`v1_to_v2_coeffs` / `v2_to_v1_coeffs`).
+
+## Backend-agnostic kernel
+
+`distortion_factor(R_norm, eta_deg, p_coeffs, terms=...)` dispatches `cos` /
+`ones_like` on the input's own array library, so numpy and torch consumers
+evaluate bit-for-bit the same model (up to floating-point reassociation).
+
+```python
+import numpy as np
+from midas_distortion import distortion_factor, v1_term_layout, v1_to_v2_coeffs
+
+p_v1 = np.zeros(15)          # legacy paramstest p0..p14
+D = distortion_factor(R/RhoD, eta_deg, p_v1, terms=v1_term_layout())
+# …or convert once and use the v2 layout (default):
+D = distortion_factor(R/RhoD, eta_deg, v1_to_v2_coeffs(p_v1))
+```

midas_distortion-0.2.0/midas_distortion.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+midas_distortion/__init__.py
+midas_distortion/core.py
+midas_distortion/rhod.py
+midas_distortion.egg-info/PKG-INFO
+midas_distortion.egg-info/SOURCES.txt
+midas_distortion.egg-info/dependency_links.txt
+midas_distortion.egg-info/requires.txt
+midas_distortion.egg-info/top_level.txt
+tests/test_core.py
+tests/test_rhod.py

midas_distortion-0.2.0/midas_distortion.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

midas_distortion-0.2.0/midas_distortion.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.22
+
+[dev]
+pytest>=7
+torch>=2.0
+
+[torch]
+torch>=2.0

midas_distortion-0.2.0/midas_distortion.egg-info/top_level.txt

@@ -0,0 +1 @@
+midas_distortion

midas_distortion-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "midas-distortion"
+version = "0.2.0"
+description = "Canonical MIDAS radial-distortion model: layout tables, v1<->v2 coefficient mapping, and a backend-agnostic (numpy/torch) distortion kernel."
+readme = "README.md"
+license = { text = "BSD-3-Clause" }
+authors = [
+    {name = "Hemant Sharma", email = "hsharma@anl.gov"},
+]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.22",
+]
+
+[project.optional-dependencies]
+torch = [
+    "torch>=2.0",
+]
+dev = [
+    "pytest>=7",
+    "torch>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/marinerhemant/MIDAS"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["midas_distortion*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"

midas_distortion-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

midas_distortion-0.2.0/tests/test_core.py

@@ -0,0 +1,156 @@
+"""midas_distortion parity + cross-backend gates.
+
+The distortion model is correct iff its layout/mapping is correct; the
+arithmetic is trivial. So we pin:
+
+  HARD GATE — every additive term is BIT-IDENTICAL across the legacy v1 inline
+    polynomial, the v1-layout kernel, and the v2-shim kernel (Δ=0). A mapping
+    bug (wrong index/fold/phase/radial-power) surfaces here, not behind rounding.
+  ASSEMBLED — the summed factor agrees to ≤ 8 ULP (pure IEEE-754 reassociation).
+  CROSS-BACKEND — numpy and torch evaluate the same factor to ≤ 8 ULP.
+"""
+import numpy as np
+import pytest
+
+from midas_distortion import (
+    distortion_factor, v1_term_layout, v2_term_layout,
+    v1_to_v2_coeffs, v2_to_v1_coeffs, v2_coeffs_from_named,
+    P_COEF_NAMES, V1_TO_V2_DISTORTION, V2_TO_V1_DISTORTION,
+)
+
+_DEG2RAD = 0.017453292519943295
+_EPS = float(np.finfo(np.float64).eps)
+_ULP_TOL = 8 * _EPS
+
+
+def _grid_np():
+    R = np.linspace(0.0, 1.3, 41)
+    eta = np.linspace(-180.0, 180.0, 73)
+    return np.meshgrid(R, eta, indexing="ij")
+
+
+def _inline_terms(Rg, Eg, p):
+    """The 9 additive terms of the legacy v1 polynomial, keyed by p-index."""
+    eT = (90.0 - Eg) * _DEG2RAD
+    return {
+        0:  p[0] * Rg**2 * np.cos(2 * eT + _DEG2RAD * p[6]),
+        1:  p[1] * Rg**4 * np.cos(4 * eT + _DEG2RAD * p[3]),
+        2:  p[2] * Rg**2,
+        4:  p[4] * Rg**6,
+        5:  p[5] * Rg**4,
+        7:  p[7] * Rg**4 * np.cos(eT + _DEG2RAD * p[8]),
+        9:  p[9] * Rg**3 * np.cos(3 * eT + _DEG2RAD * p[10]),
+        11: p[11] * Rg**5 * np.cos(5 * eT + _DEG2RAD * p[12]),
+        13: p[13] * Rg**6 * np.cos(6 * eT + _DEG2RAD * p[14]),
+    }
+
+
+def _random_p(rng):
+    p = rng.uniform(-5e-3, 5e-3, size=15)
+    for ph in (3, 6, 8, 10, 12, 14):
+        p[ph] = rng.uniform(-180.0, 180.0)
+    return p
+
+
+def test_v1_v2_maps_are_inverses():
+    assert {v: k for k, v in V1_TO_V2_DISTORTION.items()} == V2_TO_V1_DISTORTION
+    assert set(V1_TO_V2_DISTORTION.values()) == set(P_COEF_NAMES)
+    assert sorted(V1_TO_V2_DISTORTION) == list(range(15))
+
+
+def test_coeff_reindex_roundtrip_and_mapping():
+    """v1→v2→v1 is identity, and each v2 slot pulls the right v1 index."""
+    p = np.arange(15.0)
+    v2 = v1_to_v2_coeffs(p)
+    assert np.array_equal(v2_to_v1_coeffs(v2), p)
+    for v1_idx, name in V1_TO_V2_DISTORTION.items():
+        assert v2[P_COEF_NAMES.index(name)] == p[v1_idx]
+
+
+def test_v2_coeffs_from_named():
+    """v2 names populate the canonical vector; legacy p0..p14 is a fallback
+    equal to v1_to_v2_coeffs; v2 names win on collision."""
+    # pure v2 names
+    d = {"iso_R2": -1.1e-3, "a2": 4.6e-4, "phi2": 33.0, "a4": -5.2e-4, "phi4": -6.87}
+    v = v2_coeffs_from_named(d)
+    for nm, val in d.items():
+        assert v[P_COEF_NAMES.index(nm)] == val
+    # legacy p path == v1_to_v2_coeffs
+    pv = np.arange(15.0)
+    assert np.array_equal(v2_coeffs_from_named({f"p{i}": pv[i] for i in range(15)}),
+                          v1_to_v2_coeffs(pv))
+    # v2 name wins over the same-slot legacy p
+    mixed = {"p2": 99.0, "iso_R2": -1.1e-3}   # p2 and iso_R2 are the same slot
+    assert v2_coeffs_from_named(mixed)[P_COEF_NAMES.index("iso_R2")] == -1.1e-3
+    # None values skipped
+    assert np.array_equal(v2_coeffs_from_named({"a2": None}), np.zeros(15))
+
+
+def test_coeff_reindex_is_differentiable():
+    """The v1→v2 gather must preserve autograd (transforms needs grads)."""
+    torch = pytest.importorskip("torch")
+    t = torch.arange(15.0, dtype=torch.float64, requires_grad=True)
+    v1_to_v2_coeffs(t).sum().backward()
+    assert t.grad is not None and torch.all(t.grad == 1.0)
+
+
+def test_terms_bit_identical():
+    """HARD GATE: per-term Δ=0 across inline / v1-kernel / v2-shim."""
+    rng = np.random.default_rng(0)
+    Rg, Eg = _grid_np()
+    v1L, v2L = v1_term_layout(), v2_term_layout()
+    name2v2 = {nm: i for i, nm in enumerate(P_COEF_NAMES)}
+    v2_key = {k: name2v2[v] for k, v in V1_TO_V2_DISTORTION.items()}  # v1 amp idx → v2 amp idx
+    eT = (90.0 - Eg) * _DEG2RAD
+    for _ in range(300):
+        p = _random_p(rng)
+        p2 = v1_to_v2_coeffs(p)
+        inl = _inline_terms(Rg, Eg, p)
+        # kernel per-term, v1 layout
+        kv1 = {}
+        for t in v1L:
+            rad = Rg ** t.radial_power
+            kv1[t.coef_idx] = (p[t.coef_idx] * rad if t.fold == 0
+                               else p[t.coef_idx] * rad * np.cos(t.fold * eT + p[t.phase_idx] * _DEG2RAD))
+        # kernel per-term, v2 layout on shimmed coeffs
+        kv2 = {}
+        for t in v2L:
+            rad = Rg ** t.radial_power
+            kv2[t.coef_idx] = (p2[t.coef_idx] * rad if t.fold == 0
+                               else p2[t.coef_idx] * rad * np.cos(t.fold * eT + p2[t.phase_idx] * _DEG2RAD))
+        for k, term in inl.items():
+            assert np.array_equal(term, kv1[k]), f"v1 kernel term p{k} != inline"
+            assert np.array_equal(term, kv2[v2_key[k]]), f"v2 shim term p{k} != inline"
+
+
+def test_assembled_within_ulp():
+    rng = np.random.default_rng(1)
+    Rg, Eg = _grid_np()
+    for _ in range(300):
+        p = _random_p(rng)
+        p2 = v1_to_v2_coeffs(p)
+        D_inline = sum(_inline_terms(Rg, Eg, p).values()) + 1.0
+        D_v1 = distortion_factor(Rg, Eg, p, terms=v1_term_layout())
+        D_v2 = distortion_factor(Rg, Eg, p2, terms=v2_term_layout())
+        assert np.abs(D_inline - D_v1).max() <= _ULP_TOL
+        assert np.abs(D_v1 - D_v2).max() <= _ULP_TOL
+
+
+def test_zero_is_unity():
+    Rg, Eg = _grid_np()
+    z = np.zeros(15)
+    for layout in (v1_term_layout(), v2_term_layout()):
+        assert np.array_equal(distortion_factor(Rg, Eg, z, terms=layout), np.ones_like(Rg))
+
+
+def test_cross_backend_numpy_torch():
+    """numpy and torch evaluate the same factor to ≤ 8 ULP."""
+    torch = pytest.importorskip("torch")
+    rng = np.random.default_rng(2)
+    Rg, Eg = _grid_np()
+    Rt, Et = torch.from_numpy(Rg), torch.from_numpy(Eg)
+    for _ in range(50):
+        p = _random_p(rng)
+        D_np = distortion_factor(Rg, Eg, p, terms=v1_term_layout())
+        D_t = distortion_factor(Rt, Et, torch.from_numpy(p), terms=v1_term_layout())
+        assert np.abs(D_np - D_t.numpy()).max() <= _ULP_TOL

midas_distortion-0.2.0/tests/test_rhod.py

@@ -0,0 +1,60 @@
+"""Tests for the shared RhoD unit self-consistency guard."""
+import warnings
+
+import pytest
+
+from midas_distortion.rhod import (
+    detector_max_corner_dist_um,
+    check_rho_d_um,
+    resolve_rho_d_um,
+    resolve_rho_d_um_warn,
+)
+
+# A leighanne-like 2880^2 Varex: px=150 µm, BC near centre.
+GEO = dict(NrPixelsY=2880, NrPixelsZ=2880, BC_y=1431.7, BC_z=1472.5, pxY=150.0)
+DMAX = detector_max_corner_dist_um(**GEO)          # ~310000 µm
+CORNER_PX = DMAX / 150.0                            # ~2065 px
+
+
+def test_dmax_is_um_scale():
+    assert 250_000 < DMAX < 360_000   # micrometres, not pixels
+
+
+def test_resolve_passes_through_correct_um():
+    val, how = resolve_rho_d_um(DMAX, **GEO)
+    assert abs(val - DMAX) < 1.0
+    assert how.startswith("as-is")
+
+
+def test_resolve_corrects_pixels_to_um():
+    # RhoD given in pixels (~2065) must be detected and scaled by px.
+    val, how = resolve_rho_d_um(CORNER_PX, **GEO)
+    assert abs(val - DMAX) < 1.0
+    assert "pixels" in how
+
+
+def test_resolve_defaults_when_missing():
+    val, how = resolve_rho_d_um(0.0, **GEO)
+    assert abs(val - DMAX) < 1.0
+    assert "default" in how
+
+
+def test_check_raises_on_pixel_value():
+    with pytest.raises(ValueError):
+        check_rho_d_um(CORNER_PX, **GEO)            # px value, strict
+    assert check_rho_d_um(DMAX, **GEO) is None      # µm value, healthy
+
+
+def test_warn_helper_warns_on_correction_only():
+    # pixel value -> corrected + warns
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        out = resolve_rho_d_um_warn(CORNER_PX, **GEO)
+    assert abs(out - DMAX) < 1.0
+    assert any("RhoD" in str(x.message) for x in w)
+    # already-µm value -> no warning
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        out = resolve_rho_d_um_warn(DMAX, **GEO)
+    assert abs(out - DMAX) < 1.0
+    assert not w