Skip to main content

qualia_core_db/medical/dicom_frames/
extract.rs

1use super::quantitative::{self, QuantitativeStatus};
2use crate::dicom::DicomMetadata;
3use crate::medical::{
4    dicom_dataset::{DatasetError, ElementKind, ItemId, Part10Dataset, WorkBudget},
5    dicom_geometry::{GeometryError, PatientImagePlane},
6};
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8pub enum FrameError {
9    Dataset(DatasetError),
10    FrameLimit,
11    MissingFrames,
12    SharedPerFrameConflict(u32),
13    TopLevelConflict(u32),
14    Geometry(GeometryError),
15    IdentityMismatch,
16    NonImage,
17    Pixel(crate::medical::dicom_codecs::PixelError),
18    PaddingInterpretationUnavailable,
19}
20impl From<DatasetError> for FrameError {
21    fn from(e: DatasetError) -> Self {
22        Self::Dataset(e)
23    }
24}
25#[derive(Clone, Copy, Debug)]
26pub struct FrameLimits {
27    pub max_frames: usize,
28    pub max_work: usize,
29    pub max_frame_bytes: usize,
30}
31impl Default for FrameLimits {
32    fn default() -> Self {
33        Self {
34            max_frames: 4096,
35            max_work: 16 * 1024 * 1024,
36            max_frame_bytes: 4 * 1024 * 1024,
37        }
38    }
39}
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub struct DatasetIdentity<'a> {
42    pub source_blake3: [u8; 32],
43    pub study_instance_uid: Option<&'a str>,
44    pub series_instance_uid: Option<&'a str>,
45    pub sop_class_uid: Option<&'a str>,
46    pub sop_instance_uid: Option<&'a str>,
47    pub frame_of_reference_uid: Option<&'a str>,
48}
49pub struct FrameRecord<'a> {
50    frame_number: u32,
51    identity: DatasetIdentity<'a>,
52    metadata: DicomMetadata,
53    quantitative: QuantitativeStatus<'a>,
54}
55impl<'a> FrameRecord<'a> {
56    pub fn frame_number(&self) -> u32 {
57        self.frame_number
58    }
59    pub fn identity(&self) -> DatasetIdentity<'a> {
60        self.identity
61    }
62    pub fn metadata(&self) -> &DicomMetadata {
63        &self.metadata
64    }
65    pub fn quantitative(&self) -> QuantitativeStatus<'a> {
66        self.quantitative
67    }
68    /// Apply only the explicitly selected mapping to the matching source/frame.
69    /// Pixel-padding semantics are not silently treated as measured intensities.
70    pub fn quantitative_sample(
71        &self,
72        pixels: &crate::medical::dicom_codecs::NativePixelView<'_>,
73        row: u16,
74        column: u16,
75        real_world: bool,
76    ) -> Result<Option<f64>, FrameError> {
77        if pixels.source_blake3() != self.identity.source_blake3 {
78            return Err(FrameError::IdentityMismatch);
79        }
80        if pixels.padding_declared() {
81            return Err(FrameError::PaddingInterpretationUnavailable);
82        }
83        let mapping = if real_world {
84            self.quantitative.real_world
85        } else {
86            self.quantitative.modality
87        };
88        let Some(mapping) = mapping else {
89            return Ok(None);
90        };
91        if mapping.source_blake3() != self.identity.source_blake3
92            || mapping.frame_number() != self.frame_number
93        {
94            return Err(FrameError::IdentityMismatch);
95        }
96        let stored = pixels
97            .sample(
98                self.frame_number
99                    .checked_sub(1)
100                    .ok_or(FrameError::IdentityMismatch)?,
101                row,
102                column,
103            )
104            .map_err(FrameError::Pixel)?;
105        Ok(Some(mapping.apply(stored.as_f64())?))
106    }
107    pub fn plane(&self) -> Result<PatientImagePlane<'_>, GeometryError> {
108        PatientImagePlane::from_metadata(&self.metadata)
109    }
110}
111pub struct FrameSet<'a> {
112    pub identity: DatasetIdentity<'a>,
113    pub frames: Vec<FrameRecord<'a>>,
114    pub enhanced: bool,
115}
116pub(super) fn single_item(
117    ds: &Part10Dataset<'_>,
118    scope: Option<ItemId>,
119    tag: u32,
120    w: &mut WorkBudget,
121) -> Result<Option<ItemId>, FrameError> {
122    let Some(id) = ds.find(scope, tag, w)? else {
123        return Ok(None);
124    };
125    if ds.element(id)?.kind != ElementKind::Sequence {
126        return Err(DatasetError::Invalid(tag).into());
127    }
128    let mut items = ds.sequence_items(id, w)?;
129    let first = items.next().ok_or(DatasetError::Invalid(tag))?;
130    if items.next().is_some() {
131        return Err(DatasetError::Invalid(tag).into());
132    }
133    Ok(Some(first))
134}
135pub(super) fn macro_item(
136    ds: &Part10Dataset<'_>,
137    shared: Option<ItemId>,
138    per: Option<ItemId>,
139    tag: u32,
140    w: &mut WorkBudget,
141) -> Result<Option<ItemId>, FrameError> {
142    let a = if let Some(i) = shared {
143        single_item(ds, Some(i), tag, w)?
144    } else {
145        None
146    };
147    let b = if let Some(i) = per {
148        single_item(ds, Some(i), tag, w)?
149    } else {
150        None
151    };
152    if a.is_some() && b.is_some() {
153        return Err(FrameError::SharedPerFrameConflict(tag));
154    }
155    Ok(a.or(b))
156}
157fn geometry(
158    ds: &Part10Dataset<'_>,
159    meta: &mut DicomMetadata,
160    scope: Option<ItemId>,
161    tag: u32,
162    w: &mut WorkBudget,
163) -> Result<(), FrameError> {
164    if let Some(id) = ds.find(scope, tag, w)? {
165        let e = ds.element(id)?;
166        if e.kind != ElementKind::Value {
167            return Err(DatasetError::Invalid(tag).into());
168        }
169        crate::medical::dicom_geometry::apply_geometry_value(meta, tag, ds.value(id)?, e.vr);
170    }
171    Ok(())
172}
173impl<'a> FrameSet<'a> {
174    pub fn extract(ds: &Part10Dataset<'a>, limits: FrameLimits) -> Result<Self, FrameError> {
175        let mut w = WorkBudget::new(limits.max_work);
176        let identity = DatasetIdentity {
177            source_blake3: ds.source_blake3(),
178            study_instance_uid: ds.uid(None, 0x0020000d, &mut w)?,
179            series_instance_uid: ds.uid(None, 0x0020000e, &mut w)?,
180            sop_class_uid: ds.uid(None, 0x00080016, &mut w)?,
181            sop_instance_uid: ds.uid(None, 0x00080018, &mut w)?,
182            frame_of_reference_uid: ds.uid(None, 0x00200052, &mut w)?,
183        };
184        if ds.media_sop_class_uid().is_some() && ds.media_sop_class_uid() != identity.sop_class_uid
185            || ds.media_sop_instance_uid().is_some()
186                && ds.media_sop_instance_uid() != identity.sop_instance_uid
187        {
188            return Err(FrameError::IdentityMismatch);
189        }
190        let shared = single_item(ds, None, 0x52009229, &mut w)?;
191        let per_seq = ds.find(None, 0x52009230, &mut w)?;
192        let enhanced = shared.is_some() || per_seq.is_some();
193        let mut pixels = 0;
194        for tag in [0x7fe00010, 0x7fe00008, 0x7fe00009] {
195            pixels += usize::from(ds.find(None, tag, &mut w)?.is_some());
196        }
197        if pixels == 0 {
198            return Ok(Self {
199                identity,
200                frames: Vec::new(),
201                enhanced,
202            });
203        }
204        if pixels > 1 {
205            return Err(DatasetError::Invalid(0x7fe00010).into());
206        }
207        let count = usize::try_from(ds.frame_count(&mut w)?).map_err(|_| FrameError::FrameLimit)?;
208        let frame_bytes = count
209            .checked_mul(
210                std::mem::size_of::<FrameRecord<'a>>() + std::mem::size_of::<ItemId>() + 128,
211            )
212            .ok_or(FrameError::FrameLimit)?;
213        if frame_bytes > limits.max_frame_bytes {
214            return Err(FrameError::FrameLimit);
215        }
216        if count > limits.max_frames {
217            return Err(FrameError::FrameLimit);
218        }
219        if enhanced && ds.find(None, 0x00280008, &mut w)?.is_none() {
220            return Err(FrameError::MissingFrames);
221        }
222        let mut per_items = Vec::new();
223        per_items
224            .try_reserve_exact(count)
225            .map_err(|_| FrameError::FrameLimit)?;
226        if let Some(id) = per_seq {
227            if ds.element(id)?.kind != ElementKind::Sequence {
228                return Err(DatasetError::Invalid(0x52009230).into());
229            }
230            for item in ds.sequence_items(id, &mut w)? {
231                if per_items.len() >= count {
232                    return Err(FrameError::MissingFrames);
233                }
234                per_items.push(item);
235            }
236            if per_items.len() != count {
237                return Err(FrameError::MissingFrames);
238            }
239        }
240        let mut frames = Vec::new();
241        frames
242            .try_reserve_exact(count)
243            .map_err(|_| FrameError::FrameLimit)?;
244        for frame in 0..count {
245            let per = per_items.get(frame).copied();
246            let mut metadata = DicomMetadata::default();
247            for tag in [0x00102210, 0x00200052] {
248                geometry(ds, &mut metadata, None, tag, &mut w)?;
249            }
250            if enhanced {
251                for (macro_tag, value_tag) in [
252                    (0x00209113, 0x00200032),
253                    (0x00209116, 0x00200037),
254                    (0x00289110, 0x00280030),
255                ] {
256                    if ds.find(None, value_tag, &mut w)?.is_some() {
257                        return Err(FrameError::TopLevelConflict(value_tag));
258                    }
259                    if let Some(item) = macro_item(ds, shared, per, macro_tag, &mut w)? {
260                        geometry(ds, &mut metadata, Some(item), value_tag, &mut w)?;
261                    }
262                }
263            } else if count == 1 {
264                for tag in [0x00200032, 0x00200037, 0x00280030] {
265                    geometry(ds, &mut metadata, None, tag, &mut w)?;
266                }
267            }
268            let quantitative = quantitative::extract(
269                ds,
270                shared,
271                per,
272                enhanced,
273                u32::try_from(frame + 1).map_err(|_| FrameError::FrameLimit)?,
274                &mut w,
275            )?;
276            frames.push(FrameRecord {
277                frame_number: u32::try_from(frame + 1).map_err(|_| FrameError::FrameLimit)?,
278                identity,
279                metadata,
280                quantitative,
281            });
282        }
283        Ok(Self {
284            identity,
285            frames,
286            enhanced,
287        })
288    }
289}