Validate magnification on synthetic shapes; add --phase-sigma

[joeljose]

Closes #39

Full write-up with plots and every measurement: docs/research/synthetic-validation.md.

What's in this PR

• scripts/synthetic_shapes.py: renders pulsating circles, squares, rings and hollow squares (r(t) = r0 + r1·sin(2πft), camera-like blurred edges) and measures the magnified output against the exact ideal (radius r0 + k·r1·sin). It reports gain, phase lag, harmonics, isotropy, jitter, ghost energy and line doubling.
• tests/test_synthetic_shapes.py (12 tests, ~20 s): frequency response against the filter model at 0.3/1.5/8 Hz, zero phase lag, band mode inside and outside the band, k = 1 identity, isotropy for circle and square, the lowpass limitation (documented as a range), and no doubling of a 1 px ring at 2 px motion.
• --phase-sigma / magnify_motions(phase_sigma=...): amplitude-weighted spatial smoothing of the amplified phase (Wadhwa et al. 2013). CPU only, off by default; rejected with --gpu. The phase step was refactored to "phase + (k−1)·detail", which is numerically the same as before (golden test passes).
• scripts/bench_high_k.py: textured-scene (ground truth) and face.mp4 benchmark.
• README: new "Synthetic validation" section, updated Limitations (output motion below k; keep magnified displacement under ~3 px), options table. CHANGELOG.

Findings

• Correct:

  • Gain against frequency follows H2(f)·(1+(k−1)(1−Hlow(f))) from 0.1 to 12 Hz with 0.00-frame phase lag.
  • Band mode gives ~9× in band and 1.0× out of band.
  • k = 1 gives gain 1.003.
  • Isotropy spread is 2–3%; harmonics are < 0.6%.

• Limitation 1: the lowpass band isn't magnified. A filled circle reaches 0.88k at 5 levels and 0.92k at 7; thin lines reach ~1.0k.

• Limitation 2: beyond ~3 px of magnified displacement, edges stop short and leave echo edges (1 px ring: 0.89k at 3 px, 0.61k at 8 px).

• Options:

  option	result	kept?
  amplitude-weighted smoothing σ=1	noise 1.18× → 0.93× and halo 1.15× → 0.86× on the textured scene; costs ~9% magnification on clean edges	opt-in
  max_phase π/2	lower gain, up to 8× more ghost energy	removed
  level selection	loses magnification, or (skipping level 1) adds noise	removed

Acceptance criteria

• "≥ 30% lower face.mp4 background noise at k = 10 without reducing magnification": not met, and not meetable as written.
  • The background patches sit within one coarse-level footprint of the head, so ~88% of their flicker is the head's magnified motion spreading out (halo), not noise.
  • Magnifying only levels 1–3 drops it 34%, but loses most of the magnification.
  • The report proposes the synthetic noise/halo/ghost metrics instead.
• "Each option can be enabled or disabled, defaults documented": met for the one kept option (--phase-sigma, default off).

Tests

• CPU image: 104 passed, 3 skipped.
• GPU image on an RTX 4050: 127 passed, 1 skipped.