1use super::schemas::{i64_at, SignalKind, WindowKind};
5use super::yee::HarmonicSign;
6use super::*;
7use crate::container_10d::crc32c::crc32c_update;
8use core::f64::consts::PI;
9
10pub const IQ_PROFILE: &str = "calibrated_iq_stft_v1";
11pub const IQ_MODEL_URI: &str = "urn:qualia:emf:calibrated_iq_stft_v1";
12pub const IQ_CONVENTION: &str = "I_plus_iQ_exp_minus_iwt";
13pub const STFT_FFT_NORMALIZATION: &str = "forward-unscaled-inverse-1/N";
14pub const MAX_IQ_SAMPLES: u32 = 4096;
15pub const FLAG_LO_PHASE_KNOWN: u32 = 1 << 0;
16
17#[inline]
18pub fn iq_record_stride(sample_count: u32) -> Result<usize, Error> {
19 if !(1..=MAX_IQ_SAMPLES).contains(&sample_count) {
20 return Err(Error::Shape);
21 }
22 let payload_bytes = (sample_count as usize)
23 .checked_mul(16)
24 .ok_or(Error::Overflow)?;
25 let aligned = (payload_bytes + 63) & !63;
26 64usize.checked_add(aligned).ok_or(Error::Overflow)
27}
28
29pub fn iq_record_crc32c(record_bytes: &[u8]) -> Result<u32, Error> {
30 if record_bytes.len() < 80 {
31 return Err(Error::Shape);
32 }
33 let crc = crc32c_update(0xFFFF_FFFF, &record_bytes[..60]);
34 let crc = crc32c_update(crc, &[0u8; 4]);
35 Ok(!crc32c_update(crc, &record_bytes[64..]))
36}
37
38#[derive(Clone, Copy, Debug, PartialEq)]
39pub struct IqHeader {
40 pub first_sample_tick: i64,
41 pub sample_count: u32,
42 pub channel_index: u32,
43 pub centre_hz: f64,
44 pub lo_phase_rad: f64,
45 pub lo_phase_known: bool,
46 pub units_per_sample: f64,
47 pub calibration_metadata_id: u32,
48 pub acquisition_metadata_id: u32,
49 pub flags: u32,
50 pub record_crc32c: u32,
51}
52
53#[derive(Clone, Copy, Debug)]
55pub struct IqPacketView<'a> {
56 pub header: IqHeader,
57 raw_iq_bytes: &'a [u8],
58}
59
60impl<'a> IqPacketView<'a> {
61 pub fn parse(bytes: &'a [u8], valid: bool) -> Result<Option<Self>, Error> {
62 if bytes.len() < 80 || !bytes.len().is_multiple_of(64) {
63 return Err(Error::Shape);
64 }
65 let n = u32_at(bytes, 8);
66 let expected_stride = iq_record_stride(n)?;
67 if bytes.len() != expected_stride {
68 return Err(Error::Shape);
69 }
70 zeros(&bytes[52..60])?;
71 let data_end = 64 + (n as usize) * 16;
72 zeros(&bytes[data_end..])?;
73 let stored_crc = u32_at(bytes, 60);
74 if iq_record_crc32c(bytes)? != stored_crc {
75 return Err(Error::Reserved);
76 }
77 if !valid {
78 zeros(&bytes[16..60])?;
79 zeros(&bytes[64..])?;
80 return Ok(None);
81 }
82 let flags = u32_at(bytes, 48);
83 if flags & !FLAG_LO_PHASE_KNOWN != 0 {
84 return Err(Error::Flags);
85 }
86 finite(bytes, 16, 40)?;
87 let centre_hz = f64_at(bytes, 16);
88 let lo_phase_known = flags & FLAG_LO_PHASE_KNOWN != 0;
89 let lo_phase_rad = if lo_phase_known {
90 f64_at(bytes, 24)
91 } else {
92 zeros(&bytes[24..32])?;
93 0.0
94 };
95 let units_per_sample = f64_at(bytes, 32);
96 if centre_hz < 0.0 || units_per_sample <= 0.0 {
97 return Err(Error::Value);
98 }
99 let raw_iq_bytes = &bytes[64..data_end];
100 for pair in raw_iq_bytes.chunks_exact(16) {
101 if !f64_at(pair, 0).is_finite() || !f64_at(pair, 8).is_finite() {
102 return Err(Error::NonFinite);
103 }
104 }
105 Ok(Some(Self {
106 header: IqHeader {
107 first_sample_tick: i64_at(bytes, 0),
108 sample_count: n,
109 channel_index: u32_at(bytes, 12),
110 centre_hz,
111 lo_phase_rad,
112 lo_phase_known,
113 units_per_sample,
114 calibration_metadata_id: u32_at(bytes, 40),
115 acquisition_metadata_id: u32_at(bytes, 44),
116 flags,
117 record_crc32c: stored_crc,
118 },
119 raw_iq_bytes,
120 }))
121 }
122
123 pub fn raw_sample_bytes(&self) -> &'a [u8] {
125 self.raw_iq_bytes
126 }
127
128 pub fn raw_sample(&self, index: u32) -> Result<(f64, f64), Error> {
129 if index >= self.header.sample_count {
130 return Err(Error::Index);
131 }
132 let at = index as usize * 16;
133 Ok((f64_at(self.raw_iq_bytes, at), f64_at(self.raw_iq_bytes, at + 8)))
134 }
135
136 pub fn calibrated_sample(&self, index: u32) -> Result<(f64, f64), Error> {
137 let (i, q) = self.raw_sample(index)?;
138 let s = self.header.units_per_sample;
139 Ok((i * s, q * s))
140 }
141
142 pub fn extract_interleaved(&self, apply_scale: bool, out: &mut [(f64, f64)]) -> Result<usize, Error> {
143 let n = self.header.sample_count as usize;
144 if out.len() < n {
145 return Err(Error::Shape);
146 }
147 let s = if apply_scale { self.header.units_per_sample } else { 1.0 };
148 for (k, chunk) in self.raw_iq_bytes.chunks_exact(16).enumerate() {
149 out[k] = (f64_at(chunk, 0) * s, f64_at(chunk, 8) * s);
150 }
151 Ok(n)
152 }
153
154 pub fn extract_split(
155 &self,
156 apply_scale: bool,
157 out_i: &mut [f64],
158 out_q: &mut [f64],
159 ) -> Result<usize, Error> {
160 let n = self.header.sample_count as usize;
161 if out_i.len() < n || out_q.len() < n {
162 return Err(Error::Shape);
163 }
164 let s = if apply_scale { self.header.units_per_sample } else { 1.0 };
165 for (k, chunk) in self.raw_iq_bytes.chunks_exact(16).enumerate() {
166 out_i[k] = f64_at(chunk, 0) * s;
167 out_q[k] = f64_at(chunk, 8) * s;
168 }
169 Ok(n)
170 }
171
172 pub fn validate_against_blocks(
175 &self,
176 ext: Block<'_>,
177 acq: Block<'_>,
178 cal: Block<'_>,
179 raw_count_mode: bool,
180 ) -> Result<(), Error> {
181 if acq.schema_type() != 136 || cal.schema_type() != 107 {
182 return Err(Error::Shared(semantics::Error::ReferenceSchema));
183 }
184 if self.header.acquisition_metadata_id != acq.id()
185 || self.header.calibration_metadata_id != cal.id()
186 {
187 return Err(Error::Descriptor);
188 }
189 if scalar32(acq, 6)? != cal.id() {
190 return Err(Error::Descriptor);
191 }
192 if let Some(ext_n) = field(ext, 18) {
193 if u32_at(ext_n.value(), 0) != self.header.sample_count {
194 return Err(Error::Shape);
195 }
196 }
197 if let Some(ch_count) = field(acq, 13) {
198 if self.header.channel_index >= u32_at(ch_count.value(), 0) {
199 return Err(Error::Index);
200 }
201 }
202 if let Some(c_hz) = field(acq, 12) {
203 let expected_fc = f64_at(c_hz.value(), 0);
204 if (expected_fc - self.header.centre_hz).abs() > 1.0e-6 * expected_fc.max(1.0) {
205 return Err(Error::Value);
206 }
207 }
208 let kind = SignalKind::parse(text(required(acq, 4)?)?)?;
209 if kind == SignalKind::ComplexStft {
210 let fft_size = u32_at(required(acq, 9)?.value(), 0);
211 if self.header.sample_count != fft_size {
212 return Err(Error::Shape);
213 }
214 }
215 if !raw_count_mode && text(required(acq, 5)?)? != "counts" {
216 if (self.header.units_per_sample - 1.0).abs() > 1.0e-12 {
218 return Err(Error::Value);
219 }
220 }
221 if let Some(vt) = field(cal, 8) {
222 let from = i64_at(vt.value(), 0);
223 let until = i64_at(vt.value(), 8);
224 let t = self.header.first_sample_tick;
225 if t < from || t >= until {
226 return Err(Error::Time);
227 }
228 }
229 Ok(())
230 }
231}
232
233pub fn encode_iq_packet(
234 header: &IqHeader,
235 iq_samples: &[(f64, f64)],
236 valid: bool,
237 out: &mut [u8],
238) -> Result<usize, Error> {
239 let n = iq_samples.len();
240 let count_u32 = u32::try_from(n).map_err(|_| Error::Shape)?;
241 if count_u32 != header.sample_count {
242 return Err(Error::Shape);
243 }
244 let stride = iq_record_stride(count_u32)?;
245 if out.len() < stride {
246 return Err(Error::Shape);
247 }
248 let buf = &mut out[..stride];
249 buf.fill(0);
250 buf[0..8].copy_from_slice(&header.first_sample_tick.to_le_bytes());
251 buf[8..12].copy_from_slice(&count_u32.to_le_bytes());
252 buf[12..16].copy_from_slice(&header.channel_index.to_le_bytes());
253 if valid {
254 if !header.centre_hz.is_finite()
255 || !header.lo_phase_rad.is_finite()
256 || !header.units_per_sample.is_finite()
257 {
258 return Err(Error::NonFinite);
259 }
260 if header.centre_hz < 0.0 || header.units_per_sample <= 0.0 {
261 return Err(Error::Value);
262 }
263 if header.flags & !FLAG_LO_PHASE_KNOWN != 0 {
264 return Err(Error::Flags);
265 }
266 let lo_phase = if header.flags & FLAG_LO_PHASE_KNOWN != 0 {
267 header.lo_phase_rad
268 } else {
269 if header.lo_phase_rad.to_bits() != 0 {
270 return Err(Error::Reserved);
271 }
272 0.0
273 };
274 for &(i_v, q_v) in iq_samples {
275 if !i_v.is_finite() || !q_v.is_finite() {
276 return Err(Error::NonFinite);
277 }
278 }
279 buf[16..24].copy_from_slice(&header.centre_hz.to_le_bytes());
280 buf[24..32].copy_from_slice(&lo_phase.to_le_bytes());
281 buf[32..40].copy_from_slice(&header.units_per_sample.to_le_bytes());
282 buf[40..44].copy_from_slice(&header.calibration_metadata_id.to_le_bytes());
283 buf[44..48].copy_from_slice(&header.acquisition_metadata_id.to_le_bytes());
284 buf[48..52].copy_from_slice(&header.flags.to_le_bytes());
285 for (idx, &(i_v, q_v)) in iq_samples.iter().enumerate() {
286 let at = 64 + idx * 16;
287 buf[at..at + 8].copy_from_slice(&i_v.to_le_bytes());
288 buf[at + 8..at + 16].copy_from_slice(&q_v.to_le_bytes());
289 }
290 }
291 let crc = iq_record_crc32c(buf)?;
292 buf[60..64].copy_from_slice(&crc.to_le_bytes());
293 Ok(stride)
294}
295
296pub fn reconstruct_rf_real_signal(
299 iq: &[(f64, f64)],
300 sample_rate_hz: f64,
301 carrier_hz: f64,
302 lo_phase_rad: f64,
303 t0_s: f64,
304 sign: HarmonicSign,
305 out_real: &mut [f64],
306) -> Result<(), Error> {
307 if !sample_rate_hz.is_finite()
308 || !carrier_hz.is_finite()
309 || !lo_phase_rad.is_finite()
310 || !t0_s.is_finite()
311 {
312 return Err(Error::NonFinite);
313 }
314 if sample_rate_hz <= 0.0 || carrier_hz < 0.0 {
315 return Err(Error::Value);
316 }
317 if out_real.len() < iq.len() {
318 return Err(Error::Shape);
319 }
320 let s = sign.sign_factor();
321 for (n, &(i_v, q_v)) in iq.iter().enumerate() {
322 if !i_v.is_finite() || !q_v.is_finite() {
323 return Err(Error::NonFinite);
324 }
325 let dt = (n as f64) / sample_rate_hz - t0_s;
326 let phase = s * (2.0 * PI * carrier_hz * dt + lo_phase_rad);
327 let (sin_p, cos_p) = phase.sin_cos();
328 out_real[n] = i_v * cos_p - q_v * sin_p;
329 }
330 Ok(())
331}
332
333pub fn convert_carrier_sign_conjugate(src: &[(f64, f64)], dst: &mut [(f64, f64)]) -> Result<(), Error> {
335 if dst.len() < src.len() {
336 return Err(Error::Shape);
337 }
338 for (idx, &(i_v, q_v)) in src.iter().enumerate() {
339 if !i_v.is_finite() || !q_v.is_finite() {
340 return Err(Error::NonFinite);
341 }
342 dst[idx] = (i_v, -q_v);
343 }
344 Ok(())
345}
346
347#[inline]
348pub fn window_weight(kind: WindowKind, sample_idx: usize, length: usize) -> f64 {
349 match kind {
350 WindowKind::Rectangular => 1.0,
351 WindowKind::Hann => {
352 if length == 0 {
353 0.0
354 } else {
355 0.5 * (1.0 - (2.0 * PI * (sample_idx as f64) / (length as f64)).cos())
356 }
357 }
358 }
359}
360
361pub fn iq_dft_forward_unscaled(
364 samples: &[(f64, f64)],
365 window: Option<WindowKind>,
366 out_bins: &mut [(f64, f64)],
367) -> Result<(), Error> {
368 let n = samples.len();
369 if n == 0 || n > MAX_IQ_SAMPLES as usize || out_bins.len() < n {
370 return Err(Error::Shape);
371 }
372 for &(i_v, q_v) in samples {
373 if !i_v.is_finite() || !q_v.is_finite() {
374 return Err(Error::NonFinite);
375 }
376 }
377 let nf = n as f64;
378 for (k, bin) in out_bins[..n].iter_mut().enumerate() {
379 let mut re = 0.0f64;
380 let mut im = 0.0f64;
381 for (m, &(i_v, q_v)) in samples.iter().enumerate() {
382 let w = window.map_or(1.0, |wk| window_weight(wk, m, n));
383 let angle = -2.0 * PI * ((k * m) as f64) / nf;
384 let (s, c) = angle.sin_cos();
385 let xr = i_v * w;
386 let xi = q_v * w;
387 re += xr * c - xi * s;
388 im += xr * s + xi * c;
389 }
390 *bin = (re, im);
391 }
392 Ok(())
393}
394
395pub fn iq_idft_scaled(bins: &[(f64, f64)], out_samples: &mut [(f64, f64)]) -> Result<(), Error> {
397 let n = bins.len();
398 if n == 0 || n > MAX_IQ_SAMPLES as usize || out_samples.len() < n {
399 return Err(Error::Shape);
400 }
401 for &(re, im) in bins {
402 if !re.is_finite() || !im.is_finite() {
403 return Err(Error::NonFinite);
404 }
405 }
406 let nf = n as f64;
407 for (m, sample) in out_samples[..n].iter_mut().enumerate() {
408 let mut re = 0.0f64;
409 let mut im = 0.0f64;
410 for (k, &(br, bi)) in bins.iter().enumerate() {
411 let angle = 2.0 * PI * ((k * m) as f64) / nf;
412 let (s, c) = angle.sin_cos();
413 re += br * c - bi * s;
414 im += br * s + bi * c;
415 }
416 *sample = (re / nf, im / nf);
417 }
418 Ok(())
419}
420
421pub fn signed_baseband_offset_hz(
423 bin_index: usize,
424 fft_size: usize,
425 sample_rate_hz: f64,
426) -> Result<f64, Error> {
427 if !sample_rate_hz.is_finite() {
428 return Err(Error::NonFinite);
429 }
430 if fft_size == 0 || bin_index >= fft_size || sample_rate_hz <= 0.0 {
431 return Err(Error::Shape);
432 }
433 let half = fft_size / 2;
434 let signed_k = if fft_size % 2 == 0 {
435 if bin_index < half {
436 bin_index as isize
437 } else {
438 bin_index as isize - fft_size as isize
439 }
440 } else if bin_index <= half {
441 bin_index as isize
442 } else {
443 bin_index as isize - fft_size as isize
444 };
445 Ok((signed_k as f64) * (sample_rate_hz / fft_size as f64))
446}
447
448pub fn fft_bins_to_ascending_physical(
451 bins: &[(f64, f64)],
452 sample_rate_hz: f64,
453 centre_hz: f64,
454 sign: HarmonicSign,
455 out_freqs_hz: &mut [f64],
456 out_bins: &mut [(f64, f64)],
457) -> Result<(), Error> {
458 let n = bins.len();
459 if n == 0 || out_freqs_hz.len() < n || out_bins.len() < n {
460 return Err(Error::Shape);
461 }
462 if !centre_hz.is_finite() || !sample_rate_hz.is_finite() {
463 return Err(Error::NonFinite);
464 }
465 if centre_hz <= 0.0 || sample_rate_hz <= 0.0 {
466 return Err(Error::Value);
467 }
468 let s = sign.sign_factor();
469 let neg_start = n.div_ceil(2);
470 let pos_top = (n - 1) / 2;
471 for out_idx in 0..n {
473 let src_bin = match sign {
474 HarmonicSign::PlusIwt => (neg_start + out_idx) % n,
475 HarmonicSign::MinusIwt => (pos_top + n - out_idx) % n,
476 };
477 let off = signed_baseband_offset_hz(src_bin, n, sample_rate_hz)?;
478 let f_phys = centre_hz + s * off;
479 if f_phys <= 0.0 {
480 return Err(Error::Value);
481 }
482 if out_idx > 0 && f_phys <= out_freqs_hz[out_idx - 1] {
483 return Err(Error::Value);
484 }
485 out_freqs_hz[out_idx] = f_phys;
486 out_bins[out_idx] = bins[src_bin];
487 }
488 Ok(())
489}
490
491pub fn check_complex_nyquist_band(
494 sample_rate_hz: f64,
495 occupied_bandwidth_hz: f64,
496 bandpass_admitted: bool,
497) -> Result<(), Error> {
498 if !sample_rate_hz.is_finite() || !occupied_bandwidth_hz.is_finite() {
499 return Err(Error::NonFinite);
500 }
501 if sample_rate_hz <= 0.0 || occupied_bandwidth_hz < 0.0 {
502 return Err(Error::Value);
503 }
504 if !bandpass_admitted && occupied_bandwidth_hz > sample_rate_hz {
505 return Err(Error::Value);
506 }
507 Ok(())
508}