1use super::spectrum::{
6 density_coordinate_jacobian, DensityCoordinate, Quantity, SampleSemantics,
7};
8use super::*;
9
10pub const MUELLER_PROFILE: &str = "mueller_scattering_v1";
11pub const MUELLER_MODEL_URI: &str = "urn:qualia:emf:mueller_scattering_v1";
12
13pub const BAND_COUNT_24: usize = 24;
14pub const BAND_COUNT_28: usize = 28;
15
16#[derive(Clone, Copy, Debug, PartialEq)]
17pub enum SpectralPrecisionProfile {
18 Float64,
19 Float32,
20 QuantizedScaledI32 { scale: f64, offset: f64 },
21}
22
23impl SpectralPrecisionProfile {
24 pub fn encode_value(self, physical: f64) -> Result<f64, Error> {
25 if !physical.is_finite() {
26 return Err(Error::NonFinite);
27 }
28 match self {
29 Self::Float64 => Ok(physical),
30 Self::Float32 => Ok(f64::from(physical as f32)),
31 Self::QuantizedScaledI32 { scale, offset } => {
32 if !scale.is_finite() || !offset.is_finite() || scale <= 0.0 {
33 return Err(Error::Value);
34 }
35 let raw = ((physical - offset) / scale).round();
36 if !raw.is_finite() || raw < i32::MIN as f64 || raw > i32::MAX as f64 {
37 return Err(Error::Overflow);
38 }
39 Ok((raw as i32) as f64 * scale + offset)
40 }
41 }
42 }
43}
44
45pub fn validate_band_edges(edges: &[f64]) -> Result<usize, Error> {
47 if edges.len() < 2 || edges.len() - 1 > 4096 {
48 return Err(Error::Shape);
49 }
50 let mut prev = 0.0f64;
51 for &v in edges {
52 if !v.is_finite() {
53 return Err(Error::NonFinite);
54 }
55 if v <= 0.0 || v <= prev {
56 return Err(Error::Value);
57 }
58 prev = v;
59 }
60 Ok(edges.len() - 1)
61}
62
63pub fn build_log_band_edges(min_coord: f64, max_coord: f64, out_edges: &mut [f64]) -> Result<usize, Error> {
65 if !min_coord.is_finite() || !max_coord.is_finite() {
66 return Err(Error::NonFinite);
67 }
68 if min_coord <= 0.0 || max_coord <= min_coord || out_edges.len() < 2 {
69 return Err(Error::Value);
70 }
71 let bands = out_edges.len() - 1;
72 if bands > 4096 {
73 return Err(Error::Shape);
74 }
75 let ratio = (max_coord / min_coord).ln();
76 for (i, slot) in out_edges.iter_mut().enumerate() {
77 let frac = i as f64 / bands as f64;
78 *slot = if i == 0 {
79 min_coord
80 } else if i == bands {
81 max_coord
82 } else {
83 min_coord * (frac * ratio).exp()
84 };
85 }
86 Ok(bands)
87}
88
89pub fn integrate_spectrum_over_axis(axis: AxisView<'_>, values: &[f64]) -> Result<f64, Error> {
92 let n = usize::try_from(axis.sample_count()).map_err(|_| Error::Overflow)?;
93 if values.len() != n || n == 0 {
94 return Err(Error::Shape);
95 }
96 for &v in values {
97 if !v.is_finite() {
98 return Err(Error::NonFinite);
99 }
100 if v < 0.0 {
101 return Err(Error::Value);
102 }
103 }
104 match axis.semantics() {
105 SampleSemantics::BinIntegral => Ok(values.iter().copied().sum()),
106 SampleSemantics::BinAverage => {
107 let mut acc = 0.0f64;
108 for (i, &val) in values.iter().enumerate() {
109 let lo = axis.coordinate(i as u64).map_err(Error::Spectrum)?;
110 let hi = axis.coordinate(i as u64 + 1).map_err(Error::Spectrum)?;
111 acc += val * (hi - lo);
112 }
113 Ok(acc)
114 }
115 SampleSemantics::PointDensity => {
116 if n == 1 {
117 return Err(Error::Shape);
118 }
119 let mut acc = 0.0f64;
120 for i in 0..(n - 1) {
121 let x0 = axis.coordinate(i as u64).map_err(Error::Spectrum)?;
122 let x1 = axis.coordinate(i as u64 + 1).map_err(Error::Spectrum)?;
123 acc += 0.5 * (values[i] + values[i + 1]) * (x1 - x0);
124 }
125 Ok(acc)
126 }
127 }
128}
129
130pub fn apply_spectral_response(
132 samples: &[f64],
133 response_weights: &[f64],
134 out: &mut [f64],
135) -> Result<(), Error> {
136 if samples.len() != response_weights.len() || out.len() < samples.len() {
137 return Err(Error::Shape);
138 }
139 for i in 0..samples.len() {
140 if !samples[i].is_finite() || !response_weights[i].is_finite() {
141 return Err(Error::NonFinite);
142 }
143 if samples[i] < 0.0 || response_weights[i] < 0.0 {
144 return Err(Error::Value);
145 }
146 out[i] = samples[i] * response_weights[i];
147 }
148 Ok(())
149}
150
151pub fn convert_density_hz(
154 s_f: f64,
155 f_hz: f64,
156 target: DensityTarget,
157) -> Result<f64, Error> {
158 if !s_f.is_finite() || !f_hz.is_finite() {
159 return Err(Error::NonFinite);
160 }
161 if f_hz <= 0.0 || s_f < 0.0 {
162 return Err(Error::Value);
163 }
164 match target {
165 DensityTarget::FrequencyHz => Ok(s_f),
166 DensityTarget::AngularFrequencyRadS => Ok(s_f / (2.0 * core::f64::consts::PI)),
167 DensityTarget::LogFrequencyNatural => Ok(f_hz * s_f),
168 DensityTarget::VacuumWavelengthMetres => {
169 let jac = density_coordinate_jacobian(
170 Quantity::SpectralIrradiance,
171 SampleSemantics::PointDensity,
172 DensityCoordinate::Hertz,
173 DensityCoordinate::VacuumMetre,
174 f_hz,
175 )
176 .map_err(Error::Spectrum)?;
177 jac.apply(s_f).map_err(Error::Spectrum)
178 }
179 }
180}
181
182pub fn convert_density_wavelength_to_hz(s_lambda: f64, lambda_m: f64) -> Result<f64, Error> {
183 let jac = density_coordinate_jacobian(
184 Quantity::SpectralIrradiance,
185 SampleSemantics::PointDensity,
186 DensityCoordinate::VacuumMetre,
187 DensityCoordinate::Hertz,
188 lambda_m,
189 )
190 .map_err(Error::Spectrum)?;
191 jac.apply(s_lambda).map_err(Error::Spectrum)
192}
193
194#[derive(Clone, Copy, Debug, PartialEq, Eq)]
195pub enum DensityTarget {
196 FrequencyHz,
197 AngularFrequencyRadS,
198 LogFrequencyNatural,
199 VacuumWavelengthMetres,
200}
201
202#[derive(Clone, Copy, Debug, PartialEq, Eq)]
203pub enum MuellerUnits {
204 DimensionlessTransfer,
205 PerSteradian,
206}
207
208impl MuellerUnits {
209 pub fn parse(units: &str) -> Result<Self, Error> {
210 match units {
211 "1" => Ok(Self::DimensionlessTransfer),
212 "sr^-1" => Ok(Self::PerSteradian),
213 _ => Err(Error::Descriptor),
214 }
215 }
216}
217
218#[derive(Clone, Copy, Debug, PartialEq)]
219pub struct MuellerRecord {
220 pub position_m: [f64; 3],
221 pub incident_direction: [f64; 3],
222 pub outgoing_direction: [f64; 3],
223 pub frequency_hz: f64,
224 pub material_entry: u32,
225 pub flags: u32,
226 pub mueller_matrix_m: [[f64; 4]; 4],
227}
228
229fn check_unit_vec(v: [f64; 3]) -> Result<(), Error> {
230 let norm = ((v[0] * v[0] + v[1] * v[1]) + v[2] * v[2]).sqrt();
231 if !norm.is_finite() || (norm - 1.0).abs() > 1.0e-6 {
232 return Err(Error::Value);
233 }
234 Ok(())
235}
236
237impl MuellerRecord {
238 pub fn parse(
239 bytes: &[u8],
240 valid: bool,
241 require_cloude_realizable: bool,
242 ) -> Result<Option<Self>, Error> {
243 if bytes.len() != 256 {
244 return Err(Error::Shape);
245 }
246 zeros(&bytes[88..128])?;
247 if !valid {
248 zeros(bytes)?;
249 return Ok(None);
250 }
251 finite(bytes, 0, 80)?;
252 finite(bytes, 128, 256)?;
253 let flags = u32_at(bytes, 84);
254 if flags != 0 {
255 return Err(Error::Flags);
256 }
257 let inc = triple(bytes, 24);
258 let out = triple(bytes, 48);
259 check_unit_vec(inc)?;
260 check_unit_vec(out)?;
261 let freq = f64_at(bytes, 72);
262 if freq <= 0.0 {
263 return Err(Error::Value);
264 }
265 let mut m = [[0.0f64; 4]; 4];
266 for r in 0..4 {
267 for c in 0..4 {
268 m[r][c] = f64_at(bytes, 128 + (r * 4 + c) * 8);
269 }
270 }
271 if m[0][0] <= 0.0 {
272 return Err(Error::Value);
273 }
274 let col_pol = m[1][0].hypot(m[2][0]).hypot(m[3][0]);
275 let row_pol = m[0][1].hypot(m[0][2]).hypot(m[0][3]);
276 let pol_tol = m[0][0] * (1.0 + 1.0e-9) + 1.0e-12;
277 if col_pol > pol_tol || row_pol > pol_tol {
278 return Err(Error::Value);
279 }
280 if require_cloude_realizable {
281 let _ = verify_mueller_physical_realizability(&m)?;
282 }
283 Ok(Some(Self {
284 position_m: triple(bytes, 0),
285 incident_direction: inc,
286 outgoing_direction: out,
287 frequency_hz: freq,
288 material_entry: u32_at(bytes, 80),
289 flags,
290 mueller_matrix_m: m,
291 }))
292 }
293
294 pub fn encode(&self, valid: bool, out: &mut [u8; 256]) -> Result<(), Error> {
295 *out = [0u8; 256];
296 if !valid {
297 return Ok(());
298 }
299 if self.flags != 0 {
300 return Err(Error::Flags);
301 }
302 if self.position_m.iter().any(|v| !v.is_finite())
303 || self.incident_direction.iter().any(|v| !v.is_finite())
304 || self.outgoing_direction.iter().any(|v| !v.is_finite())
305 || !self.frequency_hz.is_finite()
306 {
307 return Err(Error::NonFinite);
308 }
309 check_unit_vec(self.incident_direction)?;
310 check_unit_vec(self.outgoing_direction)?;
311 if self.frequency_hz <= 0.0 {
312 return Err(Error::Value);
313 }
314 for r in 0..4 {
315 for c in 0..4 {
316 if !self.mueller_matrix_m[r][c].is_finite() {
317 return Err(Error::NonFinite);
318 }
319 }
320 }
321 let _ = verify_mueller_physical_realizability(&self.mueller_matrix_m)?;
322 for (i, v) in self
323 .position_m
324 .iter()
325 .chain(self.incident_direction.iter())
326 .chain(self.outgoing_direction.iter())
327 .enumerate()
328 {
329 out[i * 8..i * 8 + 8].copy_from_slice(&v.to_le_bytes());
330 }
331 out[72..80].copy_from_slice(&self.frequency_hz.to_le_bytes());
332 out[80..84].copy_from_slice(&self.material_entry.to_le_bytes());
333 out[84..88].copy_from_slice(&self.flags.to_le_bytes());
334 for r in 0..4 {
335 for c in 0..4 {
336 let off = 128 + (r * 4 + c) * 8;
337 out[off..off + 8].copy_from_slice(&self.mueller_matrix_m[r][c].to_le_bytes());
338 }
339 }
340 Ok(())
341 }
342
343 pub fn apply_stokes(&self, s_in: [f64; 4]) -> Result<[f64; 4], Error> {
344 apply_mueller(&self.mueller_matrix_m, s_in)
345 }
346}
347
348pub fn encode_mueller_records(
349 records: &[MuellerRecord],
350 valid: Option<&[bool]>,
351 out: &mut [u8],
352) -> Result<usize, Error> {
353 if let Some(v) = valid {
354 if v.len() != records.len() {
355 return Err(Error::Shape);
356 }
357 }
358 let needed = records.len().checked_mul(256).ok_or(Error::Overflow)?;
359 if out.len() < needed {
360 return Err(Error::Shape);
361 }
362 for (idx, rec) in records.iter().enumerate() {
363 let is_valid = valid.is_none_or(|v| v[idx]);
364 let dst: &mut [u8; 256] = (&mut out[idx * 256..idx * 256 + 256])
365 .try_into()
366 .map_err(|_| Error::Shape)?;
367 rec.encode(is_valid, dst)?;
368 }
369 Ok(needed)
370}
371
372pub fn apply_mueller(m: &[[f64; 4]; 4], s_in: [f64; 4]) -> Result<[f64; 4], Error> {
373 if s_in.iter().any(|v| !v.is_finite()) {
374 return Err(Error::NonFinite);
375 }
376 if s_in[0] < 0.0 || s_in[1].hypot(s_in[2]).hypot(s_in[3]) > s_in[0] * (1.0 + 1.0e-9) + 1.0e-12
377 {
378 return Err(Error::Value);
379 }
380 let mut out = [0.0f64; 4];
381 for r in 0..4 {
382 out[r] = m[r][0] * s_in[0] + m[r][1] * s_in[1] + m[r][2] * s_in[2] + m[r][3] * s_in[3];
383 }
384 Ok(out)
385}
386
387pub fn jones_to_mueller(j_re: [[f64; 2]; 2], j_im: [[f64; 2]; 2]) -> Result<[[f64; 4]; 4], Error> {
389 for r in 0..2 {
390 for c in 0..2 {
391 if !j_re[r][c].is_finite() || !j_im[r][c].is_finite() {
392 return Err(Error::NonFinite);
393 }
394 }
395 }
396 let sig_re: [[[f64; 2]; 2]; 4] = [
397 [[1.0, 0.0], [0.0, 1.0]],
398 [[1.0, 0.0], [0.0, -1.0]],
399 [[0.0, 1.0], [1.0, 0.0]],
400 [[0.0, 0.0], [0.0, 0.0]],
401 ];
402 let sig_im: [[[f64; 2]; 2]; 4] = [
403 [[0.0, 0.0], [0.0, 0.0]],
404 [[0.0, 0.0], [0.0, 0.0]],
405 [[0.0, 0.0], [0.0, 0.0]],
406 [[0.0, -1.0], [1.0, 0.0]],
407 ];
408
409 let mut m = [[0.0f64; 4]; 4];
411 for k in 0..4 {
412 for l in 0..4 {
413 let mut js_re = [[0.0f64; 2]; 2];
415 let mut js_im = [[0.0f64; 2]; 2];
416 for r in 0..2 {
417 for c in 0..2 {
418 for p in 0..2 {
419 js_re[r][c] +=
420 j_re[r][p] * sig_re[l][p][c] - j_im[r][p] * sig_im[l][p][c];
421 js_im[r][c] +=
422 j_re[r][p] * sig_im[l][p][c] + j_im[r][p] * sig_re[l][p][c];
423 }
424 }
425 }
426 let mut t_re = [[0.0f64; 2]; 2];
427 let mut t_im = [[0.0f64; 2]; 2];
428 for r in 0..2 {
429 for c in 0..2 {
430 for p in 0..2 {
431 let jr = j_re[c][p];
433 let ji = -j_im[c][p];
434 t_re[r][c] += js_re[r][p] * jr - js_im[r][p] * ji;
435 t_im[r][c] += js_re[r][p] * ji + js_im[r][p] * jr;
436 }
437 }
438 }
439 let mut tr = 0.0f64;
440 for r in 0..2 {
441 for p in 0..2 {
442 tr += sig_re[k][r][p] * t_re[p][r] - sig_im[k][r][p] * t_im[p][r];
443 }
444 }
445 m[k][l] = 0.5 * tr;
446 }
447 }
448 Ok(m)
449}
450
451fn stokes_rotator(theta: f64) -> [[f64; 4]; 4] {
452 let (s, c) = (2.0 * theta).sin_cos();
453 [
454 [1.0, 0.0, 0.0, 0.0],
455 [0.0, c, s, 0.0],
456 [0.0, -s, c, 0.0],
457 [0.0, 0.0, 0.0, 1.0],
458 ]
459}
460
461fn matmul4(a: &[[f64; 4]; 4], b: &[[f64; 4]; 4]) -> [[f64; 4]; 4] {
462 let mut out = [[0.0f64; 4]; 4];
463 for r in 0..4 {
464 for c in 0..4 {
465 out[r][c] = a[r][0] * b[0][c]
466 + a[r][1] * b[1][c]
467 + a[r][2] * b[2][c]
468 + a[r][3] * b[3][c];
469 }
470 }
471 out
472}
473
474pub fn rotate_mueller_passive(
476 m: [[f64; 4]; 4],
477 theta_in_rad: f64,
478 theta_out_rad: f64,
479) -> Result<[[f64; 4]; 4], Error> {
480 if !theta_in_rad.is_finite() || !theta_out_rad.is_finite() {
481 return Err(Error::NonFinite);
482 }
483 let r_out = stokes_rotator(theta_out_rad);
484 let r_in_inv = stokes_rotator(-theta_in_rad);
485 Ok(matmul4(&matmul4(&r_out, &m), &r_in_inv))
486}
487
488pub fn cloude_coherency_matrix(m: &[[f64; 4]; 4]) -> ([[f64; 4]; 4], [[f64; 4]; 4]) {
491 let sig_re: [[[f64; 2]; 2]; 4] = [
492 [[1.0, 0.0], [0.0, 1.0]],
493 [[1.0, 0.0], [0.0, -1.0]],
494 [[0.0, 1.0], [1.0, 0.0]],
495 [[0.0, 0.0], [0.0, 0.0]],
496 ];
497 let sig_im: [[[f64; 2]; 2]; 4] = [
498 [[0.0, 0.0], [0.0, 0.0]],
499 [[0.0, 0.0], [0.0, 0.0]],
500 [[0.0, 0.0], [0.0, 0.0]],
501 [[0.0, -1.0], [1.0, 0.0]],
502 ];
503 let mut re = [[0.0f64; 4]; 4];
504 let mut im = [[0.0f64; 4]; 4];
505 for d in 0..2 {
506 for b in 0..2 {
507 let row = 2 * d + b;
508 for a in 0..2 {
509 for c in 0..2 {
510 let col = 2 * a + c;
511 let mut acc_r = 0.0f64;
512 let mut acc_i = 0.0f64;
513 for k in 0..4 {
514 let kr = sig_re[k][d][a];
515 let ki = sig_im[k][d][a];
516 if kr == 0.0 && ki == 0.0 {
517 continue;
518 }
519 for l in 0..4 {
520 let lr = sig_re[l][c][b];
521 let li = sig_im[l][c][b];
522 if lr == 0.0 && li == 0.0 {
523 continue;
524 }
525 let w = m[k][l];
526 acc_r += w * (kr * lr - ki * li);
527 acc_i += w * (kr * li + ki * lr);
528 }
529 }
530 re[row][col] = 0.25 * acc_r;
531 im[row][col] = 0.25 * acc_i;
532 }
533 }
534 }
535 }
536 (re, im)
537}
538
539pub fn cloude_eigenvalues(m: &[[f64; 4]; 4]) -> Result<[f64; 4], Error> {
542 let (re, im) = cloude_coherency_matrix(m);
543 let mut k = [[0.0f64; 8]; 8];
544 for r in 0..4 {
545 for c in 0..4 {
546 k[r][c] = re[r][c];
547 k[r + 4][c + 4] = re[r][c];
548 k[r][c + 4] = -im[r][c];
549 k[r + 4][c] = im[r][c];
550 }
551 }
552 for _ in 0..24 {
554 let mut max_off = 0.0f64;
555 for p in 0..8 {
556 for q in (p + 1)..8 {
557 max_off = max_off.max(k[p][q].abs());
558 }
559 }
560 if max_off <= 1.0e-14 * m[0][0].abs().max(1.0) {
561 break;
562 }
563 for p in 0..8 {
564 for q in (p + 1)..8 {
565 let apq = k[p][q];
566 if apq.abs() <= 1.0e-15 * m[0][0].abs().max(1.0) {
567 continue;
568 }
569 let diff = k[q][q] - k[p][p];
570 let t = if diff == 0.0 {
571 if apq >= 0.0 { 1.0 } else { -1.0 }
572 } else {
573 let tau = diff / (2.0 * apq);
574 if tau >= 0.0 {
575 1.0 / (tau + (1.0 + tau * tau).sqrt())
576 } else {
577 -1.0 / (-tau + (1.0 + tau * tau).sqrt())
578 }
579 };
580 let c = 1.0 / (1.0 + t * t).sqrt();
581 let s = t * c;
582 let app = k[p][p];
583 let aqq = k[q][q];
584 k[p][p] = app - t * apq;
585 k[q][q] = aqq + t * apq;
586 k[p][q] = 0.0;
587 k[q][p] = 0.0;
588 for r in 0..8 {
589 if r == p || r == q {
590 continue;
591 }
592 let arp = k[r][p];
593 let arq = k[r][q];
594 k[r][p] = c * arp - s * arq;
595 k[p][r] = k[r][p];
596 k[r][q] = s * arp + c * arq;
597 k[q][r] = k[r][q];
598 }
599 }
600 }
601 }
602 let mut vals8 = [
603 k[0][0], k[1][1], k[2][2], k[3][3], k[4][4], k[5][5], k[6][6], k[7][7],
604 ];
605 vals8.sort_by(|a, b| b.total_cmp(a));
606 Ok([vals8[0], vals8[2], vals8[4], vals8[6]])
607}
608
609pub fn verify_mueller_physical_realizability(m: &[[f64; 4]; 4]) -> Result<[f64; 4], Error> {
611 for r in 0..4 {
612 for c in 0..4 {
613 if !m[r][c].is_finite() {
614 return Err(Error::NonFinite);
615 }
616 }
617 }
618 let m00 = m[0][0];
619 if m00 <= 0.0 {
620 return Err(Error::Value);
621 }
622 let basis_stokes = [
623 [1.0, 0.0, 0.0, 0.0],
624 [1.0, 1.0, 0.0, 0.0],
625 [1.0, -1.0, 0.0, 0.0],
626 [1.0, 0.0, 1.0, 0.0],
627 [1.0, 0.0, -1.0, 0.0],
628 [1.0, 0.0, 0.0, 1.0],
629 [1.0, 0.0, 0.0, -1.0],
630 ];
631 for s_in in basis_stokes {
632 let s_out = apply_mueller(m, s_in)?;
633 let pol = s_out[1].hypot(s_out[2]).hypot(s_out[3]);
634 if s_out[0] < -1.0e-12 * m00 || pol > s_out[0].max(0.0) * (1.0 + 1.0e-9) + 1.0e-12 * m00 {
635 return Err(Error::Value);
636 }
637 }
638 let evals = cloude_eigenvalues(m)?;
639 let tol = -1.0e-9 * m00;
640 if evals.iter().any(|&lam| lam < tol) {
641 return Err(Error::Value);
642 }
643 Ok(evals)
644}