pydicom.encaps.encapsulate¶

pydicom.encaps.encapsulate(frames: list[bytes], fragments_per_frame: int = 1, has_bot: bool = True) → bytes[source]¶

Return encapsulated frames.

Added in version 1.2.

When using a compressed transfer syntax (such as RLE Lossless or one of JPEG formats) then any Pixel Data must be encapsulated:

# Where `frame1`, `frame2` are single frames that have been encoded
# using the corresponding compression method to Transfer Syntax UID
ds.PixelData = encapsulate([frame1, frame2, ...])

For multi-frame data each frame must be encoded separately and then all encoded frames encapsulated together.

When many large frames are to be encapsulated, the total length of encapsulated data may exceed the maximum length available with the Basic Offset Table (2**31 - 1 bytes). Under these circumstances you can:

Pass has_bot=False to encapsulate()
Use encapsulate_extended() and add the Extended Offset Table elements to your dataset (recommended)

Data will be encapsulated with a Basic Offset Table Item at the beginning, then one or more fragment items. Each item will be of even length and the final fragment of each frame may be padded with 0x00 if required.

Parameters:

frames (list of bytes) – The frame data to encapsulate, one frame per item.
fragments_per_frame (int, optional) – The number of fragments to use for each frame (default 1).
has_bot (bool, optional) – True to include values in the Basic Offset Table, False otherwise (default True). If fragments_per_frame is not 1 then it’s strongly recommended that this be True.

Returns:

The encapsulated pixel data.

Return type:

bytes

References

DICOM Standard, Part 5, Section 7.5 and Annex A.4