Skip to main content

qualia_core_db/audio/qac/profiles/
dsp_bridge.rs

1//! Bridges between QAC domain profile views (`0x0000..=0x0001`, `0x0003`, `0x0102..=0x0107`)
2//! and `audio::qac::spatial_dsp` + `audio::qac::numerical` (`[GAP-026]`).
3
4use crate::audio::qac::numerical::{
5    compute_tis_soft_tissue, compute_utd_wedge_diffraction,
6    compute_zwicker_specific_and_total_loudness_into, solve_biot_poroelastic_dispersion,
7    solve_pennes_bioheat_steady_state, BiotPoroelasticParams, BiotWaveDispersion,
8    PennesBioheatParams, PennesBioheatResult, ThermalIndexEstimate, ZwickerLoudnessReport,
9    ZWICKER_BARK_BANDS,
10};
11use crate::audio::qac::spatial_dsp::{
12    convolve_stereo_hrir_with_additional_delays_into, decode_hoa_stream_to_speakers_into,
13    extract_mel_mfcc_frame_into, measure_bs1770_integrated_loudness, Bs1770ChannelRole,
14    Bs1770LoudnessReading, HoaNormalization as DspHoaNormalization, HoaOrder, HoaWignerRotation,
15};
16
17use super::{
18    synthesize_modal_sample, ElasticStressView, HapticDocumentView, HoaNormalization, HoaOrdering,
19    HoaTemporalView, HrirDocumentView, ModalBankView, PerceptualDocumentView, PerceptualScale,
20    PressureVelocityView, ProfileError, RayContributionView, UltrasoundBeamSummaryRecord,
21    UltrasoundDocumentView,
22};
23
24fn map_hoa_order(order: u8) -> Result<HoaOrder, ProfileError> {
25    match order {
26        0 => Ok(HoaOrder::Order0),
27        1 => Ok(HoaOrder::Order1),
28        2 => Ok(HoaOrder::Order2),
29        3 => Ok(HoaOrder::Order3),
30        _ => Err(ProfileError::InvalidMetadata("unsupported HOA order")),
31    }
32}
33
34/// Rotates and decodes a `0x0102` `HoaTemporalView` (`ACN`/`SN3D` or `N3D`) via `spatial_dsp`.
35pub fn bridge_hoa_view_rotate_and_decode(
36    view: &HoaTemporalView<'_>,
37    quat_xyzw: [f64; 4],
38    speaker_directions_xyz: &[[f32; 3]],
39    apply_max_re: bool,
40) -> Result<Vec<f32>, ProfileError> {
41    if view.ordering != HoaOrdering::Acn {
42        return Err(ProfileError::InvalidMetadata("spatial_dsp HOA bridge requires ACN ordering"));
43    }
44    let order = map_hoa_order(view.order)?;
45    let norm = match view.normalization {
46        HoaNormalization::Sn3d => DspHoaNormalization::Sn3d,
47        HoaNormalization::N3d => DspHoaNormalization::N3d,
48        HoaNormalization::MaxN => {
49            return Err(ProfileError::InvalidMetadata("MaxN not supported in ACN stream bridge"));
50        }
51    };
52    let wigner = HoaWignerRotation::from_quaternion_xyzw(quat_xyzw)
53        .map_err(|_| ProfileError::InvalidQuaternion)?;
54    let n_ch = view.chunk.channels();
55    let n_frames = view.chunk.frame_count();
56    let mut in_stream = vec![0.0f32; n_frames * n_ch];
57    for f in 0..n_frames {
58        view.chunk
59            .read_frame(f, &mut in_stream[f * n_ch..(f + 1) * n_ch])?;
60    }
61    let mut rot_stream = vec![0.0f32; in_stream.len()];
62    wigner
63        .apply_stream_into_f32(order, &in_stream, &mut rot_stream)
64        .map_err(|_| ProfileError::InvalidMetadata("Wigner HOA stream rotation failed"))?;
65    let mut out_speakers = vec![0.0f32; n_frames * speaker_directions_xyz.len()];
66    decode_hoa_stream_to_speakers_into(
67        order,
68        norm,
69        &rot_stream,
70        speaker_directions_xyz,
71        apply_max_re,
72        &mut out_speakers,
73    )
74    .map_err(|_| ProfileError::InvalidMetadata("HOA speaker decode failed"))?;
75    Ok(out_speakers)
76}
77
78/// Convolves a `0x0103` `HrirDocumentView` stereo measurement with a mono `f32` signal via `spatial_dsp`.
79pub fn bridge_hrir_view_binaural_convolve(
80    doc: &HrirDocumentView<'_>,
81    measurement_idx: u32,
82    mono_signal: &[f32],
83) -> Result<(Vec<f32>, Vec<f32>), ProfileError> {
84    let m_idx = measurement_idx as usize;
85    if doc.chunk.receivers() < 2 || m_idx >= doc.chunk.measurements() {
86        return Err(ProfileError::OutOfBoundsIndex("HRIR measurement/receiver index"));
87    }
88    let taps = doc.chunk.taps();
89    let mut left_ir = vec![0.0f32; taps];
90    let mut right_ir = vec![0.0f32; taps];
91    doc.chunk.read_impulse(m_idx, 0, &mut left_ir)?;
92    doc.chunk.read_impulse(m_idx, 1, &mut right_ir)?;
93    let delays_lr = match &doc.delays_samples {
94        Some(d) if d.len() >= (m_idx + 1) * 2 => [
95            d[m_idx * 2].max(0.0).round() as usize,
96            d[m_idx * 2 + 1].max(0.0).round() as usize,
97        ],
98        _ => [0, 0],
99    };
100    let out_len = mono_signal.len() + taps + delays_lr[0].max(delays_lr[1]);
101    let mut out_l = vec![0.0f32; out_len];
102    let mut out_r = vec![0.0f32; out_len];
103    let (nl, nr) = convolve_stereo_hrir_with_additional_delays_into(
104        mono_signal,
105        &left_ir,
106        &right_ir,
107        delays_lr,
108        &mut out_l,
109        &mut out_r,
110    )
111    .map_err(|_| ProfileError::InvalidMetadata("stereo HRIR convolution failed"))?;
112    out_l.truncate(nl);
113    out_r.truncate(nr);
114    Ok((out_l, out_r))
115}
116
117/// Evaluates ISO 532-1 Zwicker 24-Bark loudness (`ZwickerLoudnessReport`) from a `0x0105` `PerceptualDocumentView`.
118pub fn bridge_perceptual_view_zwicker_sones(
119    doc: &PerceptualDocumentView<'_>,
120    frame_idx: usize,
121) -> Result<(ZwickerLoudnessReport, [f64; ZWICKER_BARK_BANDS]), ProfileError> {
122    if doc.chunk.feature_count() != ZWICKER_BARK_BANDS || frame_idx >= doc.chunk.frame_count() {
123        return Err(ProfileError::InvalidPayloadLength);
124    }
125    let mut frame = [0.0f32; ZWICKER_BARK_BANDS];
126    doc.chunk.read_frame(frame_idx, &mut frame)?;
127    let mut levels_db = [0.0f64; ZWICKER_BARK_BANDS];
128    for (i, &val) in frame.iter().enumerate() {
129        let v = f64::from(val);
130        levels_db[i] = match doc.scale {
131            PerceptualScale::DbSpl => v,
132            _ => 10.0 * v.max(1e-12).log10(),
133        };
134    }
135    let mut specific = [0.0f64; ZWICKER_BARK_BANDS];
136    let report = compute_zwicker_specific_and_total_loudness_into(&levels_db, &mut specific)
137        .map_err(|_| ProfileError::InvalidMetadata("Zwicker loudness failed"))?;
138    Ok((report, specific))
139}
140
141/// Synthesizes a `0x0104` `ModalBankView` into PCM and extracts BS.1770 loudness and Mel/MFCC features.
142pub fn bridge_modal_view_to_bs1770_and_mfcc(
143    view: &ModalBankView<'_>,
144    dof_index: usize,
145    sample_rate_hz: u32,
146    num_samples: usize,
147) -> Result<(Bs1770LoudnessReading, Vec<f32>, Vec<f32>), ProfileError> {
148    let mut modes = Vec::with_capacity(view.records.len());
149    for i in 0..view.records.len() {
150        modes.push(view.records.get(i)?);
151    }
152    let sr = sample_rate_hz as f64;
153    let mut pcm = vec![0.0f32; num_samples];
154    for (n, s) in pcm.iter_mut().enumerate() {
155        *s = synthesize_modal_sample(
156            &modes,
157            None,
158            &view.mode_shapes,
159            view.shape_dofs,
160            dof_index,
161            &view.excitations,
162            (n as f64) / sr,
163        )? as f32;
164    }
165    let mut blk_scratch = vec![0.0f64; 64];
166    let loudness = measure_bs1770_integrated_loudness(
167        &pcm,
168        &[Bs1770ChannelRole::FrontOrCenter],
169        sample_rate_hz,
170        &mut blk_scratch,
171    )
172    .map_err(|_| ProfileError::InvalidMetadata("BS.1770 loudness failed"))?;
173    let n_fft = 64usize;
174    let n_bins = n_fft / 2 + 1;
175    let n_mel = 8usize;
176    let mut fb = vec![0.0f32; n_mel * n_bins];
177    for m in 0..n_mel {
178        fb[m * n_bins + (m + 1).min(n_bins - 1)] = 1.0;
179    }
180    let mut stft_scratch = vec![0.0f32; n_fft * 2];
181    let mut pwr_scratch = vec![0.0f32; n_bins];
182    let mut mel_out = vec![0.0f32; n_mel];
183    let mut mfcc_out = vec![0.0f32; n_mel];
184    extract_mel_mfcc_frame_into(
185        &pcm[..n_fft.min(pcm.len())],
186        n_mel,
187        &fb,
188        &mut stft_scratch,
189        &mut pwr_scratch,
190        &mut mel_out,
191        &mut mfcc_out,
192    )
193    .map_err(|_| ProfileError::InvalidMetadata("Mel/MFCC extraction failed"))?;
194    Ok((loudness, mel_out, mfcc_out))
195}
196
197/// Bridges `0x0000` `PressureVelocityView` and `0x0001` `ElasticStressView` with Biot poroelasticity.
198pub fn bridge_continuum_views_biot_poroelastic(
199    pv_view: &PressureVelocityView<'_>,
200    el_view: &ElasticStressView<'_>,
201    params: &BiotPoroelasticParams,
202    omega_rad_s: f64,
203) -> Result<(BiotWaveDispersion, f64), ProfileError> {
204    if pv_view.records.is_empty() || el_view.records.is_empty() {
205        return Err(ProfileError::InvalidPayloadLength);
206    }
207    let disp = solve_biot_poroelastic_dispersion(params, omega_rad_s)
208        .map_err(|_| ProfileError::InvalidMetadata("Biot dispersion failed"))?;
209    let p_fluid = f64::from(pv_view.records.get(0)?.pressure_pa);
210    let p_solid = el_view.records.get(0)?.stress().hydrostatic_pressure_pa();
211    Ok((disp, p_fluid + params.biot_willis_alpha * p_solid))
212}
213
214/// Bridges `0x0003` `RayContributionView`, `0x0106` `HapticDocumentView`, and `0x0107` `UltrasoundDocumentView`
215/// with UTD wedge diffraction, Pennes bioheat steady-state temperature rise, and AIUM/NEMA UD 3 TIS.
216pub fn bridge_ray_haptic_ultrasound_numerical(
217    ray_view: &RayContributionView<'_>,
218    haptic_view: &HapticDocumentView<'_>,
219    us_view: &UltrasoundDocumentView<'_>,
220    sound_speed_m_s: f64,
221) -> Result<(f64, f64, PennesBioheatResult, ThermalIndexEstimate), ProfileError> {
222    if ray_view.records.is_empty() || haptic_view.records.is_empty() || us_view.records.is_empty() {
223        return Err(ProfileError::InvalidPayloadLength);
224    }
225    let r0 = ray_view.records.get(0)?;
226    let f0 = f64::from(*ray_view.band_centers_hz.first().unwrap_or(&1000.0));
227    let k = 2.0 * core::f64::consts::PI * f0 / sound_speed_m_s;
228    let r_dist = f64::from(r0.distance_m).max(0.5);
229    let d_utd = compute_utd_wedge_diffraction(1.5, k, r_dist, r_dist, 0.4, 2.1, 1.0, 1.0)
230        .map_err(|_| ProfileError::InvalidMetadata("UTD diffraction failed"))?;
231    let h0 = haptic_view.records.get(0)?;
232    let normal_stress_pa = f64::from(h0.force_local_xyz_n[2].abs()) / f64::from(h0.contact_area_m2);
233    let u0: UltrasoundBeamSummaryRecord = us_view.records.get(0)?;
234    let f_mhz = (f64::from(u0.center_frequency_hz) * 1.0e-6).max(0.1);
235    let bio = solve_pennes_bioheat_steady_state(&PennesBioheatParams {
236        absorption_np_per_m_mhz: 5.0,
237        frequency_mhz: f_mhz,
238        i_spta_w_per_m2: f64::from(u0.intensity_ispta_w_m2),
239        metabolic_heat_w_per_m3: 400.0,
240        blood_perfusion_rate_s1: 0.008,
241        blood_density_kg_m3: 1060.0,
242        blood_specific_heat_j_kg_k: 3600.0,
243        tissue_thermal_conductivity_w_m_k: 0.5,
244    })
245    .map_err(|_| ProfileError::InvalidMetadata("Pennes bioheat failed"))?;
246    let tis = compute_tis_soft_tissue(105.0, f_mhz)
247        .map_err(|_| ProfileError::InvalidMetadata("TIS failed"))?;
248    Ok((d_utd.abs(), normal_stress_pa, bio, tis))
249}