Skip to main content

qualia_core_db/q42/emf_container/extension/
model.rs

1//! Cold, bounded typed interpretation. EM cells are never redefined as RGB or audio samples.
2use super::super::header::{EmfError,EmfContainerHeader};
3use serde::{Deserialize, Serialize};
4
5pub const EMF_EXTENSION_SCHEMA_VERSION: u16 = 1;
6
7#[derive(Clone, Copy, Debug, PartialEq, Eq)]
8pub struct EmfExtensionLimits {
9    pub max_file_bytes: usize,
10    pub max_metadata_bytes: usize,
11    pub max_audio_bytes: usize,
12    pub max_tracks: usize,
13}
14impl EmfExtensionLimits {
15    pub const fn conservative() -> Self {
16        Self { max_file_bytes:16*1024*1024,max_metadata_bytes:64*1024,max_audio_bytes:16*1024*1024,max_tracks:16 }
17    }
18}
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all="snake_case")]
22pub enum EmfRgbPrimaries { Rec709, Rec2020, DisplayP3 }
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all="lowercase")]
25pub enum EmfWhitePoint { D65, D50 }
26#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
27#[serde(rename_all="lowercase")]
28pub enum EmfTransfer { Linear, Srgb, Bt709, Pq, Hlg }
29#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
30pub enum EmfObserver { #[serde(rename="cie1931_2deg")] Cie1931TwoDegree }
31
32/// This declares a derivative view; physical E/B/wavelength cells remain independent.
33#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
34#[serde(tag="model",rename_all="snake_case",deny_unknown_fields)]
35pub enum EmfColourInterpretation {
36    SpectralOnly,
37    RgbPreview { primaries:EmfRgbPrimaries,white_point:EmfWhitePoint,transfer:EmfTransfer,
38        observer:EmfObserver,reference_white_nits:f64 },
39}
40
41#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
42#[serde(rename_all="snake_case")]
43pub enum EmfEpochScale {
44    /// Relative to an authored origin, without a civil calendar claim.
45    Relative,
46    /// Seconds since 1970-01-01T00:00:00 UTC using POSIX leap-second exclusion.
47    UnixPosix,
48    /// Seconds since 1970-01-01T00:00:00 TAI.
49    Tai,
50}
51#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
52#[serde(deny_unknown_fields)]
53pub struct EmfEpoch { pub scale:EmfEpochScale,pub seconds:i64,pub nanoseconds:u32 }
54impl EmfEpoch {
55    pub fn header_seconds(&self)->f64 { self.seconds as f64+self.nanoseconds as f64/1_000_000_000.0 }
56    /// Exact epoch metadata is authoritative. The legacy f64 projection may differ
57    /// by at most two ULPs from normal conversion rounding, including large epochs.
58    pub fn matches_header_seconds(&self,value:f64)->bool {
59        if !value.is_finite(){return false;}
60        let expected=self.header_seconds();let magnitude=expected.abs();
61        let next=f64::from_bits(magnitude.to_bits().saturating_add(1));
62        let tolerance=((next-magnitude)*2.0).max(f64::MIN_POSITIVE);
63        (value-expected).abs()<=tolerance
64    }
65}
66#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
67#[serde(deny_unknown_fields)]
68pub struct EmfTimebase {
69    pub epoch:EmfEpoch,
70    pub ticks_per_second_num:u64,
71    pub ticks_per_second_den:u64,
72    pub slice_start_tick:i64,
73    pub slice_step_ticks:u64,
74}
75impl EmfTimebase {
76    pub fn slice_tick(&self,index:u32)->Result<i64,EmfError> {
77        let delta=self.slice_step_ticks.checked_mul(u64::from(index)).ok_or(EmfError::ArithmeticOverflow)?;
78        self.slice_start_tick.checked_add(i64::try_from(delta).map_err(|_|EmfError::ArithmeticOverflow)?)
79            .ok_or(EmfError::ArithmeticOverflow)
80    }
81    pub fn validate(&self)->Result<(),EmfError> {
82        if self.epoch.nanoseconds>=1_000_000_000||self.ticks_per_second_num==0||self.ticks_per_second_num>1_000_000_000_000
83            ||self.ticks_per_second_den==0||self.ticks_per_second_den>1_000_000_000||self.slice_step_ticks==0 {
84            return Err(EmfError::ExtensionMetadata);
85        }
86        Ok(())
87    }
88}
89
90#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
91#[serde(rename_all="snake_case")]
92pub enum EmfSpectralSemantics {
93    /// wavelength_nm is physical; authored sigma is an explicitly legacy scalar.
94    AuthoredWavelengthLegacySigma,
95    /// Multiple emitters collapse to an amplitude-weighted wavelength centroid.
96    /// This is not a sampled spectrum or a complete multi-band distribution.
97    AmplitudeCentroidLegacySigma,
98}
99#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
100#[serde(deny_unknown_fields)]
101pub struct EmfFieldInterpretation {
102    pub colour:EmfColourInterpretation,
103    pub timebase:EmfTimebase,
104    pub hilbert_order:u8,
105    pub spectral_semantics:EmfSpectralSemantics,
106}
107impl EmfFieldInterpretation {
108    /// Only an explicitly labelled wavelength-to-visible derivative is supported
109    /// by the legacy preview. Declared RGB calibration/gamut needs its own owner.
110    pub fn supports_legacy_visible_projection(&self)->bool {matches!(self.colour,EmfColourInterpretation::SpectralOnly)}
111    pub(crate) fn validate_header(&self,header:&EmfContainerHeader)->Result<(),EmfError>{
112        self.validate()?;
113        if !self.timebase.epoch.matches_header_seconds(header.reference_epoch_s)
114            ||!header.voxel_size_meters.is_finite()||header.voxel_size_meters<=0.0
115            ||header.origin_meters.iter().any(|v|!v.is_finite())
116            ||header.grid_dims_bricks.iter().any(|v|*v==0||*v>(1u32<<self.hilbert_order)) {
117            return Err(EmfError::ExtensionMetadata);
118        }
119        Ok(())
120    }
121    pub fn validate(&self)->Result<(),EmfError> {
122        if !(1..=8).contains(&self.hilbert_order){return Err(EmfError::ExtensionMetadata);}
123        if let EmfColourInterpretation::RgbPreview{reference_white_nits,..}=self.colour {
124            if !reference_white_nits.is_finite()||reference_white_nits<=0.0||reference_white_nits>1e9 {
125                return Err(EmfError::ExtensionMetadata);
126            }
127        }
128        self.timebase.validate()
129    }
130}
131
132#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
133#[serde(rename_all="snake_case")]
134pub enum EmfAudioPurpose { Recorded, Sonification, Reference }
135#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
136#[serde(rename_all="snake_case")]
137pub enum EmfChannelLayout { Mono, Stereo, Discrete }
138#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
139#[serde(tag="unit",rename_all="snake_case",deny_unknown_fields)]
140pub enum EmfSignalUnits { NormalizedAmplitude, Pascal, Arbitrary{label:String} }
141
142/// For frame i, time is start_tick*tick_den/tick_num + i*rate_den/rate_num seconds.
143/// No audible-band restriction is imposed by serialization.
144#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
145#[serde(deny_unknown_fields)]
146pub struct EmfAudioTrackSpec {
147    pub id:String,
148    pub purpose:EmfAudioPurpose,
149    pub channels:u16,
150    pub channel_layout:EmfChannelLayout,
151    pub sample_rate_num:u64,
152    pub sample_rate_den:u64,
153    pub start_tick:i64,
154    pub units:EmfSignalUnits,
155    pub units_per_sample:f64,
156}
157impl EmfAudioTrackSpec {
158    pub fn validate(&self,index:usize)->Result<(),EmfError> {
159        let bad=||EmfError::AudioTrack{track_index:index};
160        if self.id.is_empty()||self.id.len()>64||!self.id.bytes().all(|b|b.is_ascii_alphanumeric()||b"_-".contains(&b))
161            ||self.channels==0||self.channels>32||self.sample_rate_num==0||self.sample_rate_num>1_000_000_000_000
162            ||self.sample_rate_den==0||self.sample_rate_den>1_000_000_000
163            ||self.sample_rate_num>self.sample_rate_den.checked_mul(1_000_000_000).ok_or_else(bad)?
164            ||!self.units_per_sample.is_finite()||self.units_per_sample<=0.0 {
165            return Err(bad());
166        }
167        if matches!(self.channel_layout,EmfChannelLayout::Mono)&&self.channels!=1
168            ||matches!(self.channel_layout,EmfChannelLayout::Stereo)&&self.channels!=2 {
169            return Err(bad());
170        }
171        match &self.units {
172            EmfSignalUnits::NormalizedAmplitude if self.units_per_sample!=1.0=>return Err(bad()),
173            EmfSignalUnits::Arbitrary{label} if label.is_empty()||label.len()>64||label.chars().any(char::is_control)=>return Err(bad()),
174            _=>{},
175        }
176        Ok(())
177    }
178}
179
180#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
181#[serde(rename_all="snake_case")]
182pub enum EmfAudioCodec { PcmF32Le }
183
184#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
185#[serde(deny_unknown_fields)]
186pub struct EmfAudioTrackDescriptor {
187    pub codec:EmfAudioCodec,
188    pub spec:EmfAudioTrackSpec,
189    pub frames:u64,
190    /// Offset relative to the beginning of the extension's PCM section.
191    pub pcm_offset:u64,
192    pub pcm_bytes:u64,
193    /// Complete unkeyed BLAKE3 of exact original interleaved PCM-f32LE bytes.
194    pub blake3:[u8;32],
195}
196#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct EmfExtensionMetadata {
199    pub schema_version:u16,
200    pub field:EmfFieldInterpretation,
201    pub audio_tracks:Vec<EmfAudioTrackDescriptor>,
202}
203#[derive(Clone, Debug)]
204pub struct EmfAudioTrack<'a> { pub spec:EmfAudioTrackSpec,pub samples:&'a[f32] }