Recreation of Dixon, Abrams, Jacobs & Pless, "On analyzing video with very
small motions". See CLAUDE.md, CONTEXT.md and docs/adr/ for the domain
vocabulary and decisions behind this code, and
.scratch/principal-motion-components/spec.md for the full spec and
milestone breakdown.
pip install -e ".[test]"
Requires Python 3.11+. Dependencies: numpy, scipy, opencv-python, scikit-learn (ADR-0005).
pytest
Most tests drive the analyze() seam directly with generated arrays from the
synthetic harness in src/pmc/synthetic.py; a handful — the CLI smoke test
and a few in the synthetic-harness, ingest and flow-visualisation suites —
also write and re-read an actual video file to exercise src/pmc/video_io.py.
pmc analyze <video> <bundle_dir> --k 2
pmc flow <bundle_dir> <out_video.mp4> --reference 0
pmc project <bundle_dir> <new_video> <out_video.mp4>
analyze decodes a video to luminance, runs PCA and the Motion Basis solve,
and writes an analysis bundle to <bundle_dir>. flow reads that bundle
back and renders a Flow Field (relative to --reference) for every frame as
a colour-wheel video; pass --overlay-video <original.mp4> to render the
flow blended over the original colour footage instead. project takes a
video of frames the analysis never saw, projects them onto the bundle's
existing Principal Component Images (the paper's Sec. 4 fast path), and
renders their Flow Fields the same way flow does; it prints a timing
number for the projection step (see issue 06 for the measured trend and why
it is not a reproduction of the paper's own speed claim).
Videos are downsampled by default so the decoded frame matrix stays bounded
in memory (ADR-0003): unless --downsample is given, the longest side is
capped to pmc.video_io.DEFAULT_MAX_DIMENSION (480px). Pass --downsample 1
to decode at full resolution, or any other factor to override the cap.
Milestones 1-6 of the spec (ingest + PCA, the synthetic harness, both Motion
Basis solvers and their equivalence comparison, flow visualisation, and
new-frame projection) are implemented — see
.scratch/principal-motion-components/issues/01..06.
Segmentation (issue 07) and the figure reproductions (issue 08) are not yet
built.