Skip to main content

dcmnorm_parser/dataset/
read.rs

1//! This module contains a mid-level abstraction for reading DICOM content
2//! sequentially.
3//!
4//! The rest of the crate is used to obtain DICOM element headers and values.
5//! At this level, headers and values are treated as tokens which can be used
6//! to form a syntax tree of a full data set.
7use crate::stateful::decode::{
8    CharacterSetOverride, DynStatefulDecoder, Error as DecoderError, StatefulDecode,
9    StatefulDecoder,
10};
11use dcmnorm_core::header::{DataElementHeader, Header, Length, SequenceItemHeader};
12use dcmnorm_core::{PrimitiveValue, Tag, VR};
13use dcmnorm_encoding::decode::adaptive_le::StandardAdaptiveVRLittleEndianDecoder;
14use dcmnorm_encoding::text::SpecificCharacterSet;
15use dcmnorm_encoding::transfer_syntax::{DynDecoder, TransferSyntax};
16use snafu::{Backtrace, ResultExt, Snafu};
17use std::cmp::Ordering;
18use std::io::{Read, Seek};
19
20use super::{DataToken, SeqTokenType};
21
22fn is_stateful_decode<T>(_: &T)
23where
24    T: StatefulDecode,
25{
26}
27
28#[derive(Debug, Snafu)]
29#[non_exhaustive]
30pub enum Error {
31    #[snafu(display("Could not create decoder"))]
32    CreateDecoder {
33        #[snafu(backtrace)]
34        source: DecoderError,
35    },
36    #[snafu(display("Could not read item header"))]
37    ReadItemHeader {
38        #[snafu(backtrace)]
39        source: DecoderError,
40    },
41    #[snafu(display("Could not read element header"))]
42    ReadHeader {
43        #[snafu(backtrace)]
44        source: DecoderError,
45    },
46    #[snafu(display("Could not read {} value bytes for element tagged {}", len, tag))]
47    ReadValue {
48        len: u32,
49        tag: Tag,
50        #[snafu(backtrace)]
51        source: DecoderError,
52    },
53    #[snafu(display("Could not read {} bytes for item value", len))]
54    ReadItemValue {
55        len: u32,
56        #[snafu(backtrace)]
57        source: DecoderError,
58    },
59    #[snafu(display(
60        "Inconsistent sequence end: expected end at {} bytes but read {}",
61        end_of_sequence,
62        bytes_read
63    ))]
64    InconsistentSequenceEnd {
65        end_of_sequence: u64,
66        bytes_read: u64,
67        backtrace: Backtrace,
68    },
69    #[snafu(display("Unexpected item tag {} while reading element header", tag))]
70    UnexpectedItemTag { tag: Tag, backtrace: Backtrace },
71    #[snafu(display(
72        "Unexpected item header outside a dataset sequence at {:#x}",
73        bytes_read
74    ))]
75    UnexpectedItemHeader {
76        bytes_read: u64,
77        backtrace: Backtrace,
78    },
79    /// Undefined pixel data item length
80    UndefinedItemLength,
81    /// Invalid data element length {len:04X} of {tag} at {bytes_read:#x}
82    InvalidElementLength { tag: Tag, len: u32, bytes_read: u64 },
83    /// Invalid sequence item length {len:04X} at {bytes_read:#x}
84    InvalidItemLength { len: u32, bytes_read: u64 },
85    /// Cannot skip here: {context}
86    SkipNotApplicable { context: &'static str },
87    #[snafu(display("Could not skip {} value bytes for element tagged {}", len, tag))]
88    SkipValue {
89        len: u64,
90        tag: Tag,
91        #[snafu(backtrace)]
92        source: DecoderError,
93    },
94}
95
96pub type Result<T> = std::result::Result<T, Error>;
97
98/// A reader-specific token representing a sequence or item start.
99#[derive(Debug, Copy, Clone, PartialEq)]
100struct SeqToken {
101    /// Whether it is the start of a sequence or the start of an item.
102    typ: SeqTokenType,
103    /// The length of the value, as indicated by the starting element,
104    /// can be unknown.
105    len: Length,
106    /// Whether this sequence token is part of an encapsulated pixel data.
107    pixel_data: bool,
108    /// The number of bytes the parser has read until it reached the
109    /// beginning of the sequence or item value data.
110    base_offset: u64,
111    /// Whether this is an undefined-length `UN` sequence, whose content the parser decodes as
112    /// Implicit VR Little Endian (PS3.5 6.2.2) until it ends.
113    implicit_vr: bool,
114}
115
116/// The value reading strategy for the data set reader.
117///
118/// It defines how the `PrimitiveValue`s in value tokens are constructed.
119#[derive(Debug, Default, Copy, Clone, Eq, Hash, PartialEq)]
120pub enum ValueReadStrategy {
121    /// Textual values will be decoded according to their value representation.
122    ///
123    /// Word-sized binary values are read according to
124    /// the expected byte order.
125    /// Dates, times, and date-times (DA, DT, TM) are parsed
126    /// into their more specific variants,
127    /// leading to parser failure if they are not valid DICOM.
128    /// String numbers (IS, FD) are also converted into binary representations.
129    /// For the case of floats, this may introduce precision errors.
130    Interpreted,
131    /// Values will be stored without decoding dates or textual numbers.
132    ///
133    /// Word-sized binary values are read according to
134    /// the expected byte order.
135    /// Date-time values and numbers are kept in their original string
136    /// representation as string objects.
137    /// All text is still decoded into Rust string values,
138    /// in accordance to the standard,
139    /// unless its value representation is unknown to the decoder.
140    ///
141    /// This is the default strategy.
142    #[default]
143    Preserved,
144    /// All primitive values are fetched as raw byte buffers,
145    /// without any form of decoding or interpretation.
146    /// Not even byte order conversions are made.
147    ///
148    /// This strategy is not recommended,
149    /// as it makes the retrieval of important textual data more difficult.
150    Raw,
151}
152
153/// A strategy for when the parser finds a data element with an odd number
154/// in the _length_ header field.
155#[derive(Debug, Default, Copy, Clone, Eq, Hash, PartialEq)]
156#[non_exhaustive]
157pub enum OddLengthStrategy {
158    /// Accept elements with an odd length as is,
159    /// continuing data set reading normally.
160    #[default]
161    Accept,
162    /// Assume that the real length is `length + 1`,
163    /// as in the next even number.
164    NextEven,
165    /// Raise an error instead
166    Fail,
167}
168
169/// The set of options for the data set reader.
170#[derive(Debug, Default, Copy, Clone, Eq, Hash, PartialEq)]
171#[non_exhaustive]
172pub struct DataSetReaderOptions {
173    /// The value reading strategy
174    pub value_read: ValueReadStrategy,
175
176    /// Whether to assume a different character set
177    /// depending on certain conditions
178    pub charset_override: CharacterSetOverride,
179
180    /// The strategy for handling odd length data elements
181    pub odd_length: OddLengthStrategy,
182    /// The position of the reader as received at building time in bytes.
183    /// Defaults to 0.
184    pub base_offset: u64,
185
186    /// When enabled, the decoder will probe the first non-meta element
187    /// to determine whether the dataset actually uses explicit or implicit VR,
188    /// regardless of what the transfer syntax declares.
189    ///
190    /// This handles non-conformant files that declare Explicit VR Little Endian
191    /// but actually encode the dataset in Implicit VR.
192    /// Defaults to `false`.
193    pub flexible_decoding: bool,
194}
195
196impl DataSetReaderOptions {
197    /// Replace the value reading strategy of the options.
198    pub fn value_read(mut self, value_read: ValueReadStrategy) -> Self {
199        self.value_read = value_read;
200        self
201    }
202    /// Replace the base reader offset of the options.
203    pub fn base_offset(mut self, base_offset: u64) -> Self {
204        self.base_offset = base_offset;
205        self
206    }
207    /// Enable or disable flexible VR decoding.
208    pub fn flexible_decoding(mut self, flexible_decoding: bool) -> Self {
209        self.flexible_decoding = flexible_decoding;
210        self
211    }
212}
213
214/// A higher-level reader for retrieving structure in a DICOM data set from an
215/// arbitrary data source.
216#[derive(Debug)]
217pub struct DataSetReader<S> {
218    /// the stateful decoder
219    parser: S,
220    /// the options of this reader
221    options: DataSetReaderOptions,
222    /// whether the reader is expecting an item header next (or a sequence delimiter)
223    in_sequence: bool,
224    /// whether the reader is expecting the first item value of a pixel sequence next
225    /// (offset table)
226    offset_table_next: bool,
227    /// whether a check for a sequence or item delimitation is pending
228    delimiter_check_pending: bool,
229    /// a stack of delimiters
230    seq_delimiters: Vec<SeqToken>,
231    /// fuse the iteration process if true
232    hard_break: bool,
233    /// last decoded header
234    last_header: Option<DataElementHeader>,
235    /// if a peek was taken, this holds the token peeked
236    peek: Option<DataToken>,
237}
238
239impl<R> DataSetReader<DynStatefulDecoder<R>> {
240    /// Create a new data set token reader with the given byte source,
241    /// while considering the given transfer syntax specifier.
242    #[inline]
243    pub fn new_with_ts(source: R, ts: &TransferSyntax) -> Result<Self>
244    where
245        R: Read,
246    {
247        Self::new_with_ts_cs_options(source, ts, Default::default(), Default::default())
248    }
249
250    /// Create a new iterator with the given transfer syntax and options.
251    #[inline]
252    pub fn new_with_ts_options(
253        source: R,
254        ts: &TransferSyntax,
255        options: DataSetReaderOptions,
256    ) -> Result<Self>
257    where
258        R: Read,
259    {
260        Self::new_with_ts_cs_options(source, ts, SpecificCharacterSet::default(), options)
261    }
262
263    /// Create a new data set token reader with the given byte source,
264    /// while considering the given transfer syntax specifier
265    /// and the specific character set to assume by default.
266    ///
267    /// Note that the data set being read
268    /// can override the character set with the presence of a
269    /// _Specific Character Set_ data element.
270    #[inline]
271    pub fn new_with_ts_cs(source: R, ts: &TransferSyntax, cs: SpecificCharacterSet) -> Result<Self>
272    where
273        R: Read,
274    {
275        Self::new_with_ts_cs_options(source, ts, cs, Default::default())
276    }
277
278    /// Create a new iterator with the given stateful decoder and options.
279    pub fn new_with_ts_cs_options(
280        source: R,
281        ts: &TransferSyntax,
282        cs: SpecificCharacterSet,
283        options: DataSetReaderOptions,
284    ) -> Result<Self>
285    where
286        R: Read,
287    {
288        let parser = if options.flexible_decoding
289            && ts.endianness() == dcmnorm_encoding::Endianness::Little
290        {
291            let basic = ts.basic_decoder();
292            let decoder: DynDecoder<R> = Box::<StandardAdaptiveVRLittleEndianDecoder>::default();
293            StatefulDecoder::new_with_all_options(
294                source,
295                decoder,
296                basic,
297                cs,
298                options.charset_override,
299                0,
300            )
301        } else {
302            DynStatefulDecoder::new_with_override(source, ts, cs, options.charset_override, 0)
303                .context(CreateDecoderSnafu)?
304        };
305
306        is_stateful_decode(&parser);
307
308        Ok(DataSetReader {
309            parser,
310            options,
311            seq_delimiters: Vec::new(),
312            delimiter_check_pending: false,
313            offset_table_next: false,
314            in_sequence: false,
315            hard_break: false,
316            last_header: None,
317            peek: None,
318        })
319    }
320}
321
322impl<S> DataSetReader<S> {
323    /// Create a new iterator with the given stateful decoder and options.
324    pub fn new(decoder: S, options: DataSetReaderOptions) -> Self {
325        DataSetReader {
326            parser: decoder,
327            options,
328            seq_delimiters: Vec::new(),
329            delimiter_check_pending: false,
330            offset_table_next: false,
331            in_sequence: false,
332            hard_break: false,
333            last_header: None,
334            peek: None,
335        }
336    }
337}
338
339impl<S> Iterator for DataSetReader<S>
340where
341    S: StatefulDecode,
342{
343    type Item = Result<DataToken>;
344
345    fn next(&mut self) -> Option<Self::Item> {
346        loop {
347            if self.hard_break {
348                return None;
349            }
350            // if there was a peek, consume peeked token
351            if let Some(token) = self.peek.take() {
352                return Some(Ok(token));
353            }
354
355            // item or sequence delimitation logic for explicit lengths
356            if self.delimiter_check_pending {
357                match self.update_seq_delimiters() {
358                    Err(e) => {
359                        self.hard_break = true;
360                        return Some(Err(e));
361                    }
362                    Ok(Some(token)) => return Some(Ok(token)),
363                    Ok(None) => { /* no-op */ }
364                }
365            }
366
367            // This will always return unless we do a `continue`.
368            return if self.in_sequence {
369                // at sequence level, expecting item header
370
371                match self.parser.decode_item_header() {
372                    Ok(header) => {
373                        match header {
374                            SequenceItemHeader::Item { len } => {
375                                let len = match self.sanitize_length(len) {
376                                    Some(len) => len,
377                                    None => {
378                                        return Some(
379                                            InvalidItemLengthSnafu {
380                                                bytes_read: self.parser.position(),
381                                                len: len.0,
382                                            }
383                                            .fail(),
384                                        )
385                                    }
386                                };
387                                // entered a new item
388                                self.in_sequence = false;
389
390                                let last_delimiter = match self.seq_delimiters.last() {
391                                    Some(d) => d,
392                                    None => {
393                                        return Some(
394                                            UnexpectedItemHeaderSnafu {
395                                                bytes_read: self.parser.position(),
396                                            }
397                                            .fail(),
398                                        )
399                                    }
400                                };
401                                self.push_sequence_token(
402                                    SeqTokenType::Item,
403                                    len,
404                                    last_delimiter.pixel_data,
405                                );
406                                // items can be empty
407                                if len == Length(0) {
408                                    self.delimiter_check_pending = true;
409                                }
410                                Some(Ok(DataToken::ItemStart { len }))
411                            }
412                            SequenceItemHeader::ItemDelimiter => {
413                                // closed an item
414                                self.pop_seq_token();
415                                self.in_sequence = true;
416                                // sequences can end after an item delimiter
417                                self.delimiter_check_pending = true;
418                                Some(Ok(DataToken::ItemEnd))
419                            }
420                            SequenceItemHeader::SequenceDelimiter => {
421                                // closed a sequence
422                                self.pop_seq_token();
423                                self.in_sequence = false;
424                                // items can end after a nested sequence ends
425                                self.delimiter_check_pending = true;
426                                Some(Ok(DataToken::SequenceEnd))
427                            }
428                        }
429                    }
430                    Err(DecoderError::DecodeItemHeader {
431                        source: dcmnorm_encoding::decode::Error::ReadItemHeader { source, .. },
432                        ..
433                    }) if source.kind() == std::io::ErrorKind::UnexpectedEof
434                        && self.pop_seq_token().is_some_and(|t| t.pixel_data) =>
435                    {
436                        // Note: if `UnexpectedEof` was reached while inside a
437                        // PixelData Sequence, then we assume that
438                        // the end of a DICOM object was reached gracefully.
439                        self.hard_break = true;
440                        None
441                    }
442                    Err(e) => {
443                        self.hard_break = true;
444                        Some(Err(e).context(ReadItemHeaderSnafu))
445                    }
446                }
447            } else if let Some(SeqToken {
448                typ: SeqTokenType::Item,
449                pixel_data: true,
450                len,
451                ..
452            }) = self.seq_delimiters.last()
453            {
454                let len = match len.get() {
455                    Some(len) => len as usize,
456                    None => return Some(UndefinedItemLengthSnafu.fail()),
457                };
458
459                if self.offset_table_next {
460                    // offset table. Not pre-sized to `len` (an untrusted, file-controlled item
461                    // length) - `read_u32_to_vec` already grows this in bounded chunks internally,
462                    // and pre-allocating the full declared length here would defeat that.
463                    let mut offset_table = Vec::new();
464
465                    self.offset_table_next = false;
466
467                    // need to pop item delimiter on the next iteration
468                    self.delimiter_check_pending = true;
469
470                    Some(
471                        match self.parser.read_u32_to_vec(len as u32, &mut offset_table) {
472                            Ok(()) => Ok(DataToken::OffsetTable(offset_table)),
473                            Err(e) => Err(e).context(ReadItemValueSnafu { len: len as u32 }),
474                        },
475                    )
476                } else {
477                    // item value. Not pre-sized to `len` (untrusted, file-controlled) - see the
478                    // offset-table branch above for why.
479                    let mut value = Vec::new();
480
481                    // need to pop item delimiter on the next iteration
482                    self.delimiter_check_pending = true;
483                    Some(
484                        self.parser
485                            .read_to_vec(len as u32, &mut value)
486                            .map(|_| Ok(DataToken::ItemValue(value)))
487                            .unwrap_or_else(|e| {
488                                Err(e).context(ReadItemValueSnafu { len: len as u32 })
489                            }),
490                    )
491                }
492            } else if let Some(header) = self.last_header {
493                if header.is_encapsulated_pixeldata() {
494                    self.push_sequence_token(SeqTokenType::Sequence, Length::UNDEFINED, true);
495                    self.last_header = None;
496
497                    // encapsulated pixel data, expecting offset table
498                    match self.parser.decode_item_header() {
499                        Ok(header) => match header {
500                            SequenceItemHeader::Item { len } => {
501                                let len = match self.sanitize_length(len) {
502                                    Some(len) => len,
503                                    None => {
504                                        return Some(
505                                            InvalidItemLengthSnafu {
506                                                bytes_read: self.parser.position(),
507                                                len: len.0,
508                                            }
509                                            .fail(),
510                                        )
511                                    }
512                                };
513
514                                // entered a new item
515                                self.in_sequence = false;
516                                self.push_sequence_token(SeqTokenType::Item, len, true);
517                                // items can be empty
518                                if len == Length(0) {
519                                    self.delimiter_check_pending = true;
520                                } else {
521                                    self.offset_table_next = true;
522                                }
523                                Some(Ok(DataToken::ItemStart { len }))
524                            }
525                            SequenceItemHeader::SequenceDelimiter => {
526                                // empty pixel data
527                                self.pop_seq_token();
528                                self.in_sequence = false;
529                                Some(Ok(DataToken::SequenceEnd))
530                            }
531                            item => {
532                                self.hard_break = true;
533                                Some(UnexpectedItemTagSnafu { tag: item.tag() }.fail())
534                            }
535                        },
536                        Err(e) => {
537                            self.hard_break = true;
538                            Some(Err(e).context(ReadItemHeaderSnafu))
539                        }
540                    }
541                } else {
542                    // a plain element header was read, so a value is expected
543                    let value = match self.read_value(&header) {
544                        Ok(v) => v,
545                        Err(e) => {
546                            self.hard_break = true;
547                            self.last_header = None;
548                            return Some(Err(e));
549                        }
550                    };
551
552                    self.last_header = None;
553
554                    // sequences can end after this token
555                    self.delimiter_check_pending = true;
556
557                    Some(Ok(DataToken::PrimitiveValue(value)))
558                }
559            } else {
560                // a data element header or item delimiter is expected
561                match self.parser.decode_header() {
562                    Ok(DataElementHeader {
563                        tag,
564                        vr: VR::SQ,
565                        len,
566                    }) => {
567                        let len = match self.sanitize_length(len) {
568                            Some(len) => len,
569                            None => {
570                                return Some(
571                                    InvalidElementLengthSnafu {
572                                        tag,
573                                        len: len.0,
574                                        bytes_read: self.parser.position(),
575                                    }
576                                    .fail(),
577                                )
578                            }
579                        };
580
581                        self.in_sequence = true;
582                        self.push_sequence_token(SeqTokenType::Sequence, len, false);
583
584                        // sequences can end right after they start
585                        if len == Length(0) {
586                            self.delimiter_check_pending = true;
587                        }
588
589                        Some(Ok(DataToken::SequenceStart { tag, len }))
590                    }
591                    Ok(DataElementHeader {
592                        tag: Tag(0xFFFE, 0xE00D),
593                        ..
594                    }) if self.seq_delimiters.is_empty() => {
595                        // ignore delimiter, we are not in a sequence
596                        tracing::warn!(
597                            "Item delimitation item outside of a sequence in position {}",
598                            self.parser.position()
599                        );
600                        // return a new token by repeating the method again
601                        continue;
602                    }
603                    Ok(DataElementHeader {
604                        tag: Tag(0xFFFE, 0xE00D),
605                        ..
606                    }) => {
607                        self.in_sequence = true;
608                        // pop item delimiter
609                        self.pop_seq_token();
610                        // sequences can end after this token
611                        self.delimiter_check_pending = true;
612                        Some(Ok(DataToken::ItemEnd))
613                    }
614                    Ok(header) if header.is_encapsulated_pixeldata() => {
615                        // encapsulated pixel data conditions:
616                        // expect a sequence of pixel data fragments
617
618                        // save it for the next step
619                        self.last_header = Some(header);
620                        Some(Ok(DataToken::PixelSequenceStart))
621                    }
622                    Ok(header) if header.len.is_undefined() => {
623                        // treat other undefined length elements
624                        // as data set sequences,
625                        // discarding the VR in the process
626                        self.in_sequence = true;
627
628                        let DataElementHeader { tag, len, vr } = header;
629                        self.push_sequence_token(SeqTokenType::Sequence, len, false);
630                        if vr == VR::UN {
631                            // PS3.5 6.2.2: an undefined-length UN holds a sequence encoded in
632                            // Implicit VR Little Endian, whatever the outer transfer syntax.
633                            if let Some(token) = self.seq_delimiters.last_mut() {
634                                token.implicit_vr = true;
635                            }
636                            self.parser.enter_implicit_vr();
637                        }
638
639                        Some(Ok(DataToken::SequenceStart { tag, len }))
640                    }
641                    Ok(mut header) => {
642                        match self.sanitize_length(header.len) {
643                            Some(len) => header.len = len,
644                            None => {
645                                return Some(
646                                    InvalidElementLengthSnafu {
647                                        tag: header.tag,
648                                        len: header.len.0,
649                                        bytes_read: self.parser.position(),
650                                    }
651                                    .fail(),
652                                )
653                            }
654                        };
655
656                        // save it for the next step
657                        self.last_header = Some(header);
658                        Some(Ok(DataToken::ElementHeader(header)))
659                    }
660                    Err(DecoderError::DecodeElementHeader {
661                        source: dcmnorm_encoding::decode::Error::ReadHeaderTag { source, .. },
662                        ..
663                    }) if source.kind() == std::io::ErrorKind::UnexpectedEof => {
664                        // Note: if `UnexpectedEof` was reached while trying to read
665                        // an element tag, then we assume that
666                        // the end of a DICOM object was reached gracefully.
667                        // This approach is unlikely to consume trailing bytes,
668                        // but may ignore the current depth of the data set tree.
669                        self.hard_break = true;
670                        None
671                    }
672                    Err(e) => {
673                        self.hard_break = true;
674                        Some(Err(e).context(ReadHeaderSnafu))
675                    }
676                }
677            };
678        }
679    }
680}
681
682/// Where a skipped value sat in the data set: `position` is the value's first byte, relative
683/// to where this reader started reading (add the data set's own offset in the file for an
684/// absolute file offset), and `length` its byte length.
685#[derive(Debug, Clone, Copy, PartialEq, Eq)]
686pub struct SkippedValue {
687    pub position: u64,
688    pub length: u64,
689}
690
691/// Where one skipped encapsulated pixel data fragment's payload sat in the data set.
692#[derive(Debug, Clone, Copy, PartialEq, Eq)]
693pub struct SkippedFragment {
694    pub position: u64,
695    pub length: u32,
696}
697
698/// The Basic Offset Table and per-fragment locations of an encapsulated pixel data sequence
699/// skipped by [`DataSetReader::skip_pixel_sequence_indexed`].
700#[derive(Debug, Clone, PartialEq, Eq)]
701pub struct SkippedPixelSequence {
702    pub offset_table: Vec<u32>,
703    pub fragments: Vec<SkippedFragment>,
704    pub end_position: u64,
705}
706
707impl<S> DataSetReader<S>
708where
709    S: StatefulDecode,
710    S::Reader: Seek,
711{
712    /// Skip the value of the element whose `ElementHeader` token was just returned, seeking past
713    /// it instead of reading it - the alternative to taking the next (`PrimitiveValue`) token.
714    /// Leaves the reader in the same state as reading the value would, so iteration continues
715    /// with the next element. Only valid for a defined-length, non-sequence value.
716    ///
717    /// Seeking past the end of the source is not an error here (the reader then sees a clean
718    /// end of stream), so callers must check the returned range against the source's length.
719    pub fn skip_value(&mut self) -> Result<SkippedValue> {
720        let header = match (self.peek.as_ref(), self.last_header) {
721            (None, Some(header)) if !header.is_encapsulated_pixeldata() && !self.in_sequence => {
722                header
723            }
724            _ => {
725                return SkipNotApplicableSnafu {
726                    context: "no element value is next",
727                }
728                .fail()
729            }
730        };
731        let Some(length) = header.len.get() else {
732            return SkipNotApplicableSnafu {
733                context: "undefined-length value",
734            }
735            .fail();
736        };
737        let position = self.parser.position();
738        let result = self.parser.skip_bytes_seek(u64::from(length));
739        self.last_header = None;
740        if let Err(source) = result {
741            self.hard_break = true;
742            return Err(source).context(SkipValueSnafu {
743                len: u64::from(length),
744                tag: header.tag,
745            });
746        }
747        // as after reading a value: sequences/items can end after this element
748        self.delimiter_check_pending = true;
749        Ok(SkippedValue {
750            position,
751            length: u64::from(length),
752        })
753    }
754
755    /// Skip a whole encapsulated pixel data value, right after its `PixelSequenceStart` token
756    /// was returned: walks the fragment item headers and seeks past each fragment's bytes,
757    /// through the closing sequence delimiter. Leaves the reader as if the matching
758    /// `SequenceEnd` token had just been taken.
759    ///
760    /// The returned range covers the value as a DICOM JSON BulkDataURI references it: from the
761    /// first item header (the basic offset table item) up to, not including, the sequence
762    /// delimitation item. As with [`Self::skip_value`], callers must check that range against
763    /// the source's length.
764    pub fn skip_pixel_sequence(&mut self) -> Result<SkippedValue> {
765        match (self.peek.as_ref(), self.last_header) {
766            (None, Some(header)) if header.is_encapsulated_pixeldata() => {}
767            _ => {
768                return SkipNotApplicableSnafu {
769                    context: "no encapsulated pixel data is next",
770                }
771                .fail()
772            }
773        }
774        self.last_header = None;
775        let position = self.parser.position();
776        loop {
777            let item = self.parser.decode_item_header();
778            let item = match item {
779                Ok(item) => item,
780                Err(source) => {
781                    self.hard_break = true;
782                    return Err(source).context(ReadItemHeaderSnafu);
783                }
784            };
785            match item {
786                SequenceItemHeader::Item { len } => {
787                    let Some(len) = len.get() else {
788                        self.hard_break = true;
789                        return UndefinedItemLengthSnafu.fail();
790                    };
791                    if let Err(source) = self.parser.skip_bytes_seek(u64::from(len)) {
792                        self.hard_break = true;
793                        return Err(source).context(ReadItemValueSnafu { len });
794                    }
795                }
796                SequenceItemHeader::SequenceDelimiter => break,
797                other => {
798                    self.hard_break = true;
799                    return UnexpectedItemTagSnafu { tag: other.tag() }.fail();
800                }
801            }
802        }
803        // the delimiter itself (a bare 8-byte item header) is not part of the value
804        let length = self.parser.position() - 8 - position;
805        // as after a pixel sequence's SequenceEnd: enclosing items can end here
806        self.delimiter_check_pending = true;
807        Ok(SkippedValue { position, length })
808    }
809
810    /// Skip an encapsulated pixel data value right after `PixelSequenceStart`, reading only its
811    /// Basic Offset Table (the first item) and recording each subsequent fragment's offset and
812    /// length while seeking past fragment bytes.
813    pub fn skip_pixel_sequence_indexed(&mut self) -> Result<SkippedPixelSequence> {
814        match (self.peek.as_ref(), self.last_header) {
815            (None, Some(header)) if header.is_encapsulated_pixeldata() => {}
816            _ => {
817                return SkipNotApplicableSnafu {
818                    context: "no encapsulated pixel data is next",
819                }
820                .fail();
821            }
822        }
823        self.last_header = None;
824
825        // First item is always the Basic Offset Table.
826        let bot_item = match self.parser.decode_item_header() {
827            Ok(item) => item,
828            Err(source) => {
829                self.hard_break = true;
830                return Err(source).context(ReadItemHeaderSnafu);
831            }
832        };
833        let mut offset_table = Vec::new();
834        match bot_item {
835            SequenceItemHeader::Item { len } => {
836                let Some(len) = self.sanitize_length(len) else {
837                    self.hard_break = true;
838                    return InvalidItemLengthSnafu {
839                        bytes_read: self.parser.position(),
840                        len: len.0,
841                    }
842                    .fail();
843                };
844                let Some(len) = len.get() else {
845                    self.hard_break = true;
846                    return UndefinedItemLengthSnafu.fail();
847                };
848                if len > 0 {
849                    if let Err(source) = self.parser.read_u32_to_vec(len, &mut offset_table) {
850                        self.hard_break = true;
851                        return Err(source).context(ReadItemValueSnafu { len });
852                    }
853                }
854            }
855            other => {
856                self.hard_break = true;
857                return UnexpectedItemTagSnafu { tag: other.tag() }.fail();
858            }
859        }
860
861        let mut fragments = Vec::new();
862        loop {
863            let item = match self.parser.decode_item_header() {
864                Ok(item) => item,
865                Err(source) => {
866                    self.hard_break = true;
867                    return Err(source).context(ReadItemHeaderSnafu);
868                }
869            };
870            match item {
871                SequenceItemHeader::Item { len } => {
872                    let Some(len) = self.sanitize_length(len) else {
873                        self.hard_break = true;
874                        return InvalidItemLengthSnafu {
875                            bytes_read: self.parser.position(),
876                            len: len.0,
877                        }
878                        .fail();
879                    };
880                    let Some(len) = len.get() else {
881                        self.hard_break = true;
882                        return UndefinedItemLengthSnafu.fail();
883                    };
884                    let position = self.parser.position();
885                    if let Err(source) = self.parser.skip_bytes_seek(u64::from(len)) {
886                        self.hard_break = true;
887                        return Err(source).context(ReadItemValueSnafu { len });
888                    }
889                    fragments.push(SkippedFragment {
890                        position,
891                        length: len,
892                    });
893                }
894                SequenceItemHeader::SequenceDelimiter => break,
895                other => {
896                    self.hard_break = true;
897                    return UnexpectedItemTagSnafu { tag: other.tag() }.fail();
898                }
899            }
900        }
901
902        let end_position = self.parser.position();
903        self.delimiter_check_pending = true;
904        Ok(SkippedPixelSequence {
905            offset_table,
906            fragments,
907            end_position,
908        })
909    }
910}
911
912impl<S> DataSetReader<S>
913where
914    S: StatefulDecode,
915{
916    /// The decoder's position in the data set (bytes consumed from the source since the data
917    /// set started). Right after an `ElementHeader` token this is where the element's value
918    /// begins; right after a `PixelSequenceStart` token, where its first item header begins.
919    pub fn source_position(&self) -> u64 {
920        self.parser.position()
921    }
922
923    /// Peek the next token from the source by
924    /// reading a new token in the first call.
925    /// Subsequent calls to `peek` will return the same token
926    /// until another consumer method (such as `Iterator::next`)
927    /// is called.
928    pub fn peek(&mut self) -> Result<Option<&DataToken>> {
929        if self.peek.is_none() {
930            // try to read the next token
931            match self.next() {
932                None => return Ok(None),
933                Some(Err(e)) => return Err(e),
934                Some(Ok(token)) => {
935                    self.peek = Some(token);
936                }
937            }
938        }
939        Ok(self.peek.as_ref())
940    }
941
942    fn update_seq_delimiters(&mut self) -> Result<Option<DataToken>> {
943        if let Some(sd) = self.seq_delimiters.last() {
944            if let Some(len) = sd.len.get() {
945                let end_of_sequence = sd.base_offset + len as u64;
946                let bytes_read = self.parser.position();
947                match end_of_sequence.cmp(&bytes_read) {
948                    Ordering::Equal => {
949                        // end of delimiter, as indicated by the element's length
950
951                        let token = match sd.typ {
952                            SeqTokenType::Sequence => {
953                                self.in_sequence = false;
954                                DataToken::SequenceEnd
955                            }
956                            SeqTokenType::Item => {
957                                self.in_sequence = true;
958                                DataToken::ItemEnd
959                            }
960                        };
961                        self.pop_seq_token();
962                        return Ok(Some(token));
963                    }
964                    Ordering::Less => {
965                        return InconsistentSequenceEndSnafu {
966                            end_of_sequence,
967                            bytes_read,
968                        }
969                        .fail();
970                    }
971                    Ordering::Greater => {} // continue normally
972                }
973            }
974        }
975        self.delimiter_check_pending = false;
976        Ok(None)
977    }
978
979    #[inline]
980    fn push_sequence_token(&mut self, typ: SeqTokenType, len: Length, pixel_data: bool) {
981        self.seq_delimiters.push(SeqToken {
982            typ,
983            pixel_data,
984            len,
985            base_offset: self.parser.position(),
986            implicit_vr: false,
987        })
988    }
989
990    /// Pops the innermost sequence/item token, leaving Implicit VR decoding when it closes an
991    /// undefined-length `UN` sequence.
992    fn pop_seq_token(&mut self) -> Option<SeqToken> {
993        let token = self.seq_delimiters.pop()?;
994        if token.implicit_vr {
995            self.parser.leave_implicit_vr();
996        }
997        Some(token)
998    }
999
1000    fn read_value(&mut self, header: &DataElementHeader) -> Result<PrimitiveValue> {
1001        match self.options.value_read {
1002            ValueReadStrategy::Interpreted => self.parser.read_value(header),
1003            ValueReadStrategy::Preserved => self.parser.read_value_preserved(header),
1004            ValueReadStrategy::Raw => self.parser.read_value_bytes(header),
1005        }
1006        .context(ReadValueSnafu {
1007            len: header.len.0,
1008            tag: header.tag,
1009        })
1010    }
1011
1012    /// Check for a non-compliant length
1013    /// and handle it according to the current strategy.
1014    /// Returns `None` if the length cannot or should not be resolved.
1015    fn sanitize_length(&self, length: Length) -> Option<Length> {
1016        if length.is_defined() && length.0 & 1 != 0 {
1017            match self.options.odd_length {
1018                OddLengthStrategy::Accept => Some(length),
1019                OddLengthStrategy::NextEven => Some(length + 1),
1020                OddLengthStrategy::Fail => None,
1021            }
1022        } else {
1023            Some(length)
1024        }
1025    }
1026}
1027
1028#[cfg(test)]
1029mod tests {
1030    use super::{DataSetReader, DataToken, StatefulDecode};
1031    use crate::dataset::read::{DataSetReaderOptions, OddLengthStrategy};
1032    use crate::stateful::decode::StatefulDecoder;
1033    use dcmnorm_core::header::{DataElementHeader, Length};
1034    use dcmnorm_core::value::PrimitiveValue;
1035    use dcmnorm_core::{Tag, VR};
1036    use dcmnorm_encoding::decode::basic::LittleEndianBasicDecoder;
1037    use dcmnorm_encoding::decode::{
1038        explicit_le::ExplicitVRLittleEndianDecoder, implicit_le::ImplicitVRLittleEndianDecoder,
1039    };
1040    use dcmnorm_encoding::text::SpecificCharacterSet;
1041
1042    fn validate_read_data_implicit_vr<I>(data: &[u8], ground_truth: I)
1043    where
1044        I: IntoIterator<Item = DataToken>,
1045    {
1046        let mut cursor = data;
1047        let parser = StatefulDecoder::new(
1048            &mut cursor,
1049            ImplicitVRLittleEndianDecoder::default(),
1050            LittleEndianBasicDecoder,
1051            SpecificCharacterSet::default(),
1052        );
1053
1054        validate_read_data(data, parser, ground_truth)
1055    }
1056
1057    fn validate_read_data_explicit_vr<I>(data: &[u8], ground_truth: I)
1058    where
1059        I: IntoIterator<Item = DataToken>,
1060    {
1061        let mut cursor = data;
1062        let parser = StatefulDecoder::new(
1063            &mut cursor,
1064            ExplicitVRLittleEndianDecoder::default(),
1065            LittleEndianBasicDecoder,
1066            SpecificCharacterSet::default(),
1067        );
1068
1069        validate_read_data(data, parser, ground_truth)
1070    }
1071
1072    fn validate_read_data<I, D>(data: &[u8], parser: D, ground_truth: I)
1073    where
1074        I: IntoIterator<Item = DataToken>,
1075        D: StatefulDecode,
1076    {
1077        let dset_reader = DataSetReader::new(parser, Default::default());
1078        validate_data_set_reader(data, dset_reader, ground_truth);
1079    }
1080
1081    fn validate_data_set_reader<S, I>(
1082        data: &[u8],
1083        mut dset_reader: DataSetReader<S>,
1084        ground_truth: I,
1085    ) where
1086        S: StatefulDecode,
1087        I: IntoIterator<Item = DataToken>,
1088    {
1089        let iter = &mut dset_reader;
1090        let ground_truth = ground_truth.into_iter();
1091
1092        for gt_token in ground_truth {
1093            let token = iter
1094                .next()
1095                .expect("expecting more tokens from reader")
1096                .expect("should fetch the next token without an error");
1097            eprintln!("Next token: {token:2?} ; Expected: {gt_token:2?}");
1098            assert_eq!(
1099                token, gt_token,
1100                "Got token {token:2?} ; but expected {gt_token:2?}"
1101            );
1102        }
1103
1104        let extra: Vec<_> = iter.collect();
1105        assert_eq!(
1106            extra.len(), // we have already read all of them
1107            0,
1108            "extraneous tokens remaining: {extra:?}",
1109        );
1110        assert_eq!(
1111            dset_reader.parser.position(),
1112            data.len() as u64,
1113            "Decoder position did not match end of data",
1114        );
1115    }
1116
1117    #[test]
1118    fn read_sequence_explicit() {
1119        #[rustfmt::skip]
1120        static DATA: &[u8] = &[
1121            0x18, 0x00, 0x11, 0x60, // sequence tag: (0018,6011) SequenceOfUltrasoundRegions
1122            b'S', b'Q', // VR
1123            0x00, 0x00, // reserved
1124            0x2e, 0x00, 0x00, 0x00, // length: 28 + 18 = 46 (#= 2)
1125            // -- 12 --
1126            0xfe, 0xff, 0x00, 0xe0, // item start tag
1127            0x14, 0x00, 0x00, 0x00, // item length: 20 (#= 2)
1128            // -- 20 --
1129            0x18, 0x00, 0x12, 0x60, b'U', b'S', 0x02, 0x00, 0x01, 0x00, // (0018, 6012) RegionSpatialformat, len = 2, value = 1
1130            // -- 30 --
1131            0x18, 0x00, 0x14, 0x60, b'U', b'S', 0x02, 0x00, 0x02, 0x00, // (0018, 6012) RegionDataType, len = 2, value = 2
1132            // -- 40 --
1133            0xfe, 0xff, 0x00, 0xe0, // item start tag
1134            0x0a, 0x00, 0x00, 0x00, // item length: 10 (#= 1)
1135            // -- 48 --
1136            0x18, 0x00, 0x12, 0x60, b'U', b'S', 0x02, 0x00, 0x04, 0x00, // (0018, 6012) RegionSpatialformat, len = 2, value = 4
1137            // -- 58 --
1138            0x20, 0x00, 0x00, 0x40, b'L', b'T', 0x04, 0x00, // (0020,4000) ImageComments, len = 4
1139            b'T', b'E', b'S', b'T', // value = "TEST"
1140        ];
1141
1142        let ground_truth = vec![
1143            DataToken::SequenceStart {
1144                tag: Tag(0x0018, 0x6011),
1145                len: Length(46),
1146            },
1147            DataToken::ItemStart { len: Length(20) },
1148            DataToken::ElementHeader(DataElementHeader {
1149                tag: Tag(0x0018, 0x6012),
1150                vr: VR::US,
1151                len: Length(2),
1152            }),
1153            DataToken::PrimitiveValue(PrimitiveValue::U16([1].as_ref().into())),
1154            DataToken::ElementHeader(DataElementHeader {
1155                tag: Tag(0x0018, 0x6014),
1156                vr: VR::US,
1157                len: Length(2),
1158            }),
1159            DataToken::PrimitiveValue(PrimitiveValue::U16([2].as_ref().into())),
1160            DataToken::ItemEnd,
1161            DataToken::ItemStart { len: Length(10) },
1162            DataToken::ElementHeader(DataElementHeader {
1163                tag: Tag(0x0018, 0x6012),
1164                vr: VR::US,
1165                len: Length(2),
1166            }),
1167            DataToken::PrimitiveValue(PrimitiveValue::U16([4].as_ref().into())),
1168            DataToken::ItemEnd,
1169            DataToken::SequenceEnd,
1170            DataToken::ElementHeader(DataElementHeader {
1171                tag: Tag(0x0020, 0x4000),
1172                vr: VR::LT,
1173                len: Length(4),
1174            }),
1175            DataToken::PrimitiveValue(PrimitiveValue::Str("TEST".into())),
1176        ];
1177
1178        validate_read_data_explicit_vr(DATA, ground_truth);
1179    }
1180
1181    #[test]
1182    fn read_sequence_explicit_2() {
1183        static DATA: &[u8] = &[
1184            // SequenceStart: (0008,2218) ; len = 54 (#=3)
1185            0x08, 0x00, 0x18, 0x22, b'S', b'Q', 0x00, 0x00, 0x36, 0x00, 0x00, 0x00,
1186            // -- 12, --
1187            // ItemStart: len = 46
1188            0xfe, 0xff, 0x00, 0xe0, 0x2e, 0x00, 0x00, 0x00,
1189            // -- 20, --
1190            // ElementHeader: (0008,0100) CodeValue; len = 8
1191            0x08, 0x00, 0x00, 0x01, b'S', b'H', 0x08, 0x00, // PrimitiveValue
1192            0x54, 0x2d, 0x44, 0x31, 0x32, 0x31, 0x33, b' ',
1193            // -- 36, --
1194            // ElementHeader: (0008,0102) CodingSchemeDesignator; len = 4
1195            0x08, 0x00, 0x02, 0x01, b'S', b'H', 0x04, 0x00, // PrimitiveValue
1196            0x53, 0x52, 0x54, b' ',
1197            // -- 48, --
1198            // (0008,0104) CodeMeaning; len = 10
1199            0x08, 0x00, 0x04, 0x01, b'L', b'O', 0x0a, 0x00, // PrimitiveValue
1200            0x4a, 0x61, 0x77, b' ', 0x72, 0x65, 0x67, 0x69, 0x6f, 0x6e,
1201            // -- 66 --
1202            // SequenceStart: (0040,0555) AcquisitionContextSequence; len = 0
1203            0x40, 0x00, 0x55, 0x05, b'S', b'Q', 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
1204            // ElementHeader: (2050,0020) PresentationLUTShape; len = 8
1205            0x50, 0x20, 0x20, 0x00, b'C', b'S', 0x08, 0x00, // PrimitiveValue
1206            b'I', b'D', b'E', b'N', b'T', b'I', b'T', b'Y',
1207        ];
1208
1209        let ground_truth = vec![
1210            DataToken::SequenceStart {
1211                tag: Tag(0x0008, 0x2218),
1212                len: Length(54),
1213            },
1214            DataToken::ItemStart { len: Length(46) },
1215            DataToken::ElementHeader(DataElementHeader {
1216                tag: Tag(0x0008, 0x0100),
1217                vr: VR::SH,
1218                len: Length(8),
1219            }),
1220            DataToken::PrimitiveValue(PrimitiveValue::Strs(
1221                ["T-D1213 ".to_owned()].as_ref().into(),
1222            )),
1223            DataToken::ElementHeader(DataElementHeader {
1224                tag: Tag(0x0008, 0x0102),
1225                vr: VR::SH,
1226                len: Length(4),
1227            }),
1228            DataToken::PrimitiveValue(PrimitiveValue::Strs(["SRT ".to_owned()].as_ref().into())),
1229            DataToken::ElementHeader(DataElementHeader {
1230                tag: Tag(0x0008, 0x0104),
1231                vr: VR::LO,
1232                len: Length(10),
1233            }),
1234            DataToken::PrimitiveValue(PrimitiveValue::Strs(
1235                ["Jaw region".to_owned()].as_ref().into(),
1236            )),
1237            DataToken::ItemEnd,
1238            DataToken::SequenceEnd,
1239            DataToken::SequenceStart {
1240                tag: Tag(0x0040, 0x0555),
1241                len: Length(0),
1242            },
1243            DataToken::SequenceEnd,
1244            DataToken::ElementHeader(DataElementHeader {
1245                tag: Tag(0x2050, 0x0020),
1246                vr: VR::CS,
1247                len: Length(8),
1248            }),
1249            DataToken::PrimitiveValue(PrimitiveValue::Strs(
1250                ["IDENTITY".to_owned()].as_ref().into(),
1251            )),
1252        ];
1253
1254        validate_read_data_explicit_vr(DATA, ground_truth);
1255    }
1256
1257    #[test]
1258    fn read_empty_sequence_explicit() {
1259        static DATA: &[u8] = &[
1260            // SequenceStart: (0008,1032) ProcedureCodeSequence ; len = 0
1261            0x08, 0x00, 0x18, 0x22, // VR: SQ
1262            b'S', b'Q', // Reserved
1263            0x00, 0x00, // Length: 0
1264            0x00, 0x00, 0x00, 0x00,
1265        ];
1266
1267        let ground_truth = vec![
1268            DataToken::SequenceStart {
1269                tag: Tag(0x0008, 0x2218),
1270                len: Length(0),
1271            },
1272            DataToken::SequenceEnd,
1273        ];
1274
1275        validate_read_data_explicit_vr(DATA, ground_truth);
1276    }
1277
1278    /// Gracefully ignore a stray item end tag in the data set.
1279    #[test]
1280    fn ignore_trailing_item_delimitation_item() {
1281        static DATA: &[u8] = &[
1282            0x20, 0x00, 0x00, 0x40, b'L', b'T', 0x04,
1283            0x00, // (0020,4000) ImageComments, len = 4
1284            b'T', b'E', b'S', b'T', // value = "TEST"
1285            0xfe, 0xff, 0x0d, 0xe0, 0x00, 0x00, 0x00, 0x00, // item end
1286        ];
1287
1288        let ground_truth = vec![
1289            DataToken::ElementHeader(DataElementHeader {
1290                tag: Tag(0x0020, 0x4000),
1291                vr: VR::LT,
1292                len: Length(4),
1293            }),
1294            DataToken::PrimitiveValue(PrimitiveValue::Str("TEST".into())),
1295            // no item end
1296        ];
1297
1298        validate_read_data_explicit_vr(DATA, ground_truth);
1299    }
1300
1301    #[test]
1302    fn read_sequence_implicit() {
1303        #[rustfmt::skip]
1304        static DATA: &[u8] = &[
1305            0x18, 0x00, 0x11, 0x60, // sequence tag: (0018,6011) SequenceOfUltrasoundRegions
1306            b'S', b'Q', // VR
1307            0x00, 0x00, // reserved
1308            0xff, 0xff, 0xff, 0xff, // length: undefined
1309            // -- 12 --
1310            0xfe, 0xff, 0x00, 0xe0, // item start tag
1311            0xff, 0xff, 0xff, 0xff, // item length: undefined
1312            // -- 20 --
1313            0x18, 0x00, 0x12, 0x60, b'U', b'S', 0x02, 0x00, 0x01, 0x00, // (0018, 6012) RegionSpatialformat, len = 2, value = 1
1314            // -- 30 --
1315            0x18, 0x00, 0x14, 0x60, b'U', b'S', 0x02, 0x00, 0x02, 0x00, // (0018, 6012) RegionDataType, len = 2, value = 2
1316            // -- 40 --
1317            0xfe, 0xff, 0x0d, 0xe0, 0x00, 0x00, 0x00, 0x00, // item end
1318            // -- 48 --
1319            0xfe, 0xff, 0x00, 0xe0, // item start tag
1320            0xff, 0xff, 0xff, 0xff, // item length: undefined
1321            // -- 56 --
1322            0x18, 0x00, 0x12, 0x60, b'U', b'S', 0x02, 0x00, 0x04, 0x00, // (0018, 6012) RegionSpatialformat, len = 2, value = 4
1323            // -- 66 --
1324            0xfe, 0xff, 0x0d, 0xe0, 0x00, 0x00, 0x00, 0x00, // item end
1325            // -- 74 --
1326            0xfe, 0xff, 0xdd, 0xe0, 0x00, 0x00, 0x00, 0x00, // sequence end
1327            // -- 82 --
1328            0x20, 0x00, 0x00, 0x40, b'L', b'T', 0x04, 0x00, // (0020,4000) ImageComments, len = 4
1329            b'T', b'E', b'S', b'T', // value = "TEST"
1330        ];
1331
1332        let ground_truth = vec![
1333            DataToken::SequenceStart {
1334                tag: Tag(0x0018, 0x6011),
1335                len: Length::UNDEFINED,
1336            },
1337            DataToken::ItemStart {
1338                len: Length::UNDEFINED,
1339            },
1340            DataToken::ElementHeader(DataElementHeader {
1341                tag: Tag(0x0018, 0x6012),
1342                vr: VR::US,
1343                len: Length(2),
1344            }),
1345            DataToken::PrimitiveValue(PrimitiveValue::U16([1].as_ref().into())),
1346            DataToken::ElementHeader(DataElementHeader {
1347                tag: Tag(0x0018, 0x6014),
1348                vr: VR::US,
1349                len: Length(2),
1350            }),
1351            DataToken::PrimitiveValue(PrimitiveValue::U16([2].as_ref().into())),
1352            DataToken::ItemEnd,
1353            DataToken::ItemStart {
1354                len: Length::UNDEFINED,
1355            },
1356            DataToken::ElementHeader(DataElementHeader {
1357                tag: Tag(0x0018, 0x6012),
1358                vr: VR::US,
1359                len: Length(2),
1360            }),
1361            DataToken::PrimitiveValue(PrimitiveValue::U16([4].as_ref().into())),
1362            DataToken::ItemEnd,
1363            DataToken::SequenceEnd,
1364            DataToken::ElementHeader(DataElementHeader {
1365                tag: Tag(0x0020, 0x4000),
1366                vr: VR::LT,
1367                len: Length(4),
1368            }),
1369            DataToken::PrimitiveValue(PrimitiveValue::Str("TEST".into())),
1370        ];
1371
1372        validate_read_data_explicit_vr(DATA, ground_truth);
1373    }
1374
1375    #[test]
1376    fn read_implicit_len_sequence_implicit_vr_unknown() {
1377        #[rustfmt::skip]
1378        static DATA: &[u8] = &[
1379            0x33, 0x55, 0x33, 0x55, // sequence tag: (5533,5533) «private, unknown attribute»
1380            0xff, 0xff, 0xff, 0xff, // length: undefined
1381            // -- 8 --
1382            0xfe, 0xff, 0x00, 0xe0, // item begin
1383            0xff, 0xff, 0xff, 0xff, // length: undefined
1384            // -- 16 --
1385            0xfe, 0xff, 0x0d, 0xe0, // item end
1386            0x00, 0x00, 0x00, 0x00, // length is always zero
1387            // -- 24 --
1388            0xfe, 0xff, 0xdd, 0xe0,
1389            0x00, 0x00, 0x00, 0x00, // sequence end
1390            // -- 32 --
1391        ];
1392
1393        let ground_truth = vec![
1394            DataToken::SequenceStart {
1395                tag: Tag(0x5533, 0x5533),
1396                len: Length::UNDEFINED,
1397            },
1398            DataToken::ItemStart {
1399                len: Length::UNDEFINED,
1400            },
1401            DataToken::ItemEnd,
1402            DataToken::SequenceEnd,
1403        ];
1404
1405        validate_read_data_implicit_vr(DATA, ground_truth);
1406    }
1407
1408    /// pohcee/dcmnorm#26: an undefined-length UN element in an Explicit VR data set holds a
1409    /// sequence encoded in Implicit VR Little Endian (PS3.5 6.2.2); the element after it is
1410    /// Explicit VR again.
1411    #[test]
1412    fn read_undefined_length_un_as_implicit_vr_sequence_in_explicit_vr() {
1413        #[rustfmt::skip]
1414        static DATA: &[u8] = &[
1415            0x11, 0x00, 0x10, 0x10, // (0011,1010) private
1416            b'U', b'N', 0x00, 0x00, // VR UN, reserved
1417            0xff, 0xff, 0xff, 0xff, // length: undefined
1418            // -- 12 --
1419            0xfe, 0xff, 0x00, 0xe0, // item begin
1420            0x0c, 0x00, 0x00, 0x00, // item length 12
1421            // -- 20 -- implicit VR: (0008,103E) LO, length 4, "TEST"
1422            0x08, 0x00, 0x3e, 0x10,
1423            0x04, 0x00, 0x00, 0x00,
1424            b'T', b'E', b'S', b'T',
1425            // -- 32 --
1426            0xfe, 0xff, 0xdd, 0xe0,
1427            0x00, 0x00, 0x00, 0x00, // sequence end
1428            // -- 40 -- explicit VR again: (0020,000D) UI, length 2
1429            0x20, 0x00, 0x0d, 0x00,
1430            b'U', b'I', 0x02, 0x00,
1431            b'1', 0x00,
1432        ];
1433
1434        let ground_truth = vec![
1435            DataToken::SequenceStart {
1436                tag: Tag(0x0011, 0x1010),
1437                len: Length::UNDEFINED,
1438            },
1439            DataToken::ItemStart { len: Length(12) },
1440            DataToken::ElementHeader(DataElementHeader {
1441                tag: Tag(0x0008, 0x103E),
1442                vr: VR::LO,
1443                len: Length(4),
1444            }),
1445            DataToken::PrimitiveValue(PrimitiveValue::Strs(["TEST".to_owned()].as_ref().into())),
1446            DataToken::ItemEnd,
1447            DataToken::SequenceEnd,
1448            DataToken::ElementHeader(DataElementHeader {
1449                tag: Tag(0x0020, 0x000D),
1450                vr: VR::UI,
1451                len: Length(2),
1452            }),
1453            DataToken::PrimitiveValue(PrimitiveValue::Strs(["1".to_owned()].as_ref().into())),
1454        ];
1455
1456        validate_read_data_explicit_vr(DATA, ground_truth);
1457    }
1458
1459    #[test]
1460    fn read_encapsulated_pixeldata() {
1461        #[rustfmt::skip]
1462        static DATA: &[u8] = &[
1463            0xe0, 0x7f, 0x10, 0x00, // (7FE0, 0010) PixelData
1464            b'O', b'B', // VR 
1465            0x00, 0x00, // reserved
1466            0xff, 0xff, 0xff, 0xff, // length: undefined
1467            // -- 12 -- Basic offset table
1468            0xfe, 0xff, 0x00, 0xe0, // item start tag
1469            0x00, 0x00, 0x00, 0x00, // item length: 0
1470            // -- 20 -- First fragment of pixel data
1471            0xfe, 0xff, 0x00, 0xe0, // item start tag
1472            0x20, 0x00, 0x00, 0x00, // item length: 32
1473            // -- 28 -- Compressed Fragment
1474            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1475            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1476            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1477            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1478            // -- 60 -- End of pixel data
1479            0xfe, 0xff, 0xdd, 0xe0, // sequence end tag
1480            0x00, 0x00, 0x00, 0x00,
1481            // -- 68 -- padding
1482            0xfc, 0xff, 0xfc, 0xff, // (fffc,fffc) DataSetTrailingPadding
1483            b'O', b'B', // VR
1484            0x00, 0x00, // reserved
1485            0x08, 0x00, 0x00, 0x00, // length: 8
1486            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
1487        ];
1488
1489        let ground_truth = vec![
1490            DataToken::PixelSequenceStart,
1491            DataToken::ItemStart { len: Length(0) },
1492            DataToken::ItemEnd,
1493            DataToken::ItemStart { len: Length(32) },
1494            DataToken::ItemValue(vec![0x99; 32]),
1495            DataToken::ItemEnd,
1496            DataToken::SequenceEnd,
1497            DataToken::ElementHeader(DataElementHeader::new(
1498                Tag(0xfffc, 0xfffc),
1499                VR::OB,
1500                Length(8),
1501            )),
1502            DataToken::PrimitiveValue(PrimitiveValue::U8([0x00; 8].as_ref().into())),
1503        ];
1504
1505        validate_read_data_explicit_vr(DATA, ground_truth);
1506    }
1507
1508    #[test]
1509    fn read_encapsulated_pixeldata_with_offset_table() {
1510        #[rustfmt::skip]
1511        static DATA: &[u8] = &[
1512            0xe0, 0x7f, 0x10, 0x00, // (7FE0, 0010) PixelData
1513            b'O', b'B', // VR 
1514            0x00, 0x00, // reserved
1515            0xff, 0xff, 0xff, 0xff, // length: undefined
1516            // -- 12 -- Basic offset table
1517            0xfe, 0xff, 0x00, 0xe0, // item start tag
1518            0x04, 0x00, 0x00, 0x00, // item length: 4
1519            // -- 20 -- item value
1520            0x10, 0x00, 0x00, 0x00, // 16
1521            // -- 24 -- First fragment of pixel data
1522            0xfe, 0xff, 0x00, 0xe0, // item start tag
1523            0x20, 0x00, 0x00, 0x00, // item length: 32
1524            // -- 32 -- Compressed Fragment
1525            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1526            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1527            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1528            0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99, 0x99,
1529            // -- 60 -- End of pixel data
1530            0xfe, 0xff, 0xdd, 0xe0, // sequence end tag
1531            0x00, 0x00, 0x00, 0x00,
1532            // -- 68 -- padding
1533            0xfc, 0xff, 0xfc, 0xff, // (fffc,fffc) DataSetTrailingPadding
1534            b'O', b'B', // VR
1535            0x00, 0x00, // reserved
1536            0x08, 0x00, 0x00, 0x00, // length: 8
1537            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
1538        ];
1539
1540        let ground_truth = vec![
1541            DataToken::PixelSequenceStart,
1542            DataToken::ItemStart { len: Length(4) },
1543            DataToken::OffsetTable(vec![16]),
1544            DataToken::ItemEnd,
1545            DataToken::ItemStart { len: Length(32) },
1546            DataToken::ItemValue(vec![0x99; 32]),
1547            DataToken::ItemEnd,
1548            DataToken::SequenceEnd,
1549            DataToken::ElementHeader(DataElementHeader::new(
1550                Tag(0xfffc, 0xfffc),
1551                VR::OB,
1552                Length(8),
1553            )),
1554            DataToken::PrimitiveValue(PrimitiveValue::U8([0x00; 8].as_ref().into())),
1555        ];
1556
1557        validate_read_data_explicit_vr(DATA, ground_truth);
1558    }
1559
1560    #[test]
1561    fn read_dataset_in_dataset() {
1562        #[rustfmt::skip]
1563        const DATA: &[u8; 138] = &[
1564            // 0: (2001, 9000) private sequence
1565            0x01, 0x20, 0x00, 0x90, //
1566            // length: undefined
1567            0xFF, 0xFF, 0xFF, 0xFF, //
1568            // 8: Item start
1569            0xFE, 0xFF, 0x00, 0xE0, //
1570            // Item length explicit (114 bytes)
1571            0x72, 0x00, 0x00, 0x00, //
1572            // 16: (0008,1115) ReferencedSeriesSequence
1573            0x08, 0x00, 0x15, 0x11, //
1574            // length: undefined
1575            0xFF, 0xFF, 0xFF, 0xFF, //
1576            // 24: Item start
1577            0xFE, 0xFF, 0x00, 0xE0, //
1578            // Item length undefined
1579            0xFF, 0xFF, 0xFF, 0xFF, //
1580            // 32: (0008,1140) ReferencedImageSequence
1581            0x08, 0x00, 0x40, 0x11, //
1582            // length: undefined
1583            0xFF, 0xFF, 0xFF, 0xFF, //
1584            // 40: Item start
1585            0xFE, 0xFF, 0x00, 0xE0, //
1586            // Item length undefined
1587            0xFF, 0xFF, 0xFF, 0xFF, //
1588            // 48: (0008,1150) ReferencedSOPClassUID
1589            0x08, 0x00, 0x50, 0x11, //
1590            // length: 26
1591            0x1a, 0x00, 0x00, 0x00, //
1592            // Value: "1.2.840.10008.5.1.4.1.1.7\0" (SecondaryCaptureImageStorage)
1593            b'1', b'.', b'2', b'.', b'8', b'4', b'0', b'.', b'1', b'0', b'0', b'0', b'8', b'.',
1594            b'5', b'.', b'1', b'.', b'4', b'.', b'1', b'.', b'1', b'.', b'7', b'\0',
1595            // 82: Item End (ReferencedImageSequence)
1596            0xFE, 0xFF, 0x0D, 0xE0, //
1597            0x00, 0x00, 0x00, 0x00, //
1598            // 90: Sequence End (ReferencedImageSequence)
1599            0xFE, 0xFF, 0xDD, 0xE0, //
1600            0x00, 0x00, 0x00, 0x00, //
1601            // 98: Item End (ReferencedSeriesSequence)
1602            0xFE, 0xFF, 0x0D, 0xE0, //
1603            0x00, 0x00, 0x00, 0x00, //
1604            // 106: Sequence End (ReferencedSeriesSequence)
1605            0xFE, 0xFF, 0xDD, 0xE0, //
1606            0x00, 0x00, 0x00, 0x00, //
1607            // 114: (2050,0020) PresentationLUTShape (CS)
1608            0x50, 0x20, 0x20, 0x00, //
1609            // length: 8
1610            0x08, 0x00, 0x00, 0x00, //
1611            b'I', b'D', b'E', b'N', b'T', b'I', b'T', b'Y', //
1612            // 130: Sequence end
1613            0xFE, 0xFF, 0xDD, 0xE0, //
1614            0x00, 0x00, 0x00, 0x00, //
1615        ];
1616
1617        let ground_truth = vec![
1618            DataToken::SequenceStart {
1619                tag: Tag(0x2001, 0x9000),
1620                len: Length::UNDEFINED,
1621            },
1622            DataToken::ItemStart { len: Length(114) },
1623            DataToken::SequenceStart {
1624                tag: Tag(0x0008, 0x1115),
1625                len: Length::UNDEFINED,
1626            },
1627            DataToken::ItemStart {
1628                len: Length::UNDEFINED,
1629            },
1630            DataToken::SequenceStart {
1631                tag: Tag(0x0008, 0x1140),
1632                len: Length::UNDEFINED,
1633            },
1634            DataToken::ItemStart {
1635                len: Length::UNDEFINED,
1636            },
1637            DataToken::ElementHeader(DataElementHeader {
1638                tag: Tag(0x0008, 0x1150),
1639                vr: VR::UI,
1640                len: Length(26),
1641            }),
1642            DataToken::PrimitiveValue(PrimitiveValue::from("1.2.840.10008.5.1.4.1.1.7\0")),
1643            DataToken::ItemEnd,
1644            DataToken::SequenceEnd,
1645            DataToken::ItemEnd,
1646            DataToken::SequenceEnd,
1647            DataToken::ElementHeader(DataElementHeader {
1648                tag: Tag(0x2050, 0x0020),
1649                vr: VR::CS,
1650                len: Length(8),
1651            }),
1652            DataToken::PrimitiveValue(PrimitiveValue::from("IDENTITY")),
1653            DataToken::ItemEnd, // inserted automatically
1654            DataToken::SequenceEnd,
1655        ];
1656
1657        validate_read_data_implicit_vr(DATA, ground_truth);
1658    }
1659
1660    #[test]
1661    fn peek_data_elements() {
1662        #[rustfmt::skip]
1663        static DATA: &[u8] = &[
1664            0x18, 0x00, 0x11, 0x60, // sequence tag: (0018,6011) SequenceOfUltrasoundRegions
1665            b'S', b'Q', // VR
1666            0x00, 0x00, // reserved
1667            0xff, 0xff, 0xff, 0xff, // length: undefined
1668            // -- 12 --
1669            0xfe, 0xff, 0xdd, 0xe0, 0x00, 0x00, 0x00, 0x00, // sequence end
1670            // -- 82 --
1671            0x20, 0x00, 0x00, 0x40, b'L', b'T', 0x04, 0x00, // (0020,4000) ImageComments, len = 4
1672            b'T', b'E', b'S', b'T', // value = "TEST"
1673        ];
1674
1675        let ground_truth = [
1676            DataToken::SequenceStart {
1677                tag: Tag(0x0018, 0x6011),
1678                len: Length::UNDEFINED,
1679            },
1680            DataToken::SequenceEnd,
1681            DataToken::ElementHeader(DataElementHeader {
1682                tag: Tag(0x0020, 0x4000),
1683                vr: VR::LT,
1684                len: Length(4),
1685            }),
1686            DataToken::PrimitiveValue(PrimitiveValue::Str("TEST".into())),
1687        ];
1688
1689        let mut cursor = DATA;
1690        let parser = StatefulDecoder::new(
1691            &mut cursor,
1692            ExplicitVRLittleEndianDecoder::default(),
1693            LittleEndianBasicDecoder,
1694            SpecificCharacterSet::default(),
1695        );
1696        let mut dset_reader = DataSetReader::new(parser, Default::default());
1697
1698        let iter = &mut dset_reader;
1699
1700        // peek at first token
1701        let token = iter.peek().expect("should peek first token OK");
1702        assert_eq!(token, Some(&ground_truth[0]));
1703
1704        // peeking multiple times gives the same result
1705        let token = iter.peek().expect("should peek first token again OK");
1706        assert_eq!(token, Some(&ground_truth[0]));
1707
1708        // Using `next` give us the same token
1709        let token = iter
1710            .next()
1711            .expect("expected token")
1712            .expect("should read token peeked OK");
1713        assert_eq!(&token, &ground_truth[0]);
1714
1715        // read some more tokens
1716
1717        // sequence end
1718        let token = iter.next().unwrap().unwrap();
1719        assert_eq!(&token, &ground_truth[1]);
1720        // data element header
1721        let token = iter.next().unwrap().unwrap();
1722        assert_eq!(&token, &ground_truth[2]);
1723
1724        // peek string value
1725        let token = iter.peek().unwrap();
1726        assert_eq!(token, Some(&ground_truth[3]));
1727        // peek it again
1728        let token = iter.peek().unwrap();
1729        assert_eq!(token, Some(&ground_truth[3]));
1730        // then read it
1731        let token = iter.next().unwrap().unwrap();
1732        assert_eq!(&token, &ground_truth[3]);
1733
1734        // finished reading, peek should return None
1735        assert!(iter.peek().unwrap().is_none());
1736    }
1737
1738    #[test]
1739    fn read_pixel_sequence_bad_item_end() {
1740        #[rustfmt::skip]
1741        static DATA: &[u8] = &[
1742            0xe0, 0x7f, 0x10, 0x00, // (7FE0, 0010) PixelData
1743            b'O', b'B', // VR 
1744            0x00, 0x00, // reserved
1745            0xff, 0xff, 0xff, 0xff, // length: undefined
1746            // -- 12 --
1747            0xfe, 0xff, 0x00, 0xe0, // item start tag
1748            0x00, 0x00, 0x00, 0x00, // item length: 0
1749            // -- 20 --
1750            0xfe, 0xff, 0x0d, 0xe0, // item end
1751            0x00, 0x00, 0x00, 0x00, // length is always zero
1752            // -- 28 --
1753            0xfe, 0xff, 0x0d, 0xe0, // another item end (bad)
1754            0x00, 0x00, 0x00, 0x00, //
1755            // -- 36 --
1756            0xfe, 0xff, 0x00, 0xe0, // another item start
1757            0x00, 0x00, 0x00, 0x00, // item length: 0
1758        ];
1759
1760        let mut cursor = DATA;
1761        let parser = StatefulDecoder::new(
1762            &mut cursor,
1763            ExplicitVRLittleEndianDecoder::default(),
1764            LittleEndianBasicDecoder,
1765            SpecificCharacterSet::default(),
1766        );
1767        let mut dset_reader = DataSetReader::new(parser, Default::default());
1768
1769        let token_res = (&mut dset_reader).collect::<Result<Vec<_>, _>>();
1770        dbg!(&token_res);
1771        assert!(token_res.is_err());
1772    }
1773
1774    #[test]
1775    fn read_odd_length_element() {
1776        #[rustfmt::skip]
1777        static DATA: &[u8] = &[
1778            0x08, 0x00, 0x16, 0x00, // (0008,0016) SOPClassUID
1779            b'U', b'I', // VR
1780            0x0b, 0x00, // len = 11
1781            b'1', b'.', b'2', b'.', b'8', b'4', b'0', b'.', b'1', b'0', b'0',
1782            0x00, // padding
1783        ];
1784
1785        let ground_truth = vec![
1786            DataToken::ElementHeader(DataElementHeader {
1787                tag: Tag(0x0008, 0x0016),
1788                vr: VR::UI,
1789                len: Length(12),
1790            }),
1791            DataToken::PrimitiveValue(PrimitiveValue::from("1.2.840.100\0")),
1792        ];
1793
1794        // strategy: assume next even
1795
1796        let mut cursor = DATA;
1797        let parser = StatefulDecoder::new(
1798            &mut cursor,
1799            ExplicitVRLittleEndianDecoder::default(),
1800            LittleEndianBasicDecoder,
1801            SpecificCharacterSet::default(),
1802        );
1803        let dset_reader = DataSetReader::new(
1804            parser,
1805            DataSetReaderOptions {
1806                odd_length: OddLengthStrategy::NextEven,
1807                ..Default::default()
1808            },
1809        );
1810
1811        validate_data_set_reader(DATA, dset_reader, ground_truth);
1812
1813        // strategy: fail
1814
1815        let mut cursor = DATA;
1816        let parser = StatefulDecoder::new(
1817            &mut cursor,
1818            ExplicitVRLittleEndianDecoder::default(),
1819            LittleEndianBasicDecoder,
1820            SpecificCharacterSet::default(),
1821        );
1822        let dset_reader = DataSetReader::new(
1823            parser,
1824            DataSetReaderOptions {
1825                odd_length: OddLengthStrategy::Fail,
1826                ..Default::default()
1827            },
1828        );
1829
1830        let mut tokens = dset_reader.into_iter();
1831        let token = tokens.next();
1832
1833        assert!(
1834            matches!(
1835                token,
1836                Some(Err(super::Error::InvalidElementLength {
1837                    tag: Tag(0x0008, 0x0016),
1838                    len: 11,
1839                    bytes_read: 8,
1840                })),
1841            ),
1842            "got: {:?}",
1843            token
1844        );
1845    }
1846
1847    /// Regression test for upstream dicom-rs 8c98b8a8 (LOOP_1 of Enet4/dicom-rs#768): stray item
1848    /// delimitation items outside of any sequence are skipped, and the reader used to skip each
1849    /// one by calling `next()` recursively. A crafted file with enough of them overflowed the stack
1850    /// and aborted the whole process. Run on a thread with a deliberately small stack so a
1851    /// recursive implementation fails deterministically.
1852    #[test]
1853    fn many_stray_item_delimiters_do_not_overflow_the_stack() {
1854        const STRAY_DELIMITERS: usize = 200_000;
1855        let mut data = Vec::with_capacity(STRAY_DELIMITERS * 8 + 16);
1856        for _ in 0..STRAY_DELIMITERS {
1857            // (FFFE,E00D) ItemDelimitationItem, length 0
1858            data.extend_from_slice(&[0xFE, 0xFF, 0x0D, 0xE0, 0x00, 0x00, 0x00, 0x00]);
1859        }
1860        // (0010,0010) PN "Doe^John"
1861        data.extend_from_slice(&[0x10, 0x00, 0x10, 0x00, b'P', b'N', 0x08, 0x00]);
1862        data.extend_from_slice(b"Doe^John");
1863
1864        let handle = std::thread::Builder::new()
1865            .stack_size(256 * 1024)
1866            .spawn(move || {
1867                validate_read_data_explicit_vr(
1868                    &data,
1869                    vec![
1870                        DataToken::ElementHeader(DataElementHeader {
1871                            tag: Tag(0x0010, 0x0010),
1872                            vr: VR::PN,
1873                            len: Length(8),
1874                        }),
1875                        DataToken::PrimitiveValue(PrimitiveValue::Strs(
1876                            ["Doe^John".to_owned()].as_ref().into(),
1877                        )),
1878                    ],
1879                );
1880            })
1881            .expect("spawning the test thread should succeed");
1882        handle
1883            .join()
1884            .expect("reading the data set should not panic");
1885    }
1886}