From 8043873f2ed9f3ee220e7ef6576c87781fa385af Mon Sep 17 00:00:00 2001 From: ruv Date: Mon, 27 Jul 2026 11:10:45 -0400 Subject: [PATCH] fix(vitals): HeartRateExtractor silently dropped every frame with phases=[] HeartRateExtractor::extract() computed n = residuals.len().min(n_subcarriers).min(phases.len()), so an empty (or short) phases slice truncated n to 0 and every single frame was rejected via the n == 0 guard -- silently, with no way to distinguish it from any other None. BreathingExtractor documents weights=[] as "equal weighting"; HeartRateExtractor's phases=[] must mean the same thing (no per-subcarrier coherence data available), not "refuse all input". Fix: n now derives from residuals/n_subcarriers only. compute_phase_coherence_signal looks up phases via .get() and treats any missing entry as full coherence (weight 1.0), mirroring breathing::fuse_weighted_residuals's uniform-weight fallback for a missing/partial weights slice. Updated the now-inaccurate PyO3 docstrings that claimed phases=[] was invalid. Fixes #1423 Co-Authored-By: claude-flow --- python/src/bindings/vitals.rs | 13 +- python/tests/test_vitals.py | 32 +++++ .../wifi-densepose-vitals/src/heartrate.rs | 136 ++++++++++++++++-- 3 files changed, 166 insertions(+), 15 deletions(-) diff --git a/python/src/bindings/vitals.rs b/python/src/bindings/vitals.rs index c30844a0..2d840922 100644 --- a/python/src/bindings/vitals.rs +++ b/python/src/bindings/vitals.rs @@ -252,8 +252,9 @@ impl PyBreathingExtractor { /// hr = HeartRateExtractor.esp32_default() # 56 subcarriers, 100 Hz, 15s window /// /// # Feed residuals and matching unwrapped phases from your preprocessor. -/// # Unlike BreathingExtractor weights, phases=[] is invalid for heart-rate -/// # extraction because the Rust core requires phase data for each subcarrier. +/// # Like BreathingExtractor's weights, phases=[] means "no per-subcarrier +/// # coherence information available" and falls back to equal weighting +/// # across all subcarriers -- it does NOT silently drop every frame. /// est = hr.extract(residuals=[0.01, -0.02, …], phases=[0.0, 0.01, …]) /// if est is not None: /// print(est.value_bpm, est.confidence) @@ -281,9 +282,11 @@ impl PyHeartRateExtractor { } /// Extract heart rate from per-subcarrier residuals and matching - /// per-subcarrier unwrapped phases (radians). Empty phases are invalid - /// and return `None` because the Rust extractor requires phase data. - /// GIL released during DSP. + /// per-subcarrier unwrapped phases (radians). A short or empty `phases` + /// slice falls back to equal weighting for any subcarrier missing phase + /// data (issue #1423) -- it does not truncate the number of subcarriers + /// fused, and does not silently return `None` for every frame. GIL + /// released during DSP. fn extract( &mut self, py: Python<'_>, diff --git a/python/tests/test_vitals.py b/python/tests/test_vitals.py index 942d2960..d4ddac4e 100644 --- a/python/tests/test_vitals.py +++ b/python/tests/test_vitals.py @@ -223,6 +223,38 @@ def test_heart_rate_extract_with_synthetic_signal_and_phases() -> None: ) +def test_heart_rate_extract_with_empty_phases_produces_estimates() -> None: + """Issue #1423 regression: `phases=[]` must fall back to equal + weighting (mirroring `BreathingExtractor`'s `weights=[]`), not silently + return `None` for every frame. + + Reproduces the GH-issue repro: a noiseless 1.2 Hz (72 BPM) sine + identical across all 56 subcarriers, fed frame-by-frame with an empty + `phases` list. Before the fix this produced 0/4000 estimates; the same + signal with `phases=[1.0] * 56` already produced thousands. + """ + hr = HeartRateExtractor.esp32_default() + sample_rate = 100.0 + target_freq = 1.2 # 72 BPM + n_samples = 4000 + + produced = 0 + for i in range(n_samples): + t = i / sample_rate + base = math.sin(2.0 * math.pi * target_freq * t) + residuals = [base] * 56 + est = hr.extract(residuals=residuals, phases=[]) + if est is not None: + produced += 1 + assert math.isfinite(est.value_bpm) + assert 0.0 <= est.confidence <= 1.0 + + assert produced > 0, ( + "HeartRateExtractor.extract(residuals=..., phases=[]) must not silently " + "return None for every frame of a clean 72 BPM signal (issue #1423)" + ) + + # ─── Build feature flag ────────────────────────────────────────────── diff --git a/v2/crates/wifi-densepose-vitals/src/heartrate.rs b/v2/crates/wifi-densepose-vitals/src/heartrate.rs index 924fd2f2..4b2cd350 100644 --- a/v2/crates/wifi-densepose-vitals/src/heartrate.rs +++ b/v2/crates/wifi-densepose-vitals/src/heartrate.rs @@ -98,7 +98,17 @@ impl HeartRateExtractor { /// Returns a `VitalEstimate` with heart rate in BPM, or `None` /// if insufficient data or too few subcarriers. pub fn extract(&mut self, residuals: &[f64], phases: &[f64]) -> Option { - let n = residuals.len().min(self.n_subcarriers).min(phases.len()); + // `n` is driven by `residuals` (and the subcarrier cap) only, NOT by + // `phases.len()`. Before this fix, a missing/short `phases` slice + // (e.g. `phases=[]`, documented as meaning "equal weighting", mirroring + // `BreathingExtractor`'s `weights=[]`) truncated `n` down to + // `phases.len()`, so `phases=[]` forced `n == 0` and `extract()` + // silently returned `None` for every frame (issue #1423). Missing + // phase entries are now treated by `compute_phase_coherence_signal` + // as "no coherence information available" and fused with equal + // weight, exactly like `breathing::fuse_weighted_residuals`'s + // uniform-weight fallback for a missing/partial `weights` slice. + let n = residuals.len().min(self.n_subcarriers); if n == 0 { return None; } @@ -249,29 +259,44 @@ impl HeartRateExtractor { /// Combines amplitude residuals with inter-subcarrier phase coherence /// to enhance the cardiac signal. Subcarriers with similar phase /// derivatives are likely sensing the same body surface. +/// +/// `phases` may be shorter than `n` (including empty). Missing entries mean +/// the caller has no per-subcarrier phase measurement to weight by, so that +/// subcarrier is fused with full coherence (weight 1.0) instead of being +/// excluded -- i.e. `phases=[]` degrades gracefully to equal weighting +/// across all `n` residuals, exactly like `breathing::fuse_weighted_residuals` +/// falling back to a uniform weight for a missing/partial `weights` slice +/// (issue #1423; `phases=[]` is documented as meaning equal weights, the +/// same as `BreathingExtractor`'s `weights=[]`). fn compute_phase_coherence_signal(residuals: &[f64], phases: &[f64], n: usize) -> f64 { if n <= 1 { return residuals.first().copied().unwrap_or(0.0); } + let phase_at = |i: usize| phases.get(i).copied(); + // Compute inter-subcarrier phase differences as coherence weights. // Adjacent subcarriers with small phase differences are more coherent. + // If either phase value needed for a pair is missing, treat the pair as + // fully coherent (weight 1.0) rather than panicking or excluding it. let mut weighted_sum = 0.0; let mut weight_total = 0.0; - for i in 0..n { - let coherence = if i + 1 < n { - let phase_diff = (phases[i + 1] - phases[i]).abs(); - // Higher coherence when phase difference is small - (-phase_diff).exp() + for (i, &r) in residuals.iter().enumerate().take(n) { + let neighbor = if i + 1 < n { + Some(i + 1) } else if i > 0 { - let phase_diff = (phases[i] - phases[i - 1]).abs(); - (-phase_diff).exp() + Some(i - 1) } else { - 1.0 + None }; - weighted_sum += residuals[i] * coherence; + let coherence = match neighbor.and_then(|j| phase_at(i).zip(phase_at(j))) { + Some((a, b)) => (-(b - a).abs()).exp(), + None => 1.0, + }; + + weighted_sum += r * coherence; weight_total += coherence; } @@ -561,4 +586,95 @@ mod tests { assert!(v.is_finite(), "filtered_history[{i}] must be finite, got {v}"); } } + + /// Issue #1423 bug-catching test. + /// + /// Reproduces the exact GH-issue repro: 56 subcarriers @ 100 Hz (ESP32 + /// defaults), a noiseless 1.2 Hz (72 BPM) sine identical across every + /// subcarrier, fed frame-by-frame with an **empty** `phases` slice. + /// + /// Before the fix, `extract()`'s `n` was + /// `residuals.len().min(n_subcarriers).min(phases.len())`, so + /// `phases = []` forced `n == 0` and every single frame returned `None` + /// (0/4000 estimates) even though the identical call with + /// `phases = [1.0; 56]` produced thousands of valid estimates. `phases=[]` + /// must mean "no coherence weighting available", i.e. equal weighting -- + /// the same documented fallback `BreathingExtractor` already honors for + /// `weights=[]` -- not "invalid input, refuse everything". + #[test] + fn issue_1423_empty_phases_yields_equal_weighting_not_silent_none() { + let n = 56usize; + let sample_rate = 100.0; + let heart_freq = 1.2; // 72 BPM + + let mut ext = HeartRateExtractor::esp32_default(); + let mut estimates_with_empty_phases = 0usize; + for i in 0..4000usize { + let t = i as f64 / sample_rate; + let base = (2.0 * std::f64::consts::PI * heart_freq * t).sin(); + let residuals = vec![base; n]; + if ext.extract(&residuals, &[]).is_some() { + estimates_with_empty_phases += 1; + } + } + + assert!( + estimates_with_empty_phases > 0, + "HeartRateExtractor::extract() with phases=[] must not silently return None for \ + every frame of a clean 72 BPM signal (issue #1423); got 0/4000 estimates", + ); + + // Sanity check against the issue's own comparison point: an + // equivalent uniform, non-empty `phases` slice (all subcarriers at + // the same phase, i.e. zero pairwise difference => full coherence, + // exactly what the equal-weighting fallback now produces for the + // empty case too) must yield a comparable number of estimates -- + // the two should behave the same, not `0` vs `thousands`. + let mut ext2 = HeartRateExtractor::esp32_default(); + let uniform_phases = vec![1.0_f64; n]; + let mut estimates_with_uniform_phases = 0usize; + for i in 0..4000usize { + let t = i as f64 / sample_rate; + let base = (2.0 * std::f64::consts::PI * heart_freq * t).sin(); + let residuals = vec![base; n]; + if ext2.extract(&residuals, &uniform_phases).is_some() { + estimates_with_uniform_phases += 1; + } + } + + assert_eq!( + estimates_with_empty_phases, estimates_with_uniform_phases, + "phases=[] (equal-weight fallback) must behave identically to a uniform, \ + non-empty phases slice of the same length -- both represent 'no differential \ + coherence information', got {estimates_with_empty_phases} vs \ + {estimates_with_uniform_phases}", + ); + } + + /// Issue #1423 companion: a `phases` slice *shorter* than `residuals` + /// (partial coverage) must fall back to equal weighting for the missing + /// tail rather than truncating the whole fusion down to the phases that + /// happen to be present -- mirrors + /// `breathing::partial_weights_are_renormalized_not_scale_mixed`. + #[test] + fn partial_phases_do_not_truncate_subcarrier_count() { + // 8 residuals, only 2 phase values supplied. + let residuals = [1.0_f64; 8]; + let phases = [0.0_f64, 0.0]; + let fused = compute_phase_coherence_signal(&residuals, &phases, 8); + + // All residuals are identical (1.0), so regardless of how coherence + // weights are distributed the fused value must still be 1.0 -- but + // this only holds if all 8 residuals are actually used. Before the + // fix, `n` would have been truncated to `phases.len() == 2`, so the + // caller-facing `extract()` never even reached this function with + // `n == 8`; this test pins `compute_phase_coherence_signal` itself + // to handle a short `phases` slice safely and correctly when called + // with the full `n`. + assert!( + (fused - 1.0).abs() < 1e-12, + "fusion with a partial phases slice must still average all {} residuals, got {fused}", + residuals.len(), + ); + } }