necksight 1.0.0__py3-none-any.whl

necksight/__init__.py

@@ -0,0 +1,24 @@
+"""NeckSight: Drosophila Optic Lobe T4/T5 Motion & LPLC2 Looming Reflex Engine."""
+
+from .emd import MotionOutput, T4T5MotionEngine
+from .looming import (
+    GiantFiberTrigger,
+    LPLC2LoomingReflex,
+    NeckSightPipeline,
+    attach_nltp_reflex,
+)
+from .retina import LaminaOutput, RetinaLaminaPreproc
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "LaminaOutput",
+    "RetinaLaminaPreproc",
+    "MotionOutput",
+    "T4T5MotionEngine",
+    "GiantFiberTrigger",
+    "LPLC2LoomingReflex",
+    "NeckSightPipeline",
+    "attach_nltp_reflex",
+]

necksight/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m necksight``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

necksight/cli.py

@@ -0,0 +1,348 @@
+"""Command-line interface for NeckSight (demo & benchmark-quick)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+
+from . import __version__
+from .looming import NeckSightPipeline
+
+
+def _make_clutter(
+    h: int, w: int, rng: np.random.Generator, base_scale: float = 64.0
+) -> np.ndarray:
+    """Synthesize a multi-scale natural-like textured clutter array in [40, 210]."""
+    yy, xx = np.meshgrid(
+        np.arange(h, dtype=np.float32),
+        np.arange(w, dtype=np.float32),
+        indexing="ij",
+    )
+    bg = np.zeros((h, w), dtype=np.float32)
+    for cycles in (1.0, 2.0, 4.0, 7.0):
+        wl = base_scale / cycles
+        phx = float(rng.uniform(0.0, 2.0 * np.pi))
+        phy = float(rng.uniform(0.0, 2.0 * np.pi))
+        amp = 1.0 / cycles
+        bg += amp * np.sin(2.0 * np.pi * xx / wl + phx) * np.cos(
+            2.0 * np.pi * yy / wl + phy
+        )
+    bg = (bg - float(np.min(bg))) / (float(np.ptp(bg)) + 1e-6)
+    return (45.0 + 160.0 * bg).astype(np.float32)
+
+
+def _run_demo(grid: int = 64, frames: int = 36, as_json: bool = False) -> Dict[str, Any]:
+    dt = 1.0 / 60.0
+    rng = np.random.default_rng(42)
+    yy, xx = np.meshgrid(
+        np.arange(grid, dtype=np.float32),
+        np.arange(grid, dtype=np.float32),
+        indexing="ij",
+    )
+    pano_w = grid + 4 * frames + 16
+    pano = _make_clutter(grid * 2, pano_w, rng, base_scale=float(grid))
+
+    scenarios: List[Dict[str, Any]] = []
+
+    # 1. Rightward translating sinusoidal grating
+    pipe = NeckSightPipeline(grid_size=grid)
+    vx_vals: List[float] = []
+    max_loom = 0.0
+    trig_any = False
+    for t in range(frames):
+        frame = 128.0 + 90.0 * np.sin(2.0 * np.pi * (xx - 1.2 * t) / 12.0)
+        _, mot, trig = pipe.step_full(frame, dt=dt)
+        if t >= 3:
+            vx_vals.append(mot.vx_flow)
+        max_loom = max(max_loom, trig.looming_score)
+        trig_any = trig_any or trig.triggered
+    scenarios.append(
+        {
+            "scenario": "rightward_grating",
+            "mean_vx_flow": round(float(np.mean(vx_vals)), 5),
+            "peak_looming_score": round(max_loom, 5),
+            "triggered": trig_any,
+        }
+    )
+
+    # 2. Fast camera yaw pan across cluttered scene (continuous 3.0 px/frame)
+    pipe.reset()
+    vx_vals = []
+    max_loom = 0.0
+    trig_any = False
+    for t in range(frames):
+        ox = 3 * t
+        frame = pano[grid // 2 : grid // 2 + grid, ox : ox + grid]
+        _, mot, trig = pipe.step_full(frame, dt=dt)
+        if t >= 3:
+            vx_vals.append(mot.vx_flow)
+        max_loom = max(max_loom, trig.looming_score)
+        trig_any = trig_any or trig.triggered
+    scenarios.append(
+        {
+            "scenario": "fast_camera_yaw_pan",
+            "mean_vx_flow": round(float(np.mean(vx_vals)), 5),
+            "peak_looming_score": round(max_loom, 5),
+            "triggered": trig_any,
+        }
+    )
+
+    # 3. 100x global sunlight glare step on cluttered scene
+    pipe.reset()
+    max_loom = 0.0
+    trig_any = False
+    crop = pano[:grid, :grid]
+    for t in range(frames):
+        mult = 100.0 if t >= frames // 2 else 1.0
+        frame = crop * mult
+        _, _, trig = pipe.step_full(frame, dt=dt)
+        max_loom = max(max_loom, trig.looming_score)
+        trig_any = trig_any or trig.triggered
+    scenarios.append(
+        {
+            "scenario": "glare_flash_100x",
+            "mean_vx_flow": 0.0,
+            "peak_looming_score": round(max_loom, 5),
+            "triggered": trig_any,
+        }
+    )
+
+    # 4. Head-on approaching dark obstacle on cluttered background
+    pipe.reset()
+    max_loom = 0.0
+    trig_any = False
+    first_trig_frame: Optional[int] = None
+    trig_ttc: float = float("inf")
+    cy = 0.5 * (grid - 1)
+    cx = 0.5 * (grid - 1)
+    dist = np.hypot(xx - cx, yy - cy)
+    for t in range(frames):
+        ttc_true = max((frames - t) * dt, 0.025)
+        radius = 0.09 * grid / ttc_true
+        edge = np.clip((radius - dist) / 1.2 + 0.5, 0.0, 1.0)
+        frame = crop * (1.0 - edge) + 12.0 * edge
+        _, _, trig = pipe.step_full(frame, dt=dt)
+        max_loom = max(max_loom, trig.looming_score)
+        if trig.triggered and not trig_any:
+            trig_any = True
+            first_trig_frame = t
+            trig_ttc = trig.est_ttc_s
+    lead_ms = (
+        round((frames - first_trig_frame) * dt * 1000.0, 1)
+        if first_trig_frame is not None
+        else 0.0
+    )
+    scenarios.append(
+        {
+            "scenario": "head_on_looming_obstacle",
+            "peak_looming_score": round(max_loom, 5),
+            "triggered": trig_any,
+            "lead_time_ms": lead_ms,
+            "est_ttc_at_trigger_s": round(trig_ttc, 3) if np.isfinite(trig_ttc) else None,
+        }
+    )
+
+    summary = {"version": __version__, "grid": grid, "scenarios": scenarios}
+    if as_json:
+        print(json.dumps(summary, indent=2))
+    else:
+        print(f"NeckSight v{__version__} -- Optic Lobe T4/T5 + LPLC2 Demo ({grid}x{grid})")
+        print("-" * 74)
+        for item in scenarios:
+            name = item["scenario"]
+            score = item["peak_looming_score"]
+            trig_flag = "TRIGGERED" if item["triggered"] else "quiet (0 false alarm)"
+            extra = ""
+            if "lead_time_ms" in item:
+                extra = (
+                    f" | lead={item['lead_time_ms']} ms"
+                    f" | est_ttc={item['est_ttc_at_trigger_s']} s"
+                )
+            elif "mean_vx_flow" in item:
+                extra = f" | vx_flow={item['mean_vx_flow']:+.4f}"
+            print(f"  {name:<26s} | score={score:.4f} | {trig_flag}{extra}")
+    return summary
+
+
+def _compute_auroc(pos_scores: Sequence[float], neg_scores: Sequence[float]) -> float:
+    pos = np.asarray(pos_scores, dtype=np.float64)
+    neg = np.asarray(neg_scores, dtype=np.float64)
+    diffs = pos[:, None] - neg[None, :]
+    wins = float(np.sum(diffs > 0.0) + 0.5 * np.sum(diffs == 0.0))
+    return wins / max(pos.size * neg.size, 1)
+
+
+def _run_benchmark_quick(
+    grid: int = 64, sequences: int = 24, as_json: bool = False
+) -> Dict[str, Any]:
+    rng = np.random.default_rng(2026)
+    dt = 1.0 / 60.0
+    frames = 32
+    n_pos = max(4, sequences // 2)
+    n_neg = max(4, sequences - n_pos)
+
+    pipe = NeckSightPipeline(grid_size=grid)
+    yy, xx = np.meshgrid(
+        np.arange(grid, dtype=np.float32),
+        np.arange(grid, dtype=np.float32),
+        indexing="ij",
+    )
+
+    pos_scores: List[float] = []
+    lead_times_ms: List[float] = []
+    for i in range(n_pos):
+        pipe.reset()
+        bg = _make_clutter(grid, grid, rng, base_scale=float(grid))
+        cx = 0.5 * (grid - 1) + float(rng.uniform(-6.0, 6.0))
+        cy = 0.5 * (grid - 1) + float(rng.uniform(-6.0, 6.0))
+        dist = np.hypot(xx - cx, yy - cy)
+        dark_obj = (i % 2) == 0
+        obj_val = 14.0 if dark_obj else 240.0
+        rate = float(rng.uniform(0.075, 0.115)) * grid
+        peak = 0.0
+        first_t: Optional[int] = None
+        for t in range(frames):
+            ttc = max((frames - t) * dt, 0.025)
+            rad = rate / ttc
+            edge = np.clip((rad - dist) / 1.2 + 0.5, 0.0, 1.0)
+            frame = bg * (1.0 - edge) + obj_val * edge
+            trig = pipe.step(frame, dt=dt)
+            peak = max(peak, trig.looming_score)
+            if trig.triggered and first_t is None:
+                first_t = t
+        pos_scores.append(peak)
+        if first_t is not None:
+            lead_times_ms.append((frames - first_t) * dt * 1000.0)
+
+    neg_scores: List[float] = []
+    false_alarms = 0
+    pano_w = grid + 4 * frames + 32
+    pano_h = grid + 2 * frames + 32
+    for i in range(n_neg):
+        pipe.reset()
+        pano = _make_clutter(pano_h, pano_w, rng, base_scale=float(grid))
+        peak = 0.0
+        fired = False
+        mode = i % 3
+        speed = int(rng.choice([-3, -2, 2, 3]))
+        start_x = 0 if speed > 0 else (-speed * frames + 4)
+        for t in range(frames):
+            if mode == 0:
+                ox = start_x + speed * t
+                oy = 4 + (t // 2)
+                frame = pano[oy : oy + grid, ox : ox + grid]
+            elif mode == 1:
+                mult = 80.0 if t >= frames // 2 else 1.0
+                frame = pano[:grid, :grid] * mult
+            else:
+                dist = np.hypot(xx - 0.5 * grid, yy - 0.5 * grid)
+                rad = max(2.0, 22.0 - 0.65 * t)
+                edge = np.clip((rad - dist) / 1.2 + 0.5, 0.0, 1.0)
+                frame = pano[:grid, :grid] * (1.0 - edge) + 18.0 * edge
+            trig = pipe.step(frame, dt=dt)
+            peak = max(peak, trig.looming_score)
+            fired = fired or trig.triggered
+        neg_scores.append(peak)
+        if fired:
+            false_alarms += 1
+
+    # Throughput timing on 600 frames
+    pipe.reset()
+    test_frames = [
+        _make_clutter(grid, grid, rng, base_scale=float(grid)) for _ in range(16)
+    ]
+    n_bench = 600
+    t0 = time.perf_counter()
+    for k in range(n_bench):
+        pipe.step(test_frames[k & 15], dt=dt)
+    elapsed = max(time.perf_counter() - t0, 1e-6)
+    fps = n_bench / elapsed
+
+    state_bytes = sum(
+        arr.nbytes
+        for arr in (
+            pipe.retina._baseline_log,
+            pipe.emd._d_on,
+            pipe.emd._d_off,
+        )
+        if arr is not None
+    )
+
+    auroc = _compute_auroc(pos_scores, neg_scores)
+    far = false_alarms / max(n_neg, 1)
+    mean_lead = float(np.mean(lead_times_ms)) if lead_times_ms else 0.0
+
+    result = {
+        "version": __version__,
+        "grid": f"{grid}x{grid}",
+        "sequences": n_pos + n_neg,
+        "auroc": round(auroc, 4),
+        "false_alarm_rate": round(far, 4),
+        "mean_lead_time_ms": round(mean_lead, 1),
+        "throughput_fps": round(fps, 1),
+        "persistent_state_kb": round(state_bytes / 1024.0, 2),
+    }
+
+    if as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(
+            f"NeckSight v{__version__} Quick Benchmark ({grid}x{grid}, N={n_pos + n_neg}):\n"
+            f"  Looming vs Yaw/Glare AUROC : {result['auroc']:.4f}\n"
+            f"  False-Alarm Rate (negatives): {result['false_alarm_rate'] * 100.0:.1f}%\n"
+            f"  Mean Warning Lead Time     : {result['mean_lead_time_ms']:.1f} ms\n"
+            f"  CPU Throughput (Python)    : {result['throughput_fps']:.1f} FPS\n"
+            f"  Persistent State Memory    : {result['persistent_state_kb']:.2f} KB"
+        )
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="necksight",
+        description="NeckSight: Drosophila Optic Lobe T4/T5 Motion & LPLC2 Looming Reflex.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"necksight {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_demo = sub.add_parser(
+        "demo", help="Run 4 synthetic optic-lobe scenarios (grating, yaw, glare, looming)."
+    )
+    p_demo.add_argument("--grid", type=int, default=64, help="Retinal grid size (default: 64)")
+    p_demo.add_argument("--frames", type=int, default=36, help="Frames per scenario (default: 36)")
+    p_demo.add_argument("--json", action="store_true", help="Emit JSON output")
+
+    p_bench = sub.add_parser(
+        "benchmark-quick", help="Run a fast accuracy & throughput benchmark."
+    )
+    p_bench.add_argument("--grid", type=int, default=64, help="Retinal grid size (default: 64)")
+    p_bench.add_argument(
+        "--sequences", type=int, default=24, help="Number of sequences (default: 24)"
+    )
+    p_bench.add_argument("--json", action="store_true", help="Emit JSON output")
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "demo":
+        _run_demo(grid=args.grid, frames=args.frames, as_json=args.json)
+        return 0
+    if args.command == "benchmark-quick":
+        _run_benchmark_quick(
+            grid=args.grid, sequences=args.sequences, as_json=args.json
+        )
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

necksight/emd.py

@@ -0,0 +1,283 @@
+"""Medulla/Lobula Plate T4 (ON) and T5 (OFF) 3-arm Elementary Motion Detectors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple, Union
+
+import numpy as np
+
+from .retina import LaminaOutput
+
+
+@dataclass(slots=True)
+class MotionOutput:
+    """Output of the T4/T5 Elementary Motion Detector and LPTC wide-field stage.
+
+    Attributes:
+        t4: 4-cardinal ON motion maps (keys ``"+X"``, ``"-X"``, ``"+Y"``, ``"-Y"``).
+        t5: 4-cardinal OFF motion maps (keys ``"+X"``, ``"-X"``, ``"+Y"``, ``"-Y"``).
+        pos_x: Combined (T4 + T5) rightward (+X) motion map.
+        neg_x: Combined (T4 + T5) leftward (-X) motion map.
+        pos_y: Combined (T4 + T5) downward (+Y) motion map.
+        neg_y: Combined (T4 + T5) upward (-Y) motion map.
+        flow_x: Opponent horizontal motion field ``pos_x - neg_x``.
+        flow_y: Opponent vertical motion field ``pos_y - neg_y``.
+        vx_flow: Wide-field horizontal LPTC (HS-like) optic flow.
+        vy_flow: Wide-field vertical LPTC (VS-like) optic flow.
+        yaw_pan: Wide-field equatorial horizontal tangential pan signal.
+        radial_divergence: Wide-field radial expansion (+) vs contraction (-) flow.
+    """
+
+    t4: Dict[str, np.ndarray]
+    t5: Dict[str, np.ndarray]
+    pos_x: np.ndarray
+    neg_x: np.ndarray
+    pos_y: np.ndarray
+    neg_y: np.ndarray
+    flow_x: np.ndarray
+    flow_y: np.ndarray
+    vx_flow: float
+    vy_flow: float
+    yaw_pan: float
+    radial_divergence: float
+
+    @property
+    def lptc(self) -> Tuple[float, float, float, float]:
+        """Return wide-field LPTC summary tuple ``(vx_flow, vy_flow, yaw_pan, radial_divergence)``."""
+        return (self.vx_flow, self.vy_flow, self.yaw_pan, self.radial_divergence)
+
+
+class T4T5MotionEngine:
+    """Biophysical 4-cardinal 3-arm T4 (ON) and T5 (OFF) motion engine.
+
+    Inspired by *Drosophila* T4 and T5 Lobula Plate direction-selective neurons
+    (Maisak et al., *Nature* 2013; Haag et al., *eLife* 2017):
+      - **Preferred-arm Hassenstein-Reichardt correlation**: multiplies delayed
+        trailing-column activity by prompt center-column activity while subtracting
+        synchronous self-correlation (``delayed_back * center - delayed_center * back``),
+        mathematically guaranteeing zero response to stationary contrast flicker.
+      - **Null-arm Barlow-Levick divisive shunting veto**: divides excitation by
+        ``1 + veto_gain * delayed_front`` so waves arriving from the null direction
+        actively suppress output.
+      - **Multi-stride receptive field** (1-ommatidium + weighted 2-ommatidia arms)
+        maintaining clean direction selectivity across both slow drift and rapid
+        pre-collision expansion speeds.
+      - **LPTC wide-field tangential integration** computing ``vx_flow``, ``vy_flow``,
+        ``yaw_pan``, and ``radial_divergence``.
+    """
+
+    def __init__(
+        self,
+        grid_size: Union[int, Tuple[int, int]] = 64,
+        *,
+        delay_alpha: float = 0.55,
+        veto_gain: float = 12.0,
+        stride2_weight: float = 0.5,
+        output_gain: float = 10.0,
+    ) -> None:
+        if isinstance(grid_size, int):
+            self.grid_shape: Tuple[int, int] = (grid_size, grid_size)
+        else:
+            self.grid_shape = (int(grid_size[0]), int(grid_size[1]))
+
+        gh, gw = self.grid_shape
+        if gh < 8 or gw < 8:
+            raise ValueError("grid_size dimensions must be >= 8")
+        if not (0.0 < delay_alpha <= 1.0):
+            raise ValueError("delay_alpha must be in (0.0, 1.0]")
+        if veto_gain < 0.0:
+            raise ValueError("veto_gain must be >= 0.0")
+
+        self.delay_alpha = float(delay_alpha)
+        self.veto_gain = float(veto_gain)
+        self.stride2_weight = float(stride2_weight)
+        self.output_gain = float(output_gain)
+
+        self._d_on: Optional[np.ndarray] = None
+        self._d_off: Optional[np.ndarray] = None
+
+        # Precompute wide-field LPTC radial unit vectors & equatorial HS weights
+        yy, xx = np.meshgrid(
+            np.arange(gh, dtype=np.float32),
+            np.arange(gw, dtype=np.float32),
+            indexing="ij",
+        )
+        cy = 0.5 * (gh - 1)
+        cx = 0.5 * (gw - 1)
+        dy = yy - cy
+        dx = xx - cx
+        rad = np.hypot(dx, dy)
+        inv_rad = np.where(rad > 1e-3, 1.0 / np.maximum(rad, 1e-3), 0.0)
+        self._ux = (dx * inv_rad).astype(np.float32)
+        self._uy = (dy * inv_rad).astype(np.float32)
+
+        # Equatorial Gaussian belt (models HS horizontal system cells)
+        norm_y = dy / max(0.5 * gh, 1.0)
+        hs_w = np.exp(-1.5 * (norm_y ** 2)).astype(np.float32)
+        self._hs_weights = hs_w / float(np.mean(hs_w))
+
+    def reset(self) -> None:
+        """Clear delayed T4/T5 temporal filter states."""
+        self._d_on = None
+        self._d_off = None
+
+    def _compute_cardinal_stride(
+        self,
+        prompt: np.ndarray,
+        delayed: np.ndarray,
+        stride: int,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        """Evaluate 3-arm HR + BL motion across all 4 cardinal directions for one stride."""
+        h, w = prompt.shape
+        g = self.veto_gain
+        s = stride
+
+        pos_x = np.zeros((h, w), dtype=np.float32)
+        neg_x = np.zeros((h, w), dtype=np.float32)
+        pos_y = np.zeros((h, w), dtype=np.float32)
+        neg_y = np.zeros((h, w), dtype=np.float32)
+
+        if w > 2 * s:
+            f_c = prompt[:, s : w - s]
+            d_c = delayed[:, s : w - s]
+            f_l = prompt[:, : w - 2 * s]
+            d_l = delayed[:, : w - 2 * s]
+            f_r = prompt[:, 2 * s :]
+            d_r = delayed[:, 2 * s :]
+
+            # +X (rightward: left -> center, null veto from right + Mi4 center adaptation)
+            hr_px = np.maximum(0.0, d_l * f_c - 1.35 * d_c * f_l)
+            pos_x[:, s : w - s] = hr_px / (1.0 + g * d_r)
+
+            # -X (leftward: right -> center, null veto from left + Mi4 center adaptation)
+            hr_nx = np.maximum(0.0, d_r * f_c - 1.35 * d_c * f_r)
+            neg_x[:, s : w - s] = hr_nx / (1.0 + g * d_l)
+
+        if h > 2 * s:
+            f_c = prompt[s : h - s, :]
+            d_c = delayed[s : h - s, :]
+            f_u = prompt[: h - 2 * s, :]
+            d_u = delayed[: h - 2 * s, :]
+            f_d = prompt[2 * s :, :]
+            d_d = delayed[2 * s :, :]
+
+            # +Y (downward: up -> center, null veto from down + Mi4 center adaptation)
+            hr_py = np.maximum(0.0, d_u * f_c - 1.35 * d_c * f_u)
+            pos_y[s : h - s, :] = hr_py / (1.0 + g * d_d)
+
+            # -Y (upward: down -> center, null veto from up + Mi4 center adaptation)
+            hr_ny = np.maximum(0.0, d_d * f_c - 1.35 * d_c * f_d)
+            neg_y[s : h - s, :] = hr_ny / (1.0 + g * d_u)
+
+        return pos_x, neg_x, pos_y, neg_y
+
+    def _compute_pathway(
+        self, prompt: np.ndarray, delayed: np.ndarray
+    ) -> Dict[str, np.ndarray]:
+        px1, nx1, py1, ny1 = self._compute_cardinal_stride(prompt, delayed, stride=1)
+        if self.stride2_weight > 0.0 and min(prompt.shape) > 6:
+            w2 = self.stride2_weight
+            px2, nx2, py2, ny2 = self._compute_cardinal_stride(prompt, delayed, stride=2)
+            scale = self.output_gain / (1.0 + w2)
+            px = (px1 + w2 * px2) * scale
+            nx = (nx1 + w2 * nx2) * scale
+            py = (py1 + w2 * py2) * scale
+            ny = (ny1 + w2 * ny2) * scale
+        else:
+            scale = self.output_gain
+            px = px1 * scale
+            nx = nx1 * scale
+            py = py1 * scale
+            ny = ny1 * scale
+
+        return {
+            "+X": px.astype(np.float32, copy=False),
+            "-X": nx.astype(np.float32, copy=False),
+            "+Y": py.astype(np.float32, copy=False),
+            "-Y": ny.astype(np.float32, copy=False),
+        }
+
+    def step(
+        self,
+        lamina_or_l1: Union[LaminaOutput, np.ndarray],
+        l2_off: Optional[np.ndarray] = None,
+    ) -> MotionOutput:
+        """Advance T4 (ON) and T5 (OFF) motion detectors by one frame."""
+        if isinstance(lamina_or_l1, LaminaOutput):
+            l1 = lamina_or_l1.l1_on
+            l2 = lamina_or_l1.l2_off
+        else:
+            if l2_off is None:
+                raise ValueError("l2_off must be provided when passing raw l1_on array")
+            l1 = np.asarray(lamina_or_l1, dtype=np.float32)
+            l2 = np.asarray(l2_off, dtype=np.float32)
+
+        if l1.shape != self.grid_shape or l2.shape != self.grid_shape:
+            raise ValueError(
+                f"Expected L1/L2 shape {self.grid_shape}, got {l1.shape} and {l2.shape}"
+            )
+
+        if self._d_on is None or self._d_off is None:
+            self._d_on = (self.delay_alpha * l1).astype(np.float32)
+            self._d_off = (self.delay_alpha * l2).astype(np.float32)
+            zeros = np.zeros(self.grid_shape, dtype=np.float32)
+            empty_dirs = {"+X": zeros, "-X": zeros.copy(), "+Y": zeros.copy(), "-Y": zeros.copy()}
+            empty_dirs_off = {"+X": zeros.copy(), "-X": zeros.copy(), "+Y": zeros.copy(), "-Y": zeros.copy()}
+            return MotionOutput(
+                t4=empty_dirs,
+                t5=empty_dirs_off,
+                pos_x=zeros.copy(),
+                neg_x=zeros.copy(),
+                pos_y=zeros.copy(),
+                neg_y=zeros.copy(),
+                flow_x=zeros.copy(),
+                flow_y=zeros.copy(),
+                vx_flow=0.0,
+                vy_flow=0.0,
+                yaw_pan=0.0,
+                radial_divergence=0.0,
+            )
+
+        t4 = self._compute_pathway(l1, self._d_on)
+        t5 = self._compute_pathway(l2, self._d_off)
+
+        # Update delayed low-pass states for next step
+        a = self.delay_alpha
+        self._d_on = ((1.0 - a) * self._d_on + a * l1).astype(np.float32, copy=False)
+        self._d_off = ((1.0 - a) * self._d_off + a * l2).astype(np.float32, copy=False)
+
+        pos_x = t4["+X"] + t5["+X"]
+        neg_x = t4["-X"] + t5["-X"]
+        pos_y = t4["+Y"] + t5["+Y"]
+        neg_y = t4["-Y"] + t5["-Y"]
+
+        flow_x = pos_x - neg_x
+        flow_y = pos_y - neg_y
+
+        vx_flow = float(np.mean(flow_x))
+        vy_flow = float(np.mean(flow_y))
+        yaw_pan = float(np.mean(flow_x * self._hs_weights))
+        radial_div = float(np.mean(flow_x * self._ux + flow_y * self._uy))
+
+        return MotionOutput(
+            t4=t4,
+            t5=t5,
+            pos_x=pos_x,
+            neg_x=neg_x,
+            pos_y=pos_y,
+            neg_y=neg_y,
+            flow_x=flow_x,
+            flow_y=flow_y,
+            vx_flow=vx_flow,
+            vy_flow=vy_flow,
+            yaw_pan=yaw_pan,
+            radial_divergence=radial_div,
+        )
+
+    def __call__(
+        self,
+        lamina_or_l1: Union[LaminaOutput, np.ndarray],
+        l2_off: Optional[np.ndarray] = None,
+    ) -> MotionOutput:
+        return self.step(lamina_or_l1, l2_off)