Skip to main content

qualia_core_db/medical/dicom_part10/
parser.rs

1//! DICOM Part-10 metadata parsing and zero-copy Pixel Data split entry points.
2
3use std::fs;
4use std::path::Path;
5
6use super::stream::{
7    decode_dicom_string, decode_i32, decode_numeric_string, decode_u16, encapsulated_pixel_end,
8    find_dataset_offset, read_element_header, skip_element, TransferSyntax,
9};
10use super::types::{
11    DicomError, DicomMetadata, DicomPixelSlice, DicomSplitPayload, ITEM_DELIMITER,
12    ITEM_END_DELIMITER, SEQ_DELIMITER, TAG_BITS_ALLOCATED, TAG_BODY_PART_EXAMINED, TAG_COLUMNS,
13    TAG_INSTANCE_NUMBER, TAG_MODALITY, TAG_PATIENT_ID, TAG_PHOTOMETRIC_INTERPRETATION,
14    TAG_PIXEL_DATA, TAG_PIXEL_REPRESENTATION, TAG_ROWS, TAG_SERIES_DESCRIPTION,
15    TAG_SERIES_INSTANCE_UID, TAG_STUDY_DATE, TAG_STUDY_DESCRIPTION, TAG_TRANSFER_SYNTAX_UID,
16    TAG_WINDOW_CENTER, TAG_WINDOW_WIDTH, TS_EXPLICIT_VR_LITTLE_ENDIAN,
17    TS_IMPLICIT_VR_LITTLE_ENDIAN, TS_JPEG2000, TS_JPEG2000_LOSSLESS, TS_JPEG_BASELINE,
18    TS_RLE_LOSSLESS,
19};
20
21/// Walk the group-0x0002 file-meta elements (always explicit-VR LE)
22/// to extract the transfer-syntax UID; returns it plus the dataset cursor.
23fn parse_meta_information(data: &[u8], offset: usize) -> Result<(String, usize), DicomError> {
24    let mut transfer_syntax = TS_EXPLICIT_VR_LITTLE_ENDIAN.to_string();
25    let mut cursor = offset;
26
27    loop {
28        let Some(header) =
29            read_element_header(data, cursor, TransferSyntax::ExplicitVrLittleEndian, true)?
30        else {
31            break;
32        };
33        let value_offset = cursor + header.header_size;
34        if header.tag == TAG_TRANSFER_SYNTAX_UID && header.length > 0 {
35            let end = value_offset + header.length;
36            if end > data.len() {
37                return Err(DicomError::UnexpectedEof);
38            }
39            transfer_syntax = decode_dicom_string(&data[value_offset..end]);
40        }
41        if (header.tag >> 16) as u16 > 0x0002 {
42            break;
43        }
44        cursor = skip_element(
45            data,
46            cursor,
47            &header,
48            TransferSyntax::ExplicitVrLittleEndian,
49            true,
50        )?;
51    }
52
53    Ok((transfer_syntax, cursor))
54}
55
56/// Map a transfer-syntax UID to the `TransferSyntax` variant;
57/// encapsulated syntaxes (JPEG/JPEG2000/RLE) fold into
58/// `EncapsulatedExplicitVr`. Unknown UIDs fail closed.
59fn transfer_syntax_from_uid(uid: &str) -> Result<TransferSyntax, DicomError> {
60    match uid {
61        TS_IMPLICIT_VR_LITTLE_ENDIAN => Ok(TransferSyntax::ImplicitVrLittleEndian),
62        TS_EXPLICIT_VR_LITTLE_ENDIAN => Ok(TransferSyntax::ExplicitVrLittleEndian),
63        TS_JPEG2000_LOSSLESS
64        | TS_JPEG2000
65        | TS_JPEG_BASELINE
66        | "1.2.840.10008.1.2.4.51"
67        | TS_RLE_LOSSLESS => Ok(TransferSyntax::EncapsulatedExplicitVr),
68        other => Err(DicomError::UnsupportedTransferSyntax(other.to_string())),
69    }
70}
71
72/// Decode `value` into the matching `DicomMetadata` field for each
73/// recognized tag; unrecognized tags are skipped.
74fn apply_value(meta: &mut DicomMetadata, tag: u32, value: &[u8], vr: Option<[u8; 2]>) {
75    if crate::medical::dicom_geometry::apply_geometry_value(meta, tag, value, vr) {
76        return;
77    }
78    match tag {
79        TAG_MODALITY => meta.modality = decode_dicom_string(value),
80        TAG_STUDY_DESCRIPTION => meta.study_description = decode_dicom_string(value),
81        TAG_SERIES_DESCRIPTION => meta.series_description = decode_dicom_string(value),
82        TAG_BODY_PART_EXAMINED => meta.body_part_examined = decode_dicom_string(value),
83        TAG_SERIES_INSTANCE_UID => meta.series_instance_uid = decode_dicom_string(value),
84        TAG_INSTANCE_NUMBER => meta.instance_number = decode_i32(value),
85        TAG_ROWS => meta.rows = decode_u16(value),
86        TAG_COLUMNS => meta.columns = decode_u16(value),
87        TAG_WINDOW_CENTER => meta.window_center = decode_numeric_string(value),
88        TAG_WINDOW_WIDTH => meta.window_width = decode_numeric_string(value),
89        TAG_PHOTOMETRIC_INTERPRETATION => {
90            meta.photometric_interpretation = decode_dicom_string(value)
91        }
92        TAG_BITS_ALLOCATED => meta.bits_allocated = decode_u16(value),
93        TAG_PIXEL_REPRESENTATION => meta.pixel_representation = decode_u16(value),
94        TAG_PATIENT_ID => meta.patient_id = decode_dicom_string(value),
95        TAG_STUDY_DATE => meta.study_date = decode_dicom_string(value),
96        _ => {}
97    }
98}
99
100/// Sequential element walk: applies recognized tags into `meta` and,
101/// when `capture_pixels`, returns the Pixel Data element's byte
102/// slice (offset+length — no copy, zero-copy ingest seam).
103fn walk_dataset(
104    data: &[u8],
105    mut cursor: usize,
106    syntax: TransferSyntax,
107    meta: &mut DicomMetadata,
108    capture_pixels: bool,
109) -> Result<Option<DicomPixelSlice>, DicomError> {
110    let mut pixels = None;
111
112    while cursor + 8 <= data.len() {
113        let Some(header) = read_element_header(data, cursor, syntax, false)? else {
114            break;
115        };
116
117        if header.tag == TAG_PIXEL_DATA {
118            if capture_pixels {
119                let value_offset = cursor + header.header_size;
120                if header.length == 0xFFFF_FFFF {
121                    let end = encapsulated_pixel_end(data, value_offset)?;
122                    pixels = Some(DicomPixelSlice {
123                        offset: value_offset,
124                        length: end.saturating_sub(value_offset),
125                    });
126                } else {
127                    let end = value_offset
128                        .checked_add(header.length)
129                        .ok_or(DicomError::UnexpectedEof)?;
130                    if end <= data.len() {
131                        pixels = Some(DicomPixelSlice {
132                            offset: value_offset,
133                            length: header.length,
134                        });
135                    }
136                }
137            }
138            break;
139        }
140
141        if header.tag == ITEM_DELIMITER
142            || header.tag == ITEM_END_DELIMITER
143            || header.tag == SEQ_DELIMITER
144        {
145            cursor = skip_element(data, cursor, &header, syntax, false)?;
146            continue;
147        }
148
149        let value_offset = cursor + header.header_size;
150        if header.length != 0xFFFF_FFFF && value_offset + header.length <= data.len() {
151            apply_value(
152                meta,
153                header.tag,
154                &data[value_offset..value_offset + header.length],
155                header.vr,
156            );
157        }
158
159        cursor = skip_element(data, cursor, &header, syntax, false)?;
160    }
161
162    Ok(pixels)
163}
164
165/// Parse DICOM Part 10 metadata from an on-disk byte buffer (pixel data optional).
166pub fn parse_dicom_metadata_bytes(data: &[u8]) -> Result<DicomMetadata, DicomError> {
167    let offset = find_dataset_offset(data)?;
168    let (transfer_syntax_uid, cursor) = parse_meta_information(data, offset)?;
169    let syntax = transfer_syntax_from_uid(&transfer_syntax_uid)?;
170    let mut meta = DicomMetadata {
171        transfer_syntax_uid,
172        ..Default::default()
173    };
174    walk_dataset(data, cursor, syntax, &mut meta, false)?;
175    Ok(meta)
176}
177
178/// Split-ingestion entry: metadata tags + pixel slice bounds (no heap copy of pixels).
179pub fn split_dicom_payload(data: &[u8]) -> Result<DicomSplitPayload, DicomError> {
180    let offset = find_dataset_offset(data)?;
181    let (transfer_syntax_uid, cursor) = parse_meta_information(data, offset)?;
182    let syntax = transfer_syntax_from_uid(&transfer_syntax_uid)?;
183
184    let mut meta = DicomMetadata {
185        transfer_syntax_uid,
186        ..Default::default()
187    };
188
189    let pixels = walk_dataset(data, cursor, syntax, &mut meta, true)?
190        .ok_or(DicomError::Io("DICOM has no Pixel Data (7FE0,0010)".into()))?;
191
192    Ok(DicomSplitPayload { meta, pixels })
193}
194
195/// Parse DICOM metadata from a file path.
196pub fn parse_dicom_file(path: &Path) -> Result<DicomMetadata, DicomError> {
197    let bytes = fs::read(path).map_err(|e| DicomError::Io(e.to_string()))?;
198    parse_dicom_metadata_bytes(&bytes)
199}