motionmag — phase-based video motion magnification

A phase-based (Riesz pyramid) motion magnification pipeline and interactive probe, per Wadhwa et al., Riesz Pyramids for Fast Phase-Based Video Magnification (ICCP 2014). Built as an instrument: the per-pixel phase signal is vibration data. Click a pixel, read its frequency spectrum, choose a band, and amplify it — the RDI-Iris workflow.

Install

pip install -e ".[viewer,dev]"      # numpy/scipy/opencv/av + PySide6/pyqtgraph + pytest
# optional GPU path: pip install -e ".[gpu]"

The desktop app (PySide6)

python viewer/app.py                 # then Open a clip
python viewer/app.py fidget_spinner.mp4

1. Open a clip. It auto-detects the true capture fps (e.g. slow-mo phone clips that record 240 fps on a 30 fps timeline), reports frame-pacing jitter and any luminance flicker peaks. Set Downscale higher for faster iteration.
2. Analyze — builds the Riesz decomposition once (the expensive step). Tick Use GPU (CUDA) for a ~15× faster decomposition if a CUDA GPU is present.
3. Click any pixel → its phase waveform and amplitude spectrum appear.
4. Drag the band on the spectrum (or type f_lo/f_hi), set α, Magnify. Only the temporal filter + collapse re-run, so band changes are quick.
5. Play and toggle Original / Magnified.

Command line

# magnify a band
python scripts/magnify_cli.py in.mp4 -o out.mp4 --flo 20 --fhi 60 --alpha 25 --fps 240

# analysis only: jitter, flicker, dominant-motion report
python scripts/magnify_cli.py in.mp4 --analyze

# side-by-side original|magnified, downscaled for speed
python scripts/magnify_cli.py in.mp4 -o out.mp4 --flo 2 --fhi 6 --alpha 15 --downscale 2 --side-by-side

Tests

pytest -q

The acceptance test (tests/test_synthetic.py) renders a sub-pixel oscillating blob and verifies the pipeline amplifies a chosen band by ~(1+α) while leaving out-of-band motion untouched.

Notes / gotchas the code handles

• The low-pass residual is never magnified. Motion of very coarse features needs a deep pyramid (small Min level size) so its energy lands in band levels rather than the residual. Default min_size is deliberately small.
• Amplitude-weighted spatial blur (σ) denoises real footage but can reduce gain on tiny isolated features (opposite-edge phase cancellation) — a synthetic-blob artifact, not present on extended textures.
• Pyramid reconstruction uses the published Riesz FIR taps, which trade ~1% reconstruction ripple for clean band isolation (see pyramid.py). This never biases the phase the probe measures.
• f_lo = 0 is invalid — DC is excluded from the passband by design.

Layout

motionmag/   io, pyramid, riesz, temporal, magnify, probe, config, gpu
viewer/      app.py — PySide6 spectrum-probe viewer
scripts/     magnify_cli.py, fetch_samples.py
tests/       pyramid / riesz / temporal / synthetic / probe / gpu

License

Apache License 2.0 — Copyright 2026 Andrew Salinas Labs LLC. See LICENSE.

This is an independent, from-scratch implementation of the algorithm in Wadhwa et al., Riesz Pyramids for Fast Phase-Based Video Magnification (ICCP 2014); no author source code is included. The technique is covered by third-party patents (e.g. U.S. 9,338,331, MIT) — this repo is a research/educational reimplementation and grants no rights in those patents. See NOTICE for attribution and third-party dependency licenses.