Skip to content

Let users set the amplified band in Hz (--freq-low/--freq-high) - #65

Merged
joeljose merged 1 commit into
mainfrom
feature/38-band-in-hz
Sep 28, 2026
Merged

joeljose merged 1 commit into
mainfrom
feature/38-band-in-hz

Conversation

@joeljose

@joeljose joeljose commented Sep 28, 2026 •

Copy link
Copy Markdown
Owner

Closes #38

What changed

  • New --freq-low / --freq-high (Hz, given together). They select band mode: an ideal temporal band-pass on the phase, phase += (k - 1) * bandpass(phase), so in-band motion is multiplied by k and out-of-band motion is untouched. bandpass_1d extends the series symmetrically by its own length before the FFT to avoid wrap-around. The GPU path has the same mode (_gpu_bandpass_filter, chunked, with OOM retry).
  • Chose a true band-pass over mapping Hz onto the flat-top windows: the flat-top roll-off is too gradual to amplify 1.2 Hz ~10x while keeping 0.3 Hz under 2x, which is what the acceptance criterion needs. --filter {butter,...} wasn't added; one well-defined band mode is enough.
  • The Parameters block always prints the band in Hz: Band: 0.8–2 Hz (ideal band-pass), or for width mode the measured half-amplitude points, e.g. Band: ~0.20–8.59 Hz (flat-top, width 80) at 30 fps (flattop_band()).
  • -w still works and stays the default when no band is given (existing output unchanged). Passing it prints a deprecation note. Errors for: only one band edge, low ≥ high, -w together with a band, and a band above Nyquist (fps / 2).
  • README: the Applications table now gives Hz ranges, plus the options table, an example, Temporal Filtering docs and Tips. CHANGELOG updated.

Measured gains (synthetic texture oscillation, 30 fps, --freq-low 0.8 --freq-high 2 -k 10)

Oscillation 0.3 Hz 0.8 Hz (edge) 1.2 Hz 2.0 Hz (edge) 5 Hz
Gain 1.01 6.4 9.17 4.0 1.00

The acceptance test asserts 8–12x at 1.2 Hz and < 2x at 0.3 and 5 Hz.

Tests

  • Band gains (above), bandpass_1d keeps only the in-band sinusoid, flattop_band(80) ≈ 0.20 / 8.6 Hz at 30 fps.
  • CLI: band run, default band printed, argument validation (4 cases), Nyquist check, -w deprecation note.
  • GPU: band mode agrees with the CPU path (PSNR ≥ 60 dB). A full --gpu -k 10 --freq-low 0.8 --freq-high 2 run on face.mp4 takes 27.3 s and passes verify_output.py.
  • CPU image 89 passed, 3 skipped. GPU image on an RTX 4050 112 passed, 1 skipped. GPU-path tests on CPU tensors 22 passed.

-w is a filter width in frames: its meaning changes with the frame rate,
and the upper edge was fixed by the width-2 smoothing pass. With
--freq-low/--freq-high the pipeline uses an ideal temporal band-pass
(bandpass_1d, FFT of a symmetrically extended series; GPU path too):
phase += (k - 1) * bandpass(phase). On a synthetic test with 0.8-2 Hz
and k=10, a 1.2 Hz oscillation is amplified 9.2x while 0.3 Hz and 5 Hz
stay at 1.0x. The Parameters block prints the band in Hz in both modes
(the default -w 80 is about 0.20-8.59 Hz at 30 fps). -w keeps working and
stays the default, but prints a deprecation note when given.

Closes #38
@joeljose
joeljose merged commit 62c39bb into main Sep 28, 2026
2 checks passed
@joeljose
joeljose deleted the feature/38-band-in-hz branch September 28, 2026 05:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let users set the temporal band in Hz (--freq-low/--freq-high) instead of a filter width in frames

1 participant