[stevevanhooser]

Ports +ndr/+reader/video.m from VH-Lab/NDR-matlab#140, synced through VH-Lab/NDR-matlab#143 (d2ebe98). Adds cross-language symmetry tests for it, paired with VH-Lab/NDR-matlab#144 (same branch name, claude/clever-bardeen-hf5jgx, so test-symmetry.yml checks it out).

The reader

• src/ndr/reader/video.py: ndr_reader_video mirrors every method of video.m under the same names, frame API only. Where MATLAB uses VideoReader, Python uses PyAV (av, the FFmpeg binding). It is an optional dependency in [formats] and [dev] and is only imported when a video is read. PyAV wheels bundle FFmpeg.
• Behaviour matches MATLAB:
  • An epoch is exactly one video file. Companion files are ignored and directories are expanded.
  • Frames come back in YXCZT order.
  • A frame's time is its stored presentation time, measured per decoded frame, so variable frame rate is handled correctly.
  • Those times are cached per file, keyed by path, size and mtime.
  • t0_t1 seeks near the end instead of decoding the whole file.
  • Grey pixel formats and grey-palette pal8 (MATLAB's 'Grayscale AVI') give C=1. Video above 8 bits gives uint16.
• Registry: adds the aliases video, mp4, avi and mov. The MATLAB-specific videoreader alias was dropped upstream in #143, so it is dropped here too.
• Bridge YAML: a video entry (regular_port, d2ebe98). Its decision_log covers where Python differs: a PyAV container stands in for VideoReader; readframes seeks by pts read from the demuxed packets (Python-only _framepts); and MATLAB error IDs map to ValueError, IndexError or FileNotFoundError.
• Tests: tests/test_video_reader.py (32 tests) ports TestVideo.m, plus cases for variable frame rate, a container with no frame count in its header, 16-bit grey, and the checked-in example files.

Symmetry

• New fixtures: tools/make_example_data.py now also writes example_video.avi (6-frame 12×16 uncompressed 24-bit RGB, 10 fps) and example_video_grey.avi (8-bit, grey palette).
  • The AVI is written by hand, laid out as MATLAB's VideoWriter writes it: BI_RGB frames stored bottom-up.
  • Both are uncompressed, so VideoReader reads them on every platform and the ports must agree pixel for pixel.
  • They are committed byte-identically to NDR-matlab's example_data/, and the README is updated in both repos.
• New tests: tests/symmetry/{make,read}_artifacts/reader/test_read_video.py, paired with NDR-matlab's +makeArtifacts/+readArtifacts/+reader/readVideo.m. They compare:
  • numframes, framesize, dimensionorder, datatype, frametimes, t0_t1, epochclock, channels and image metadata;
  • exact pixels of the first and last RGB frame per channel, a SelectC read, and an out-of-order greyscale read.
• Time tolerance: frame times are compared to 1e-6 s, since each port measures them through its own decoder.

Bug fixed by the new fixture

FFmpeg decodes a bottom-up 8-bit DIB with a negative line stride. The pal8 path read the plane in memory order, so MATLAB-written greyscale AVIs came back upside down. Test files written by FFmpeg are top-down, so they could not show this. A unit test on the checked-in bottom-up file now covers it, and that test fails without the fix.

Verification

• pytest: 723 passed, 15 skipped (same skips as before), 24 xfailed.
• NDR_BRIDGE_CHECK_STRICT=1 bridge completeness + conventions, run against a full NDR-matlab clone: 191 passed.
• black and ruff check are clean.
• Cross-language symmetry (run 39476490054, attempt 2), against NDR-matlab claude/clever-bardeen-hf5jgx:
  • Every video check ran and passed in both directions: MATLAB make → Python read, and Python make → MATLAB read.
  • MATLAB's VideoReader reads the grey-palette AVI as one channel, matching Python pixel for pixel.
  • Attempt 1 had resolved NDR-matlab to main because the matching branch was pushed seconds later, so its video checks skipped. It was re-run rather than counted.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QjkvVXsdCVw6NNe5SnGNyX