def read_item(fp: DicomFileLike) -> Optional[bytes]:
"""Read and return a single Item in the fragmented data stream.
Parameters
----------
fp : filebase.DicomIO
The file-like to read the item from.
Returns
-------
bytes
The Item's raw bytes.
"""
logger = pydicom.config.logger
try:
tag = fp.read_tag()
# already read delimiter before passing data here
# so should just run out
except EOFError:
return None
# No more items, time for sequence to stop reading
if tag == SequenceDelimiterTag:
length = fp.read_UL()
logger.debug(
"%04x: Sequence Delimiter, length 0x%x",
fp.tell() - 8,
length)
if length != 0:
logger.warning(
"Expected 0x00000000 after delimiter, found 0x%x,"
" at data position 0x%x",
length,
fp.tell() - 4)
return None
if tag != ItemTag:
logger.warning(
"Expected Item with tag %s at data position 0x%x",
ItemTag,
fp.tell() - 4)
length = fp.read_UL()
else:
length = fp.read_UL()
logger.debug(
"%04x: Item, length 0x%x",
fp.tell() - 8,
length)
if length == 0xFFFFFFFF:
raise ValueError(
"Encapsulated data fragment had Undefined Length"
" at data position 0x%x" % (fp.tell() - 4, ))
item_data = fp.read(length)
return item_data
def get_nr_fragments(fp: DicomFileLike) -> int:
"""Return the number of fragments in `fp`.
.. versionadded:: 1.4
"""
if not fp.is_little_endian:
raise ValueError("'fp.is_little_endian' must be True")
nr_fragments = 0
start = fp.tell()
while True:
try:
tag = Tag(fp.read_tag())
except EOFError:
break
if tag == 0xFFFEE000:
# Item
length = fp.read_UL()
if length == 0xFFFFFFFF:
raise ValueError(
f"Undefined item length at offset {fp.tell() - 4} when "
"parsing the encapsulated pixel data fragments")
fp.seek(length, 1)
nr_fragments += 1
elif tag == 0xFFFEE0DD:
# Sequence Delimiter
break
else:
raise ValueError(
f"Unexpected tag '{tag}' at offset {fp.tell() - 4} when "
"parsing the encapsulated pixel data fragment items")
fp.seek(start)
return nr_fragments
def generate_pixel_data_fragment(
fp: DicomFileLike) -> Generator[bytes, None, None]:
"""Yield the encapsulated pixel data fragments.
For compressed (encapsulated) Transfer Syntaxes, the (7FE0,0010) *Pixel
Data* element is encoded in an encapsulated format.
**Encapsulation**
The encoded pixel data stream is fragmented into one or more Items. The
stream may represent a single or multi-frame image.
Each *Data Stream Fragment* shall have tag of (FFFE,E000), followed by a 4
byte *Item Length* field encoding the explicit number of bytes in the Item.
All Items containing an encoded fragment shall have an even number of bytes
greater than or equal to 2, with the last fragment being padded if
necessary.
The first Item in the Sequence of Items shall be a 'Basic Offset Table',
however the Basic Offset Table item value is not required to be present.
It is assumed that the Basic Offset Table item has already been read prior
to calling this function (and that `fp` is positioned past this item).
The remaining items in the Sequence of Items are the pixel data fragments
and it is these items that will be read and returned by this function.
The Sequence of Items is terminated by a (FFFE,E0DD) *Sequence Delimiter
Item* with an Item Length field of value ``0x00000000``. The presence
or absence of the *Sequence Delimiter Item* in `fp` has no effect on the
returned fragments.
*Encoding*
The encoding of the data shall be little endian.
Parameters
----------
fp : filebase.DicomFileLike
The encoded (7FE0,0010) *Pixel Data* element value, positioned at the
start of the item tag for the first item after the Basic Offset Table
item. ``fp.is_little_endian`` should be set to ``True``.
Yields
------
bytes
A pixel data fragment.
Raises
------
ValueError
If the data contains an item with an undefined length or an unknown
tag.
References
----------
DICOM Standard Part 5, :dcm:`Annex A.4 <part05/sect_A.4.html>`
"""
if not fp.is_little_endian:
raise ValueError("'fp.is_little_endian' must be True")
# We should be positioned at the start of the Item Tag for the first
# fragment after the Basic Offset Table
while True:
try:
tag = Tag(fp.read_tag())
except EOFError:
break
if tag == 0xFFFEE000:
# Item
length = fp.read_UL()
if length == 0xFFFFFFFF:
raise ValueError(
f"Undefined item length at offset {fp.tell() - 4} when "
"parsing the encapsulated pixel data fragments")
yield fp.read(length)
elif tag == 0xFFFEE0DD:
# Sequence Delimiter
# Behave nicely and rewind back to the end of the items
fp.seek(-4, 1)
break
else:
raise ValueError(
f"Unexpected tag '{tag}' at offset {fp.tell() - 4} when "
"parsing the encapsulated pixel data fragment items")
def get_frame_offsets(fp: DicomFileLike) -> Tuple[bool, List[int]]:
"""Return a list of the fragment offsets from the Basic Offset Table.
**Basic Offset Table**
The Basic Offset Table Item must be present and have a tag (FFFE,E000) and
a length, however it may or may not have a value.
Basic Offset Table with no value
::
Item Tag | Length |
FE FF 00 E0 00 00 00 00
Basic Offset Table with value (2 frames)
::
Item Tag | Length | Offset 1 | Offset 2 |
FE FF 00 E0 08 00 00 00 00 00 00 00 10 00 00 00
For single or multi-frame images with only one frame, the Basic Offset
Table may or may not have a value. When it has no value then its length
shall be ``0x00000000``.
For multi-frame images with more than one frame, the Basic Offset Table
should have a value containing concatenated 32-bit unsigned integer values
that are the byte offsets to the first byte of the Item tag of the first
fragment of each frame as measured from the first byte of the first item
tag following the Basic Offset Table Item.
All decoders, both for single and multi-frame images should accept both
an empty Basic Offset Table and one containing offset values.
.. versionchanged:: 1.4
Changed to return (is BOT empty, list of offsets).
Parameters
----------
fp : filebase.DicomFileLike
The encapsulated pixel data positioned at the start of the Basic Offset
Table. ``fp.is_little_endian`` should be set to ``True``.
Returns
-------
bool, list of int
Whether or not the BOT is empty, and a list of the byte offsets
to the first fragment of each frame, as measured from the start of the
first item following the Basic Offset Table item.
Raises
------
ValueError
If the Basic Offset Table item's tag is not (FFEE,E000) or if the
length in bytes of the item's value is not a multiple of 4.
References
----------
DICOM Standard, Part 5, :dcm:`Annex A.4 <part05/sect_A.4.html>`
"""
if not fp.is_little_endian:
raise ValueError("'fp.is_little_endian' must be True")
tag = Tag(fp.read_tag())
if tag != 0xfffee000:
raise ValueError(
f"Unexpected tag '{tag}' when parsing the Basic Table Offset item")
length = fp.read_UL()
if length % 4:
raise ValueError(
"The length of the Basic Offset Table item is not a multiple of 4")
offsets = []
# Always return at least a 0 offset
if length == 0:
offsets.append(0)
for ii in range(length // 4):
offsets.append(fp.read_UL())
return bool(length), offsets
