Skip to main content

autoeq_measurements/read/source/
load.rs

1use super::{MeasurementRef, MeasurementSource};
2use crate::Curve;
3use crate::read::{interpolate_log_space, read_curve_from_csv};
4use ndarray::Array1;
5use std::error::Error;
6use std::path::PathBuf;
7
8fn measurement_identity(measurement: &MeasurementRef) -> String {
9    measurement
10        .path()
11        .map(|path| path.display().to_string())
12        .or_else(|| measurement.name().map(String::from))
13        .unwrap_or_else(|| "inline".to_string())
14}
15
16fn load_measurements_strict(measurements: &[MeasurementRef]) -> Result<Vec<Curve>, Box<dyn Error>> {
17    let mut curves = Vec::with_capacity(measurements.len());
18    let mut failures = Vec::new();
19    for measurement in measurements {
20        match load_measurement(measurement) {
21            Ok(curve) => curves.push(curve),
22            Err(error) => failures.push(format!("{}: {error}", measurement_identity(measurement))),
23        }
24    }
25    if failures.is_empty() {
26        Ok(curves)
27    } else {
28        Err(format!(
29            "Failed to load {} of {} measurements: {}",
30            failures.len(),
31            measurements.len(),
32            failures.join("; ")
33        )
34        .into())
35    }
36}
37
38fn grids_match(left: &Array1<f64>, right: &Array1<f64>) -> bool {
39    left.len() == right.len() && left.iter().zip(right).all(|(a, b)| (a - b).abs() <= 1e-9)
40}
41
42fn validate_and_align_curves(
43    curves: &[Curve],
44    context: &str,
45) -> Result<Vec<Curve>, Box<dyn Error>> {
46    let Some(first) = curves.first() else {
47        return Err(format!("{context} is empty").into());
48    };
49    for (index, curve) in curves.iter().enumerate() {
50        curve.validate(&format!("{context} {index}"))?;
51    }
52
53    let reference_grid = first.freq.clone();
54    Ok(curves
55        .iter()
56        .map(|curve| {
57            if grids_match(&reference_grid, &curve.freq) {
58                curve.clone()
59            } else {
60                interpolate_log_space(&reference_grid, curve)
61            }
62        })
63        .collect())
64}
65
66/// Load a single measurement from a file or inline data
67pub fn load_measurement(measurement: &MeasurementRef) -> Result<Curve, Box<dyn Error>> {
68    let curve = match measurement {
69        MeasurementRef::Path(path) => {
70            read_curve_from_csv(path).map_err(|error| -> Box<dyn Error> {
71                format!("Failed to load measurement '{}': {error}", path.display()).into()
72            })?
73        }
74        MeasurementRef::Named { path, .. } => {
75            read_curve_from_csv(path).map_err(|error| -> Box<dyn Error> {
76                format!("Failed to load measurement '{}': {error}", path.display()).into()
77            })?
78        }
79        MeasurementRef::Inline(inline) => {
80            // If inline data is empty but csv_path is provided, load from CSV
81            if inline.frequencies.is_empty() || inline.magnitude_db.is_empty() {
82                if let Some(ref csv_path) = inline.csv_path {
83                    read_curve_from_csv(&PathBuf::from(csv_path))?
84                } else {
85                    return Err(format!(
86                        "Inline measurement has empty data and no csv_path to fall back to (name: {:?})",
87                        inline.name
88                    )
89                    .into());
90                }
91            } else {
92                if inline.frequencies.len() != inline.magnitude_db.len() {
93                    return Err(format!(
94                        "Inline measurement has mismatched lengths: {} frequencies, {} magnitude values",
95                        inline.frequencies.len(),
96                        inline.magnitude_db.len()
97                    )
98                    .into());
99                }
100
101                let phase = inline.phase_deg.as_ref().and_then(|p| {
102                    if p.len() != inline.frequencies.len() {
103                        log::debug!(
104                            "Warning: phase array length ({}) doesn't match frequencies ({}), ignoring phase",
105                            p.len(),
106                            inline.frequencies.len()
107                        );
108                        None
109                    } else {
110                        Some(Array1::from(p.clone()))
111                    }
112                });
113
114                Curve {
115                    freq: Array1::from(inline.frequencies.clone()),
116                    spl: Array1::from(inline.magnitude_db.clone()),
117                    phase,
118                    ..Default::default()
119                }
120            }
121        }
122    };
123    curve.validate("measurement")?;
124    Ok(curve)
125}
126
127/// Load individual measurement curves from a source without averaging.
128///
129/// - `Single` → returns `vec![curve]`
130/// - `Multiple` → loads all curves, interpolates to first curve's frequency grid
131/// - `InMemory` → returns `vec![curve]`
132pub fn load_source_individual(source: &MeasurementSource) -> Result<Vec<Curve>, Box<dyn Error>> {
133    match source {
134        MeasurementSource::Single(s) => {
135            let curve = load_measurement(&s.measurement)?;
136            Ok(vec![curve])
137        }
138        MeasurementSource::InMemory(curve) => {
139            curve.validate("in-memory measurement")?;
140            Ok(vec![curve.clone()])
141        }
142        MeasurementSource::InMemoryMultiple(curves) => {
143            validate_and_align_curves(curves, "in-memory measurement")
144        }
145        MeasurementSource::Multiple(m) => {
146            if m.measurements.is_empty() {
147                return Err("Measurement list is empty".into());
148            }
149            let curves = load_measurements_strict(&m.measurements)?;
150            validate_and_align_curves(&curves, "measurement")
151        }
152    }
153}
154
155/// Average a set of curves in the power domain after interpolating to the
156/// first curve's frequency grid.
157///
158/// All curves must be non-empty; callers are responsible for checking.
159fn average_curves_power_domain(curves: &[Curve]) -> Curve {
160    let ref_curve = &curves[0];
161    let freqs = ref_curve.freq.clone();
162
163    let mut power_sum = Array1::<f64>::zeros(freqs.len());
164    let mut coherence_sum = curves
165        .iter()
166        .all(|curve| curve.coherence.is_some())
167        .then(|| Array1::<f64>::zeros(freqs.len()));
168    let preserve_phase = curves.iter().all(|curve| {
169        curve
170            .phase
171            .as_ref()
172            .is_some_and(|phase| phase.len() == curve.freq.len())
173    });
174    let mut phase_real_sum = preserve_phase.then(|| Array1::<f64>::zeros(freqs.len()));
175    let mut phase_imag_sum = preserve_phase.then(|| Array1::<f64>::zeros(freqs.len()));
176
177    for curve in curves {
178        let interpolated = interpolate_log_space(&freqs, curve);
179        // Convert SPL to power (proportional to pressure squared)
180        // Power = 10^(SPL/10)
181        let p = interpolated.spl.mapv(|spl| 10.0_f64.powf(spl / 10.0));
182        power_sum = power_sum + p;
183        if let (Some(sum), Some(coherence)) =
184            (coherence_sum.as_mut(), interpolated.coherence.as_ref())
185        {
186            *sum = sum.clone() + coherence;
187        }
188        if let (Some(real_sum), Some(imag_sum), Some(phase)) = (
189            phase_real_sum.as_mut(),
190            phase_imag_sum.as_mut(),
191            interpolated.phase.as_ref(),
192        ) {
193            for (((real, imag), &spl), &phase_deg) in real_sum
194                .iter_mut()
195                .zip(imag_sum.iter_mut())
196                .zip(interpolated.spl.iter())
197                .zip(phase.iter())
198            {
199                let amplitude = 10.0_f64.powf(spl / 20.0);
200                let phase_rad = phase_deg.to_radians();
201                *real += amplitude * phase_rad.cos();
202                *imag += amplitude * phase_rad.sin();
203            }
204        }
205    }
206
207    let avg_power = power_sum / (curves.len() as f64);
208    let avg_spl = avg_power.mapv(|p| 10.0 * p.log10());
209    let coherence = coherence_sum.map(|sum| sum / curves.len() as f64);
210    let phase = phase_real_sum.zip(phase_imag_sum).map(|(real, imag)| {
211        Array1::from_iter(
212            real.iter()
213                .zip(imag.iter())
214                .map(|(&real, &imag)| imag.atan2(real).to_degrees()),
215        )
216    });
217
218    Curve {
219        freq: freqs,
220        spl: avg_spl,
221        phase,
222        coherence,
223        ..Default::default()
224    }
225}
226
227/// Load measurement(s) once and return both the representative response and
228/// the aligned individual responses.
229pub fn load_source_with_individual(
230    source: &MeasurementSource,
231) -> Result<(Curve, Vec<Curve>), Box<dyn Error>> {
232    let curves = load_source_individual(source)?;
233    let representative = if curves.len() == 1 {
234        curves[0].clone()
235    } else {
236        average_curves_power_domain(&curves)
237    };
238    Ok((representative, curves))
239}
240
241/// Load measurement(s) from a source and average if necessary.
242pub fn load_source(source: &MeasurementSource) -> Result<Curve, Box<dyn Error>> {
243    load_source_with_individual(source).map(|(representative, _)| representative)
244}
245
246#[cfg(test)]
247mod tests {
248    use super::super::inline_measurement::InlineMeasurement;
249    use super::super::measurement_ref::MeasurementRef;
250    use super::super::measurement_single::MeasurementSingle;
251    use super::super::measurement_source::MeasurementSource;
252    use super::super::types::MeasurementMultiple;
253    use super::*;
254    use ndarray::Array1;
255
256    fn sample_inline() -> InlineMeasurement {
257        InlineMeasurement {
258            frequencies: vec![100.0, 1000.0, 10000.0],
259            magnitude_db: vec![80.0, 75.0, 70.0],
260            phase_deg: Some(vec![0.0, 45.0, 90.0]),
261            name: Some("inline".to_string()),
262            wav_path: None,
263            csv_path: None,
264        }
265    }
266
267    fn sample_curve(spl_offset: f64) -> Curve {
268        Curve {
269            freq: Array1::from(vec![100.0, 1000.0, 10000.0]),
270            spl: Array1::from(vec![
271                80.0 + spl_offset,
272                75.0 + spl_offset,
273                70.0 + spl_offset,
274            ]),
275            phase: None,
276            ..Default::default()
277        }
278    }
279
280    #[test]
281    fn load_measurement_inline_ok() {
282        let m = MeasurementRef::Inline(sample_inline());
283        let curve = load_measurement(&m).unwrap();
284        assert_eq!(curve.freq.len(), 3);
285        assert_eq!(curve.spl[0], 80.0);
286        assert!(curve.phase.is_some());
287    }
288
289    #[test]
290    fn load_measurement_inline_ignores_mismatched_phase() {
291        let mut inline = sample_inline();
292        inline.phase_deg = Some(vec![0.0, 45.0]);
293        let curve = load_measurement(&MeasurementRef::Inline(inline)).unwrap();
294        assert!(curve.phase.is_none());
295    }
296
297    #[test]
298    fn load_measurement_inline_rejects_mismatched_lengths() {
299        let mut inline = sample_inline();
300        inline.magnitude_db.push(65.0);
301        let result = load_measurement(&MeasurementRef::Inline(inline));
302        assert!(result.is_err());
303        assert!(
304            result
305                .unwrap_err()
306                .to_string()
307                .contains("mismatched lengths")
308        );
309    }
310
311    #[test]
312    fn load_measurement_rejects_single_bin_and_non_finite_inline_data() {
313        for (frequencies, magnitude_db) in [
314            (vec![100.0], vec![80.0]),
315            (vec![100.0, f64::NAN], vec![80.0, 81.0]),
316            (vec![100.0, f64::INFINITY], vec![80.0, 81.0]),
317            (vec![100.0, 1_000.0], vec![80.0, f64::NEG_INFINITY]),
318        ] {
319            let inline = InlineMeasurement {
320                frequencies,
321                magnitude_db,
322                phase_deg: None,
323                name: Some("invalid".to_string()),
324                wav_path: None,
325                csv_path: None,
326            };
327            assert!(load_measurement(&MeasurementRef::Inline(inline)).is_err());
328        }
329    }
330
331    #[test]
332    fn load_source_rejects_invalid_in_memory_curve() {
333        let source = MeasurementSource::InMemory(Curve {
334            freq: Array1::from_vec(vec![100.0, 1_000.0]),
335            spl: Array1::from_vec(vec![80.0]),
336            ..Default::default()
337        });
338        assert!(load_source_individual(&source).is_err());
339        assert!(load_source(&source).is_err());
340    }
341
342    #[test]
343    fn load_measurement_inline_empty_rejects_without_csv_path() {
344        let inline = InlineMeasurement {
345            frequencies: vec![],
346            magnitude_db: vec![],
347            phase_deg: None,
348            name: Some("empty".to_string()),
349            wav_path: None,
350            csv_path: None,
351        };
352        let result = load_measurement(&MeasurementRef::Inline(inline));
353        assert!(result.is_err());
354    }
355
356    #[test]
357    fn load_measurement_named_missing_file_returns_error() {
358        let path = std::path::PathBuf::from("/tmp/does_not_exist_abc123.csv");
359        let m = MeasurementRef::Named {
360            path: path.clone(),
361            name: Some("missing".to_string()),
362        };
363        let error = load_measurement(&m).expect_err("missing measurement must fail");
364        assert!(
365            error.to_string().contains(&path.display().to_string()),
366            "missing path was not preserved in error: {error}"
367        );
368    }
369
370    #[test]
371    fn load_source_single_inline() {
372        let source = MeasurementSource::Single(MeasurementSingle {
373            measurement: MeasurementRef::Inline(sample_inline()),
374            speaker_name: Some("L".to_string()),
375        });
376        let curve = load_source(&source).unwrap();
377        assert_eq!(curve.freq.len(), 3);
378        assert_eq!(source.speaker_name(), Some("L"));
379    }
380
381    #[test]
382    fn load_source_in_memory_returns_clone() {
383        let curve = sample_curve(0.0);
384        let source = MeasurementSource::InMemory(curve.clone());
385        let loaded = load_source(&source).unwrap();
386        assert_eq!(loaded.spl[0], curve.spl[0]);
387    }
388
389    #[test]
390    fn load_source_in_memory_multiple_averages() {
391        let c1 = sample_curve(0.0);
392        let c2 = sample_curve(3.0);
393        let source = MeasurementSource::InMemoryMultiple(vec![c1, c2]);
394        let avg = load_source(&source).unwrap();
395        assert_eq!(avg.freq.len(), 3);
396        // Averaging in power domain: 3 dB difference => average ~81.76 dB at first point
397        let expected =
398            10.0 * ((10.0_f64.powf(80.0 / 10.0) + 10.0_f64.powf(83.0 / 10.0)) / 2.0).log10();
399        assert!((avg.spl[0] - expected).abs() < 1e-6);
400    }
401
402    #[test]
403    fn load_source_with_individual_reuses_aligned_curves() {
404        let first = sample_curve(0.0);
405        let second = sample_curve(3.0);
406        let source = MeasurementSource::InMemoryMultiple(vec![first, second]);
407
408        let (representative, individual) = load_source_with_individual(&source).unwrap();
409
410        assert_eq!(individual.len(), 2);
411        assert_eq!(representative.freq, individual[0].freq);
412        let expected =
413            10.0 * ((10.0_f64.powf(80.0 / 10.0) + 10.0_f64.powf(83.0 / 10.0)) / 2.0).log10();
414        assert!((representative.spl[0] - expected).abs() < 1e-6);
415    }
416
417    #[test]
418    fn load_source_power_average_invalidates_position_specific_phase() {
419        let mut first = sample_curve(0.0);
420        first.phase = Some(Array1::from_vec(vec![10.0, 20.0, 30.0]));
421        first.min_phase = Some(Array1::from_vec(vec![1.0, 2.0, 3.0]));
422        first.excess_phase = Some(Array1::from_vec(vec![9.0, 18.0, 27.0]));
423        first.excess_delay_ms = Some(1.0);
424        let source = MeasurementSource::InMemoryMultiple(vec![first, sample_curve(3.0)]);
425
426        let average = load_source(&source).unwrap();
427
428        assert!(average.phase.is_none());
429        assert!(average.min_phase.is_none());
430        assert!(average.excess_phase.is_none());
431        assert!(average.excess_delay_ms.is_none());
432    }
433
434    #[test]
435    fn load_source_power_average_preserves_circular_phase_when_all_positions_have_phase() {
436        let mut first = sample_curve(0.0);
437        first.phase = Some(Array1::from_vec(vec![170.0, 20.0, -45.0]));
438        let mut second = sample_curve(0.0);
439        second.phase = Some(Array1::from_vec(vec![-170.0, 40.0, -15.0]));
440
441        let source = MeasurementSource::InMemoryMultiple(vec![first, second]);
442        let average = load_source(&source).unwrap();
443        let phase = average
444            .phase
445            .expect("phase must survive all-phase averaging");
446
447        assert!((phase[0].abs() - 180.0).abs() < 1e-9);
448        assert!((phase[1] - 30.0).abs() < 1e-9);
449        assert!((phase[2] + 30.0).abs() < 1e-9);
450    }
451
452    #[test]
453    fn load_source_individual_multiple_interpolates_to_first_grid() {
454        let c1 = sample_curve(0.0);
455        let mut c2 = sample_curve(3.0);
456        // Different grid to exercise interpolation path
457        c2.freq = Array1::from(vec![120.0, 1100.0, 9000.0]);
458        let source = MeasurementSource::Multiple(MeasurementMultiple {
459            measurements: vec![
460                MeasurementRef::Inline(InlineMeasurement {
461                    frequencies: c1.freq.to_vec(),
462                    magnitude_db: c1.spl.to_vec(),
463                    phase_deg: None,
464                    name: None,
465                    wav_path: None,
466                    csv_path: None,
467                }),
468                MeasurementRef::Inline(InlineMeasurement {
469                    frequencies: c2.freq.to_vec(),
470                    magnitude_db: c2.spl.to_vec(),
471                    phase_deg: None,
472                    name: None,
473                    wav_path: None,
474                    csv_path: None,
475                }),
476            ],
477            speaker_name: None,
478        });
479        let curves = load_source_individual(&source).unwrap();
480        assert_eq!(curves.len(), 2);
481        assert_eq!(curves[0].freq[0], 100.0);
482    }
483
484    #[test]
485    fn load_source_individual_in_memory_multiple_interpolates_to_first_grid() {
486        let first = sample_curve(0.0);
487        let second = Curve {
488            freq: Array1::from_vec(vec![120.0, 1100.0, 9000.0]),
489            spl: Array1::from_vec(vec![83.0, 78.0, 73.0]),
490            ..Default::default()
491        };
492        let source = MeasurementSource::InMemoryMultiple(vec![first.clone(), second]);
493
494        let curves = load_source_individual(&source).unwrap();
495
496        assert_eq!(curves.len(), 2);
497        assert_eq!(curves[0].freq, first.freq);
498        assert_eq!(curves[1].freq, first.freq);
499    }
500
501    #[test]
502    fn load_source_rejects_invalid_curve_inside_in_memory_multiple() {
503        let invalid = Curve {
504            freq: Array1::from_vec(vec![100.0, 1000.0]),
505            spl: Array1::from_vec(vec![80.0]),
506            ..Default::default()
507        };
508        let source = MeasurementSource::InMemoryMultiple(vec![sample_curve(0.0), invalid]);
509
510        assert!(load_source_individual(&source).is_err());
511        assert!(load_source(&source).is_err());
512    }
513
514    #[test]
515    fn load_source_individual_empty_multiple_errors() {
516        let source = MeasurementSource::Multiple(MeasurementMultiple {
517            measurements: vec![],
518            speaker_name: None,
519        });
520        assert!(load_source_individual(&source).is_err());
521    }
522
523    #[test]
524    fn load_source_multiple_rejects_partial_measurement_failure() {
525        let source = MeasurementSource::Multiple(MeasurementMultiple {
526            measurements: vec![
527                MeasurementRef::Inline(sample_inline()),
528                MeasurementRef::Path(std::path::PathBuf::from("/tmp/missing.csv")),
529            ],
530            speaker_name: None,
531        });
532        for error in [
533            load_source(&source).unwrap_err(),
534            load_source_individual(&source).unwrap_err(),
535        ] {
536            let message = error.to_string();
537            assert!(message.contains("1 of 2"), "unexpected error: {message}");
538            assert!(
539                message.contains("missing.csv"),
540                "unexpected error: {message}"
541            );
542        }
543    }
544}