chasepy 2.0.0__py3-none-any.whl

chase/__init__.py

@@ -0,0 +1,104 @@
+"""chase — a modular CHASE/HIS calibration + flare-analysis pipeline.
+
+Nothing here is a forced pipeline: every stage is an importable function you can
+call on its own, *and* there is a one-call orchestrator (:func:`run_pipeline`), a
+config-file workflow (:class:`Config`), a CLI (``chase``), and a TUI
+(``chase-tui``) layered on top of the exact same functions.
+
+Quick start (SDK)
+-----------------
+>>> import chase
+>>> cube, hdr, wav = chase.load_cube("RSM..._HA.fits")
+>>> seq = chase.load_flare_sequence("/path/to/fits", patch=[940, 1080, 1870, 2040])
+>>> aligned = chase.optical_flow_align(seq["ha_cubes"], reference=seq["align_ref"])
+>>> contrast, _ = chase.contrast_profile(aligned, background=seq["ha_bg"])
+
+Quick start (lazy)
+------------------
+>>> from chase import Config, run_pipeline
+>>> run_pipeline(Config(fits_dir="/path/to/fits", patch=[940, 1080, 1870, 2040],
+...                     contrast=True, temperature="double"))
+"""
+
+from __future__ import annotations
+
+from . import _compat  # noqa: F401  (lzma stub + headless matplotlib)
+
+__version__ = "2.0.0"
+
+# --- I/O -------------------------------------------------------------------
+from .io import (
+    discover_fits,
+    download_file,
+    extract_disk_center,
+    load_cube,
+    load_fits_data,
+    load_flare_sequence,
+    resolve_inputs,
+    save_cube_fits,
+    save_npz,
+)
+download = download_file  # SDK alias
+
+# --- Calibration -----------------------------------------------------------
+from .calib import (
+    align_spectrum,
+    atlas_calibrate,
+    correct_spectral_drift,
+    create_optical_flow_solver,
+    find_disk_center,
+    hough_disk_center,
+    integral_scaling,
+    normalize_intensity,
+    optical_flow_align,
+    phase_shift,
+    planck_inversion,
+    recenter,
+    resample_wavelength,
+    track_and_crop,
+    warp_cube,
+)
+
+# --- Analysis --------------------------------------------------------------
+from .analysis import (
+    contrast_profile,
+    fe_eb_temperature,
+    fe_planck_temperature,
+    fe_voigt_temperature,
+    halpha_width_map,
+    halpha_width_temperature,
+    width_to_temperature,
+)
+
+# --- Visualisation ---------------------------------------------------------
+from .viz import (
+    make_animation,
+    make_contrast_animation,
+    make_temperature_animation,
+)
+
+# --- Orchestration ---------------------------------------------------------
+from .config import Config, load_config
+from .pipeline import run_pipeline
+
+__all__ = [
+    "__version__",
+    # io
+    "download", "download_file", "resolve_inputs", "discover_fits",
+    "load_cube", "load_fits_data", "load_flare_sequence", "extract_disk_center",
+    "save_cube_fits", "save_npz",
+    # calib
+    "find_disk_center", "hough_disk_center", "recenter", "phase_shift",
+    "track_and_crop", "optical_flow_align", "warp_cube",
+    "create_optical_flow_solver", "resample_wavelength", "correct_spectral_drift",
+    "align_spectrum", "normalize_intensity", "integral_scaling",
+    "atlas_calibrate", "planck_inversion",
+    # analysis
+    "contrast_profile", "halpha_width_map", "halpha_width_temperature",
+    "width_to_temperature", "fe_planck_temperature", "fe_eb_temperature",
+    "fe_voigt_temperature",
+    # viz
+    "make_animation", "make_contrast_animation", "make_temperature_animation",
+    # orchestration
+    "Config", "load_config", "run_pipeline",
+]

chase/_compat.py

@@ -0,0 +1,78 @@
+"""Environment-compatibility shims.
+
+Importing :mod:`chase._compat` (which happens automatically when you ``import
+chase``) makes the package usable in two awkward-but-common situations:
+
+1. **Python builds without the ``_lzma`` C extension.**  ``astropy`` imports
+   :mod:`lzma` at load time, so on a pyenv/conda interpreter compiled without
+   the xz headers an ``import astropy`` explodes with ``ModuleNotFoundError:
+   _lzma``.  We install a minimal stub *before* astropy is imported.  The stub
+   carries a real ``__spec__`` because :mod:`importlib` refuses to treat a bare
+   ``ModuleType`` as a package.
+
+2. **Headless matplotlib.**  We default ``MPLBACKEND`` to ``Agg`` and point
+   ``MPLCONFIGDIR`` at a writable per-user cache so figure generation works on a
+   server / in CI with no ``$HOME/.config`` write access.
+
+Both shims are idempotent and only activate when needed, so importing this on a
+fully-featured interpreter is a no-op.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+__all__ = ["ensure_lzma_stub", "ensure_headless_matplotlib"]
+
+
+def ensure_lzma_stub() -> bool:
+    """Install a stub :mod:`lzma` module if the real one is unavailable.
+
+    Returns
+    -------
+    bool
+        ``True`` if a stub was installed, ``False`` if the real module works.
+    """
+    try:  # pragma: no cover - depends on interpreter build
+        import lzma  # noqa: F401
+
+        return False
+    except ImportError:
+        from importlib.machinery import ModuleSpec
+        from types import ModuleType
+
+        stub = ModuleType("lzma")
+        stub.__spec__ = ModuleSpec("lzma", loader=None)
+
+        class _MissingLZMAFile:  # noqa: D401 - mirror of v50 stub
+            def __init__(self, *args, **kwargs):
+                raise RuntimeError(
+                    "lzma is unavailable in this Python build; rebuild Python "
+                    "with the xz/liblzma headers to read .xz-compressed FITS."
+                )
+
+        stub.LZMAFile = _MissingLZMAFile
+        sys.modules["lzma"] = stub
+        return True
+
+
+def ensure_headless_matplotlib(config_dir: str | os.PathLike | None = None) -> None:
+    """Configure matplotlib for headless rendering (Agg + writable cache)."""
+    os.environ.setdefault("MPLBACKEND", "Agg")
+    if "MPLCONFIGDIR" not in os.environ:
+        if config_dir is None:
+            config_dir = Path(tempfile.gettempdir()) / "chase_mplconfig"
+        cfg = Path(config_dir)
+        try:
+            cfg.mkdir(parents=True, exist_ok=True)
+            os.environ["MPLCONFIGDIR"] = str(cfg)
+        except OSError:  # pragma: no cover - fall back to matplotlib default
+            pass
+
+
+# Apply on import; safe and idempotent.
+ensure_lzma_stub()
+ensure_headless_matplotlib()

chase/analysis/__init__.py

@@ -0,0 +1,23 @@
+"""Science analysis: contrast profiles and temperature maps."""
+
+from .contrast import contrast_profile
+from .temperature import (
+    fe_eb_temperature,
+    fe_planck_temperature,
+    fe_voigt_temperature,
+    halpha_width_map,
+    halpha_width_temperature,
+    measure_halpha_width,
+    width_to_temperature,
+)
+
+__all__ = [
+    "contrast_profile",
+    "halpha_width_map",
+    "halpha_width_temperature",
+    "measure_halpha_width",
+    "width_to_temperature",
+    "fe_planck_temperature",
+    "fe_eb_temperature",
+    "fe_voigt_temperature",
+]

chase/analysis/contrast.py

@@ -0,0 +1,70 @@
+"""Spectral contrast profile (wavelength vs time).
+
+The contrast map averages an aligned Hα cube over the spatial axes to get one
+spectrum per frame, then expresses each as a fractional excess over a quiet-Sun
+baseline.  The physically correct definition uses a **separate background patch**::
+
+    contrast(t, λ) = (flare(t, λ) − bg(t, λ)) / bg(t, λ)  −  [same at frame 0]
+
+which removes instrumental throughput drift that a naive ``frame_t/frame_0 − 1``
+leaves in.  When no background patch is supplied it falls back to the naive form.
+
+In the resulting wavelength-vs-time image the erupting CME shows up as a red
+Doppler feature in the Hα wing — the science hook for the A&A letter.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+__all__ = ["contrast_profile"]
+
+
+def contrast_profile(
+    ha_cubes: np.ndarray,
+    background: Optional[np.ndarray] = None,
+    baseline_frame: int = 0,
+    correct_drift: bool = True,
+):
+    """Compute the wavelength-vs-time contrast profile of an aligned cube.
+
+    Parameters
+    ----------
+    ha_cubes : ndarray (nframes, nchannels, H, W)
+        Aligned Hα spectral stack.
+    background : ndarray (nframes, nchannels, H, W) or None, optional
+        Quiet-Sun background patch (same shape).  If given, the
+        ``(flare − bg)/bg`` form is used; otherwise ``frame_t/frame_0 − 1``.
+    baseline_frame : int, optional
+        Frame whose profile is subtracted as the pre-flare baseline.
+    correct_drift : bool, optional
+        Apply 1-D spectral-drift correction before averaging.
+
+    Returns
+    -------
+    contrast : ndarray (nframes, nchannels)
+        The contrast map (time along axis 0, wavelength along axis 1).
+    mean_spec : ndarray (nframes, nchannels)
+        Spatially-averaged flare spectra (post drift-correction).
+    """
+    cube = ha_cubes
+    if correct_drift:
+        from ..calib.wavelength import correct_spectral_drift
+
+        cube, _ = correct_spectral_drift(cube, verbose=False)
+
+    mean_spec = np.mean(cube, axis=(2, 3))  # (nframes, nch)
+
+    if background is not None:
+        mean_bg = np.mean(background, axis=(2, 3))
+        mean_bg = np.where(mean_bg == 0, 1.0, mean_bg)
+        contrast = (mean_spec - mean_bg) / mean_bg
+        contrast = contrast - contrast[baseline_frame]
+    else:
+        ref = mean_spec[baseline_frame].copy()
+        ref[ref == 0] = 1.0
+        contrast = mean_spec / ref[np.newaxis, :] - 1.0
+
+    return contrast, mean_spec

chase/analysis/temperature.py

@@ -0,0 +1,246 @@
+"""Temperature maps — split by line physics.
+
+Two regimes, two methods:
+
+* **Hα → chromospheric temperature** via the line *width* (Molnar et al. 2019,
+  ApJ 881, 99).  Hα forms out of LTE, so a Planck inversion is invalid; instead
+  the half-depth width maps onto an ALMA brightness temperature,
+  ``T[K] = (width[Å] − 0.553) / 6.12e-5``.
+
+* **Fe I → photospheric temperature** via a Planck inversion.  Fe I 6569 Å is a
+  photospheric LTE line, so ``B_ν(T) = I_core`` holds once the data is on an
+  absolute radiance scale (see :func:`chase.calib.atlas_calibrate`).  Three core
+  estimators are offered:
+  - :func:`fe_planck_temperature` — Gaussian fit to the line core (default);
+  - :func:`fe_eb_temperature`     — Eddington–Barbier per-wavelength inversion;
+  - :func:`fe_voigt_temperature`  — Voigt fit (robust when the Fe line is
+    under-sampled).
+
+References
+----------
+Molnar et al. 2019, ApJ 881, 99 (10.3847/1538-4357/ab2ba3).
+Eddington–Barbier: aa21259-13 (A&A 2013).
+ISPy FTS atlas: ISP-SST/ISPy.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import numpy as np
+
+from ..calib.intensity import planck_inversion
+
+__all__ = [
+    "measure_halpha_width",
+    "halpha_width_map",
+    "width_to_temperature",
+    "halpha_width_temperature",
+    "fe_planck_temperature",
+    "fe_eb_temperature",
+    "fe_voigt_temperature",
+]
+
+_MOLNAR_OFFSET = 0.553
+_MOLNAR_SLOPE = 6.12e-5
+
+
+# ---------------------------------------------------------------------------
+# Hα width → chromospheric temperature (Molnar 2019)
+# ---------------------------------------------------------------------------
+def _find_crossing(spectrum, wavelengths, indices, level):
+    for j in range(len(indices) - 1):
+        i0, i1 = indices[j], indices[j + 1]
+        s0, s1 = spectrum[i0], spectrum[i1]
+        if (s0 <= level <= s1) or (s1 <= level <= s0):
+            if s1 == s0:
+                return wavelengths[i0]
+            frac = (level - s0) / (s1 - s0)
+            return wavelengths[i0] + frac * (wavelengths[i1] - wavelengths[i0])
+    return np.nan
+
+
+def measure_halpha_width(spectrum, wavelengths, core_wavelength=6562.8, wing_offset=1.0):
+    """Half-depth Hα width (Å) of one spectrum (Molnar 2019 definition).
+
+    Finds the core minimum, measures the depth relative to the mean intensity at
+    ``±wing_offset`` Å, and returns the wavelength separation where the profile
+    crosses the half-depth level.  Returns NaN if the measurement is ill-defined.
+    """
+    from scipy.interpolate import interp1d
+
+    core_mask = np.abs(wavelengths - core_wavelength) < 0.5
+    if core_mask.sum() < 3:
+        return np.nan
+    region = np.where(core_mask)[0]
+    local_min = region[np.argmin(spectrum[region])]
+    core_wav = wavelengths[local_min]
+    i_core = spectrum[local_min]
+
+    wb, wr = core_wav - wing_offset, core_wav + wing_offset
+    if wb < wavelengths[0] or wr > wavelengths[-1]:
+        return np.nan
+    f = interp1d(wavelengths, spectrum, kind="linear")
+    depth = 0.5 * (float(f(wb)) + float(f(wr))) - i_core
+    if depth <= 0:
+        return np.nan
+    level = i_core + 0.5 * depth
+
+    blue = np.where(wavelengths < core_wav)[0][::-1]
+    red = np.where(wavelengths > core_wav)[0]
+    if len(blue) < 2 or len(red) < 2:
+        return np.nan
+    bx = _find_crossing(spectrum, wavelengths, blue, level)
+    rx = _find_crossing(spectrum, wavelengths, red, level)
+    if np.isnan(bx) or np.isnan(rx):
+        return np.nan
+    return rx - bx
+
+
+def width_to_temperature(width):
+    """Molnar 2019: ``T[K] = (width[Å] − 0.553) / 6.12e-5``."""
+    return (width - _MOLNAR_OFFSET) / _MOLNAR_SLOPE
+
+
+def halpha_width_map(ha_cube, wavelengths, core_wavelength=6562.8) -> np.ndarray:
+    """Per-pixel Hα width map (Å) for one frame's cube ``(nch, H, W)``."""
+    nch, H, W = ha_cube.shape
+    width = np.full((H, W), np.nan, dtype=np.float32)
+    for y in range(H):
+        for x in range(W):
+            spec = ha_cube[:, y, x]
+            if np.any(np.isnan(spec)) or np.all(spec == 0):
+                continue
+            width[y, x] = measure_halpha_width(spec, wavelengths, core_wavelength)
+    return width
+
+
+def halpha_width_temperature(
+    ha_cube, wavelengths, core_wavelength=6562.8, t_min=4000.0, t_max=20000.0
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Chromospheric temperature map from Hα width (Molnar 2019).
+
+    Returns ``(temperature_map, width_map)``; temperatures outside
+    ``[t_min, t_max]`` are masked to NaN.
+    """
+    width = halpha_width_map(ha_cube, wavelengths, core_wavelength)
+    temp = width_to_temperature(width)
+    temp[(temp < t_min) | (temp > t_max)] = np.nan
+    return temp, width
+
+
+# ---------------------------------------------------------------------------
+# Fe I → photospheric temperature (Planck) — three estimators
+# ---------------------------------------------------------------------------
+def _gaussian(x, amp, mu, sigma, offset):
+    return offset + amp * np.exp(-0.5 * ((x - mu) / sigma) ** 2)
+
+
+def _fit_fe_core_gaussian(spectrum, wavelengths, n_lowest=6):
+    from scipy.optimize import curve_fit
+
+    if np.any(np.isnan(spectrum)) or np.all(spectrum == 0):
+        return np.nan
+    lowest = np.sort(np.argsort(spectrum)[:n_lowest])
+    wav_fit, spec_fit = wavelengths[lowest], spectrum[lowest]
+    cont = spectrum.max()
+    try:
+        popt, _ = curve_fit(
+            _gaussian, wav_fit, spec_fit,
+            p0=[spec_fit.min() - cont, wav_fit[np.argmin(spec_fit)], 0.05, cont],
+            maxfev=2000,
+        )
+        i_core = popt[3] + popt[0]
+        return float(i_core) if i_core > 0 else np.nan
+    except (RuntimeError, ValueError):
+        return np.nan
+
+
+def fe_planck_temperature(fe_cube, wavelengths, ifact, t_min=3000.0, t_max=8000.0):
+    """Photospheric T from a Gaussian-core Planck inversion of Fe I.
+
+    For each pixel: Gaussian-fit the line core to the ~6 lowest channels, scale
+    DN→radiance with ``ifact`` (from :func:`chase.calib.atlas_calibrate`), and
+    invert the Planck function at the Fe core wavelength.
+
+    Returns ``(temperature_map, core_intensity_map)``.
+    """
+    nch, H, W = fe_cube.shape
+    core_int = np.full((H, W), np.nan, dtype=np.float32)
+    for y in range(H):
+        for x in range(W):
+            core_int[y, x] = _fit_fe_core_gaussian(fe_cube[:, y, x], wavelengths)
+    fe_core_wav = wavelengths[np.argmin(np.mean(fe_cube, axis=(1, 2)))]
+    temp = planck_inversion(core_int * ifact, wavelength_ang=fe_core_wav).astype(np.float32)
+    temp[(temp < t_min) | (temp > t_max)] = np.nan
+    return temp, core_int
+
+
+def fe_eb_temperature(fe_cube, wavelengths, ifact, t_min=3000.0, t_max=8000.0):
+    """Eddington–Barbier photospheric T (per-wavelength Planck inversion).
+
+    At disk centre (μ=1) ``I(λ) = B(T(τ_λ=1), λ)``, so every wavelength probes a
+    different height.  Returns ``(temp_cube, temp_core, temp_continuum)`` where
+    ``temp_cube`` is ``(nch, H, W)``, ``temp_core`` samples the per-pixel minimum,
+    and ``temp_continuum`` averages the last three channels.
+    """
+    nch, H, W = fe_cube.shape
+    I_cgs = fe_cube.astype(np.float64) * ifact
+    temp_cube = np.empty_like(I_cgs, dtype=np.float32)
+    for ich in range(nch):
+        temp_cube[ich] = planck_inversion(I_cgs[ich], wavelengths[ich]).astype(np.float32)
+    core_ch = np.argmin(fe_cube, axis=0)
+    temp_core = np.take_along_axis(temp_cube, core_ch[np.newaxis], axis=0)[0]
+    temp_cont = np.mean(temp_cube[-3:], axis=0)
+    for arr in (temp_core, temp_cont):
+        arr[(arr < t_min) | (arr > t_max)] = np.nan
+    return temp_cube, temp_core, temp_cont
+
+
+def _fit_fe_voigt(spectrum, wavelengths):
+    from scipy.optimize import curve_fit
+    from scipy.special import voigt_profile
+
+    if np.any(np.isnan(spectrum)) or np.all(spectrum == 0):
+        return np.nan, np.nan
+    cont = float(np.mean(spectrum[-3:]))
+    core_idx = int(np.argmin(spectrum))
+
+    def model(wav, amp, center, sigma, gamma, continuum, slope):
+        v = voigt_profile(wav - center, sigma, gamma)
+        vpeak = voigt_profile(0.0, sigma, gamma)
+        return (continuum + slope * (wav - center)) - amp * v / vpeak
+
+    try:
+        popt, _ = curve_fit(
+            model, wavelengths, spectrum,
+            p0=[cont - spectrum[core_idx], wavelengths[core_idx], 0.05, 0.02, cont, 0.0],
+            bounds=(
+                [0, wavelengths[0], 0.001, 0.001, 0, -2000],
+                [cont * 2, wavelengths[-1], 0.5, 0.5, cont * 2, 2000],
+            ),
+            maxfev=5000,
+        )
+        i_core = popt[4] - popt[0]
+        return (float(i_core), float(popt[1])) if i_core > 0 else (np.nan, np.nan)
+    except (RuntimeError, ValueError):
+        return np.nan, np.nan
+
+
+def fe_voigt_temperature(fe_cube, wavelengths, ifact, t_min=3000.0, t_max=8000.0):
+    """Photospheric T from a Voigt-core Planck inversion of Fe I.
+
+    Robust when the Fe I line is under-sampled (a Gaussian can miss the true
+    core).  Returns ``(temperature_map, core_intensity_map, center_map)``.
+    """
+    nch, H, W = fe_cube.shape
+    core_map = np.full((H, W), np.nan, dtype=np.float32)
+    center_map = np.full((H, W), np.nan, dtype=np.float32)
+    for y in range(H):
+        for x in range(W):
+            ic, cen = _fit_fe_voigt(fe_cube[:, y, x].astype(np.float64), wavelengths)
+            core_map[y, x], center_map[y, x] = ic, cen
+    median_center = float(np.nanmedian(center_map))
+    temp = planck_inversion(core_map * ifact, median_center).astype(np.float32)
+    temp[(temp < t_min) | (temp > t_max)] = np.nan
+    return temp, core_map, center_map

chase/calib/__init__.py

@@ -0,0 +1,48 @@
+"""Calibration stages: spatial, alignment, wavelength, intensity.
+
+Every function here is usable on its own — nothing forces a full pipeline.
+"""
+
+from .spatial import (
+    find_disk_center,
+    hough_disk_center,
+    phase_shift,
+    recenter,
+    track_and_crop,
+)
+from .align import create_optical_flow_solver, optical_flow_align, warp_cube
+from .wavelength import (
+    align_spectrum,
+    correct_spectral_drift,
+    cross_correlation_shift,
+    resample_wavelength,
+)
+from .intensity import (
+    atlas_calibrate,
+    integral_scaling,
+    normalize_intensity,
+    planck_inversion,
+)
+
+__all__ = [
+    # spatial
+    "find_disk_center",
+    "hough_disk_center",
+    "phase_shift",
+    "recenter",
+    "track_and_crop",
+    # align
+    "create_optical_flow_solver",
+    "optical_flow_align",
+    "warp_cube",
+    # wavelength
+    "align_spectrum",
+    "correct_spectral_drift",
+    "cross_correlation_shift",
+    "resample_wavelength",
+    # intensity
+    "atlas_calibrate",
+    "integral_scaling",
+    "normalize_intensity",
+    "planck_inversion",
+]

chase/calib/align.py

@@ -0,0 +1,127 @@
+"""Fine alignment via dense optical flow.
+
+Integer crop-tracking (:func:`chase.calib.spatial.track_and_crop`) removes whole
+pixel jitter; residual sub-pixel wobble is removed here with a dense optical-flow
+warp.
+
+The flow field is computed **once per frame** from a single flare-free reference
+channel converted to ``uint8`` (TV-L1 if OpenCV's ``optflow`` module is present,
+else Farneback).  The resulting displacement map is then applied with
+``cv2.remap`` (cubic) to **every** wavelength channel of the float32 science
+cubes — the science data never leaves float precision.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+__all__ = ["create_optical_flow_solver", "calculate_optical_flow", "warp_cube", "optical_flow_align"]
+
+
+def create_optical_flow_solver():
+    """Return a TV-L1 optical-flow solver, or ``None`` to signal Farneback."""
+    import cv2
+
+    try:
+        return cv2.optflow.DualTVL1OpticalFlow_create()
+    except AttributeError:
+        try:
+            return cv2.DualTVL1OpticalFlow_create()
+        except AttributeError:
+            return None
+
+
+def calculate_optical_flow(ref_u8: np.ndarray, cur_u8: np.ndarray, solver=None) -> np.ndarray:
+    """Compute the dense flow field mapping ``cur`` onto ``ref`` (both uint8)."""
+    import cv2
+
+    if solver is not None:
+        return solver.calc(ref_u8, cur_u8, None)
+    return cv2.calcOpticalFlowFarneback(
+        ref_u8, cur_u8, None,
+        pyr_scale=0.5, levels=3, winsize=15, iterations=3,
+        poly_n=5, poly_sigma=1.2, flags=0,
+    )
+
+
+def _to_u8(img: np.ndarray) -> np.ndarray:
+    import cv2
+
+    return cv2.normalize(img, None, 0, 255, cv2.NORM_MINMAX).astype(np.uint8)
+
+
+def warp_cube(cube: np.ndarray, map_x: np.ndarray, map_y: np.ndarray) -> np.ndarray:
+    """Apply a precomputed remap to every channel of a cube (cubic, reflect)."""
+    import cv2
+
+    out = np.empty_like(cube)
+    for ch in range(cube.shape[0]):
+        out[ch] = cv2.remap(
+            cube[ch], map_x, map_y,
+            interpolation=cv2.INTER_CUBIC, borderMode=cv2.BORDER_REFLECT,
+        )
+    return out
+
+
+def optical_flow_align(
+    cubes: np.ndarray,
+    reference: Optional[np.ndarray] = None,
+    ref_idx: int = 0,
+    method: str = "tvl1",
+    extra_cubes: Optional[np.ndarray] = None,
+    verbose: bool = False,
+):
+    """Stabilise a frame sequence with optical-flow warping.
+
+    Parameters
+    ----------
+    cubes : ndarray (nframes, nchannels, H, W)
+        Science cubes to warp (e.g. the Hα stack).  Stays float32.
+    reference : ndarray (nframes, H, W) or None, optional
+        Per-frame flare-free image used to *compute* the flow.  If None, the last
+        channel of ``cubes`` is used.  Pass the Fe I last wavelength here to
+        avoid stabilising the eruption away.
+    ref_idx : int, optional
+        Index of the reference frame everything is aligned to.
+    method : {"tvl1", "farneback"}, optional
+        Optical-flow algorithm (TV-L1 falls back to Farneback if unavailable).
+    extra_cubes : ndarray (nframes, nchannels2, H, W) or None, optional
+        A second stack (e.g. Fe I) warped with the *same* per-frame map.
+    verbose : bool, optional
+
+    Returns
+    -------
+    aligned : ndarray, same shape as ``cubes``
+    aligned_extra : ndarray or None
+        Present only when ``extra_cubes`` is given.
+    """
+    import cv2  # noqa: F401  (ensure available early)
+
+    nframes, nch, H, W = cubes.shape
+    if reference is None:
+        reference = cubes[:, -1, :, :]
+
+    solver = create_optical_flow_solver() if method == "tvl1" else None
+    ref_u8 = _to_u8(reference[ref_idx])
+
+    X, Y = np.meshgrid(np.arange(W, dtype=np.float32), np.arange(H, dtype=np.float32))
+
+    aligned = np.empty_like(cubes)
+    aligned_extra = np.empty_like(extra_cubes) if extra_cubes is not None else None
+
+    for i in range(nframes):
+        cur_u8 = _to_u8(reference[i])
+        flow = calculate_optical_flow(ref_u8, cur_u8, solver)
+        map_x = (X + flow[..., 0]).astype(np.float32)
+        map_y = (Y + flow[..., 1]).astype(np.float32)
+        aligned[i] = warp_cube(cubes[i], map_x, map_y)
+        if aligned_extra is not None:
+            aligned_extra[i] = warp_cube(extra_cubes[i], map_x, map_y)
+        if verbose:
+            print(f"  optical-flow frame {i}/{nframes - 1} aligned")
+
+    if aligned_extra is not None:
+        return aligned, aligned_extra
+    return aligned