1use super::envelope::*;
8use super::types::*;
9
10#[path = "hrir_helpers.rs"]
11mod hrir_helpers;
12pub use hrir_helpers::*;
13
14#[derive(Debug, Clone)]
16pub struct HrirWriteSpec<'a> {
17 pub representation: &'a str, pub taps: u32,
19 pub receivers: u32,
20 pub measurements: u32,
21 pub impulse_sample_rate: RationalRate,
22 pub delay_reference: &'a str,
23 pub sofa_convention: Option<&'a str>,
24 pub units: &'a str,
25 pub delays_samples: Option<&'a [f64]>,
26 pub source_positions_xyz: Option<&'a [[f32; 3]]>,
27 pub receiver_positions_xyz: Option<&'a [[f32; 3]]>,
28 pub measurement_cadence: Option<(&'a ClockSpec, RationalRate)>,
30}
31
32pub struct HrirChunkView<'a> {
34 bytes: &'a [u8],
35 taps: usize,
36 receivers: usize,
37 measurements: usize,
38 mask: Option<&'a [u8]>,
39}
40
41impl<'a> HrirChunkView<'a> {
42 pub fn taps(&self) -> usize {
43 self.taps
44 }
45
46 pub fn receivers(&self) -> usize {
47 self.receivers
48 }
49
50 pub fn measurements(&self) -> usize {
51 self.measurements
52 }
53
54 pub fn record_count(&self) -> usize {
55 self.measurements * self.receivers
56 }
57
58 pub fn read_impulse(
60 &self,
61 measurement: usize,
62 receiver: usize,
63 out_taps: &mut [f32],
64 ) -> Result<(), ProfileError> {
65 if measurement >= self.measurements || receiver >= self.receivers {
66 return Err(ProfileError::OutOfBoundsIndex("hrir measurement/receiver"));
67 }
68 if out_taps.len() != self.taps {
69 return Err(ProfileError::InvalidPayloadLength);
70 }
71 let rec_idx = measurement * self.receivers + receiver;
72 let stride = self.taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
73 let start = rec_idx.checked_mul(stride).ok_or(ProfileError::Overflow)?;
74 let end = start.checked_add(stride).ok_or(ProfileError::Overflow)?;
75 let slice = self
76 .bytes
77 .get(start..end)
78 .ok_or(ProfileError::OutOfBoundsIndex("hrir slice"))?;
79 let ext_valid = self.mask.map_or(true, |m| m[rec_idx] != 0);
80 for (i, dst) in out_taps.iter_mut().enumerate() {
81 let v = read_f32_finite(slice, i * 4)?;
82 require_zero_when_masked(ext_valid, v)?;
83 *dst = v;
84 }
85 Ok(())
86 }
87}
88
89pub fn tap_time_seconds(
92 delay_samples: f64,
93 tap_index: u32,
94 impulse_sample_rate: RationalRate,
95) -> Result<f64, ProfileError> {
96 if !delay_samples.is_finite() {
97 return Err(ProfileError::NonFiniteFloat);
98 }
99 let dt = (impulse_sample_rate.den as f64) / (impulse_sample_rate.num as f64);
100 Ok((delay_samples + f64::from(tap_index)) * dt)
101}
102
103pub fn sample_delayed_impulse(taps: &[f32], delay_samples: f64, sample_idx: f64) -> f64 {
105 let shifted = sample_idx - delay_samples;
106 if shifted < 0.0 || shifted > (taps.len().saturating_sub(1)) as f64 {
107 return 0.0;
108 }
109 let i0 = shifted.floor() as usize;
110 let frac = shifted - (i0 as f64);
111 if i0 + 1 < taps.len() {
112 (1.0 - frac) * f64::from(taps[i0]) + frac * f64::from(taps[i0 + 1])
113 } else {
114 f64::from(taps[i0])
115 }
116}
117
118pub fn convolve_hrir(input: &[f32], taps: &[f32], out: &mut [f32]) -> Result<(), ProfileError> {
120 if out.len() != input.len() {
121 return Err(ProfileError::InvalidPayloadLength);
122 }
123 for (n, slot) in out.iter_mut().enumerate() {
124 let mut acc = 0.0f64;
125 for (k, &h) in taps.iter().enumerate() {
126 if n >= k {
127 acc += f64::from(input[n - k]) * f64::from(h);
128 }
129 }
130 *slot = acc as f32;
131 }
132 Ok(())
133}
134
135pub fn write_hrir_qac(
137 impulses: &[f32],
138 spec: &HrirWriteSpec<'_>,
139 frame: &FrameSpec<'_>,
140 provenance: &ProvenanceSpec<'_>,
141 limits: ProfileLimits,
142) -> Result<Vec<u8>, ProfileError> {
143 if spec.representation != "HRIR" && spec.representation != "RIR" {
144 return Err(ProfileError::InvalidMetadata("representation must be HRIR or RIR"));
145 }
146 if spec.delay_reference != BASE_DELAY_REFERENCE && spec.delay_reference != LEGACY_DELAY_REFERENCE {
147 return Err(ProfileError::InvalidMetadata("invalid delay_reference"));
148 }
149 if spec.taps == 0 || spec.receivers == 0 || spec.measurements == 0 {
150 return Err(ProfileError::InvalidMetadata("taps/receivers/measurements must be > 0"));
151 }
152 if spec.taps > limits.max_taps || spec.receivers > limits.max_channels {
153 return Err(ProfileError::LimitExceeded);
154 }
155 let rec_count = u64::from(spec.measurements)
156 .checked_mul(u64::from(spec.receivers))
157 .ok_or(ProfileError::Overflow)?;
158 let expected_floats = rec_count
159 .checked_mul(u64::from(spec.taps))
160 .ok_or(ProfileError::Overflow)?;
161 if impulses.len() as u64 != expected_floats {
162 return Err(ProfileError::InvalidPayloadLength);
163 }
164 let stride = spec.taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
165 let mut main_payload = vec![0u8; impulses.len() * 4];
166 write_f32_slice(&mut main_payload, 0, impulses)?;
167
168 let mut meta = MetadataBuilder::new();
169 let has_time = spec.measurement_cadence.is_some();
170 if let Some((clk, _)) = spec.measurement_cadence {
171 meta.push_clock(1, clk)?;
172 }
173 meta.push_frame(2, frame)?;
174 meta.push_provenance(3, provenance)?;
175
176 let mut entries = Vec::new();
177 let stream_id = if has_time { 1 } else { 0 };
178 let main_flags = if has_time { 3 } else { 1 };
179 let main_desc_id = 6u32;
180
181 let mut s204_fields = vec![
185 OwnedField::crit(1, OwnedValue::Utf8(spec.representation.to_owned())),
186 OwnedField::crit(8, OwnedValue::U32(vec![spec.taps])),
187 OwnedField::crit(9, OwnedValue::U32(vec![spec.receivers])),
188 OwnedField::crit(10, OwnedValue::U32(vec![spec.measurements])),
189 OwnedField::opt(13, OwnedValue::MetadataRefs(vec![2])),
190 OwnedField::crit(17, OwnedValue::U64(vec![spec.impulse_sample_rate.num])),
191 OwnedField::crit(18, OwnedValue::U64(vec![spec.impulse_sample_rate.den])),
192 OwnedField::crit(19, OwnedValue::Utf8(spec.delay_reference.to_owned())),
193 ];
194 if let Some(conv) = spec.sofa_convention {
195 validate_identifier_str(conv, "sofa_convention")?;
196 s204_fields.push(OwnedField::opt(12, OwnedValue::Utf8(conv.to_owned())));
197 }
198
199 let mut aux_desc_id = 7u32;
200 let mut next_entry_idx = 2u32;
201 let mut aux_entries = Vec::new();
202
203 if let Some(rx_pos) = spec.receiver_positions_xyz {
204 if rx_pos.len() != spec.receivers as usize {
205 return Err(ProfileError::InvalidPayloadLength);
206 }
207 let e = push_aux_f32_vec3_entry(&mut meta, aux_desc_id, 3, "receiver-positions", "m", rx_pos)?;
208 s204_fields.push(OwnedField::opt(5, OwnedValue::EntryRefs(vec![next_entry_idx])));
209 aux_entries.push(e);
210 aux_desc_id += 1;
211 next_entry_idx += 1;
212 }
213 if let Some(tx_pos) = spec.source_positions_xyz {
214 if tx_pos.len() != spec.measurements as usize {
215 return Err(ProfileError::InvalidPayloadLength);
216 }
217 let e = push_aux_f32_vec3_entry(&mut meta, aux_desc_id, 3, "source-positions", "m", tx_pos)?;
218 s204_fields.push(OwnedField::opt(6, OwnedValue::EntryRefs(vec![next_entry_idx])));
219 aux_entries.push(e);
220 aux_desc_id += 1;
221 next_entry_idx += 1;
222 }
223 if let Some(delays) = spec.delays_samples {
224 if delays.len() as u64 != rec_count {
225 return Err(ProfileError::InvalidPayloadLength);
226 }
227 let e = push_aux_f64_scalar_entry(&mut meta, aux_desc_id, 3, "delays-samples", "1", delays)?;
228 s204_fields.push(OwnedField::opt(7, OwnedValue::EntryRefs(vec![next_entry_idx])));
229 aux_entries.push(e);
230 }
231
232 meta.push_block(OwnedBlock {
233 id: 4,
234 schema_type: 204,
235 revision: 1,
236 critical: true,
237 fields: s204_fields,
238 })?;
239
240 let shape = [
241 u64::from(spec.measurements),
242 u64::from(spec.receivers),
243 u64::from(spec.taps),
244 ];
245 meta.push_model_grid(
246 5,
247 &ModelGridSpec {
248 model_uri: "urn:qac:model:hrir-fir:v1",
249 model_version: "1",
250 discretization: Some("discrete-fir-taps"),
251 component_offsets_xyz: &[],
252 component_time_offset_num: &[],
253 component_time_offset_den: &[],
254 timestep: None,
255 tolerance_abs: None,
256 tolerance_rel: None,
257 tensor_shape: &shape,
258 component_names: "hrir_tap",
259 },
260 )?;
261
262 let ext = [4u32, 5u32];
263 let (clock_id, sample_rate) = if let Some((_, rate)) = spec.measurement_cadence {
264 (Some(1), Some(rate))
265 } else {
266 (None, None)
267 };
268 meta.push_descriptor(
269 main_desc_id,
270 &DescriptorSpec {
271 clock_id,
272 frame_id: Some(2),
273 provenance_id: 3,
274 medium_id: None,
275 transform_id: None,
276 calibration_id: None,
277 quantity: "impulse-response",
278 units: spec.units,
279 channels: Some(spec.receivers),
280 layout: Some("measurement-receiver-tap"),
281 scalar: Some(AuxScalar::F32),
282 model_uri: "urn:qac:mode:0x0103:v1",
283 sample_rate,
284 valid_record_count: None,
285 validity_mask_entry: None,
286 source_entries: &[],
287 extension_metadata: &ext,
288 },
289 )?;
290
291 entries.push(OwnedEntry {
292 mode: MODE_HRIR_IMPULSE,
293 flags: main_flags,
294 stream_id,
295 frame_id: 2,
296 start_tick: 0,
297 time_count: if has_time { u64::from(spec.measurements) } else { 0 },
298 spatial_key: 0,
299 record_count: rec_count,
300 stride,
301 descriptor_id: main_desc_id,
302 payload: main_payload,
303 });
304 for mut aux in aux_entries {
308 aux.stream_id = stream_id;
309 entries.push(aux);
310 }
311 assemble_qac_v1(&meta, &entries, limits)
312}
313
314pub struct HrirDocumentView<'a> {
315 pub chunk: HrirChunkView<'a>,
316 pub representation: &'a str,
317 pub impulse_sample_rate: RationalRate,
318 pub delay_reference: &'a str,
319 pub delays_samples: Option<Vec<f64>>,
320 pub legacy_original_bytes: Option<&'a [u8]>,
321}
322
323pub fn read_hrir_qac<'a>(
325 bytes: &'a [u8],
326 entry_index: u32,
327 limits: ProfileLimits,
328) -> Result<HrirDocumentView<'a>, ProfileError> {
329 let env = AdmittedEnvelope::open_alloc(bytes, limits)?;
330 let e = env.entry(entry_index)?;
331 if e.mode() != MODE_HRIR_IMPULSE {
332 return Err(ProfileError::InvalidMode(e.mode()));
333 }
334 let desc = env.descriptor_for_entry(e)?;
335 let s204 = env
336 .extension_block(desc, 204)?
337 .ok_or(ProfileError::MissingRequiredSchema(204))?;
338 let repr = field_str(field_req(s204, 1)?)?;
339 if repr != "HRIR" && repr != "RIR" {
340 return Err(ProfileError::InvalidMetadata("Schema 204 representation must be HRIR or RIR"));
341 }
342 let taps = field_u32(field_req(s204, 8)?)?;
343 let receivers = field_u32(field_req(s204, 9)?)?;
344 let measurements = field_u32(field_req(s204, 10)?)?;
345 if taps == 0 || receivers == 0 || measurements == 0 || taps > limits.max_taps {
346 return Err(ProfileError::InvalidMetadata("invalid HRIR dimensions"));
347 }
348 let impulse_sample_rate = RationalRate::new(
349 field_u64(field_req(s204, 17)?)?,
350 field_u64(field_req(s204, 18)?)?,
351 )?;
352 let delay_reference = field_str(field_req(s204, 19)?)?;
353 if delay_reference == LEGACY_DELAY_REFERENCE && env.extension_block(desc, 209)?.is_none() {
354 return Err(ProfileError::MissingRequiredSchema(209));
355 }
356 let expected_rec = u64::from(measurements)
357 .checked_mul(u64::from(receivers))
358 .ok_or(ProfileError::Overflow)?;
359 let expected_stride = taps.checked_mul(4).ok_or(ProfileError::Overflow)?;
360 if e.record_count() != expected_rec || e.stride() != expected_stride {
361 return Err(ProfileError::InvalidStride {
362 expected: expected_stride,
363 actual: e.stride(),
364 });
365 }
366 let payload = env.verify_chunk(entry_index)?;
367 let mask = env.read_validity_mask(desc, expected_rec)?;
368
369 let delays_samples = if let Some(df) = field_opt(s204, 7) {
370 let d_idx = field_u32(df)?;
371 let d_bytes = env.verify_chunk(d_idx)?;
372 if d_bytes.len() as u64 != expected_rec * 8 {
373 return Err(ProfileError::InvalidPayloadLength);
374 }
375 let mut out = Vec::with_capacity(expected_rec as usize);
376 for c in d_bytes.chunks_exact(8) {
377 let v = f64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7]]);
378 out.push(require_finite_f64(v)?);
379 }
380 Some(out)
381 } else {
382 None
383 };
384
385 let legacy_original_bytes = if let Some(s209) = env.extension_block(desc, 209)? {
386 let orig_idx = field_u32(field_req(s209, 3)?)?;
387 let orig_digest = field_bytes32(field_req(s209, 4)?)?;
388 let orig_bytes = env.verify_chunk(orig_idx)?;
389 if blake3::hash(orig_bytes).as_bytes() != &orig_digest {
390 return Err(ProfileError::LegacyFormat("Schema 209 original_digest mismatch"));
391 }
392 Some(orig_bytes)
393 } else {
394 None
395 };
396
397 let chunk = HrirChunkView {
398 bytes: payload,
399 taps: taps as usize,
400 receivers: receivers as usize,
401 measurements: measurements as usize,
402 mask,
403 };
404 let mut tmp = vec![0.0f32; taps as usize];
405 for m in 0..measurements as usize {
406 for r in 0..receivers as usize {
407 chunk.read_impulse(m, r, &mut tmp)?;
408 }
409 }
410 Ok(HrirDocumentView {
411 chunk,
412 representation: repr,
413 impulse_sample_rate,
414 delay_reference,
415 delays_samples,
416 legacy_original_bytes,
417 })
418}