[1mattbecker]

Summary

Motion energy for any number of ROIs of any shape, computed in one decode pass per video.

• ROIs are binary masks. The ROI annotator's *_masks.npz export (masks (H, W, K), roi_ids) is the input. Boxes, polygons and compound shapes all arrive as masks. --roi-masks DIR matches one file per camera by name, ignoring case and separators, so the annotator's …_BottomCamera_masks.npz matches bottom_camera.mp4. --roi X Y W H still works as a single rectangular mask. In Python, ROIs are a plain dict of name → boolean mask.
• One pass per frame. Each frame is decoded and differenced once. The whole frame and every ROI are summed from that diff in one vectorized call, so cost grows with the total masked area, not the ROI count.
• One NPZ per video replaces the four .npy files. It holds me and me_clean (frames × (1+K), column 0 = full_frame), keyframe_mask, first_frame, roi_ids, pixel_counts and avg_map. It is written atomically, and the input masks are copied next to it for provenance.
• Frame-aligned outputs. Saved traces, and the traces compute_motion_energy returns, have one value per frame (row i = frame first_frame + i), with NaN at row 0, which has no previous frame.
• QC plots. The trace PNG shows the full-frame trace above an ROI × time z-scored heatmap. The map PNG and the MP4 show ROI outlines, and --viz-rois chooses which traces scroll in the MP4.
• Smaller CLI changes. --csv replaces --format. An invalid --start-frame/--end-frame range is refused up front, as are masks that are empty or don't match the video's size.

Breaking changes

• The .npy outputs are replaced by {stem}_motion_energy.npz. The old motion_energy_clean.npy is now npz["me_clean"][:, 0].
• Readers must stop adding their own leading NaN. The library now pads frame 0. The metadata key n_me_frames is removed, so existing padding logic fails loudly instead of shifting traces by one frame.
• compute_motion_energy(rois={name: mask}) returns a frame-aligned MotionEnergyResult (it was roi= returning a 4-tuple of N−1 arrays).
• --format {npy,csv,both} is replaced by --csv.

Downstream updates (kinematics_analysis, the ME capsule, the batch launcher, the ROI annotator) are listed in docs/plans/downstream-migration.md. They are not part of this PR. The version bump to 0.4.0 will follow as a separate chore: PR.

Testing

• 101 tests, 100% coverage; ruff, ruff format and mypy --strict are clean.
• Real session: behavior_800886_2025-09-11_13-52-51 (flat layout, 1000 fps, 2.6M frames per camera), with 10 ROIs drawn in the annotator. Every ROI trace matches a brute-force per-mask reference (max error 1e-7), and the outlines sit on the intended anatomy. 6 ROIs cost about 8% throughput (1040 → 955 fps).
• Sample clip: whole-frame-only throughput matches 0.3.0. 100 ROIs of ~3,000 px run at about 55% of it; kernel measurements are in docs/design-notes.md.
• The IBL comparison notebook runs and reaches the same conclusions.

A simplification pass before merge removed ~250 lines: the RoiSet class, bounding boxes, size guards and the separate frame-alignment step. The real-session check was re-run afterwards with identical results.

Plan and as-built notes: docs/plans/multi-roi-motion-energy.md.

🤖 Generated with Claude Code

[1mattbecker]

reviewed