# Bulk Data Encapsulation Utilities (`pydicom.encaps`)

Functions for parsing and applying encapsulation to bulk data elements such as (7FE0,0010) Pixel Data.

## Parsing Encapsulated Data

`decode_data_sequence`(data) | Read encapsulated data and return a list of bytes.
`defragment_data`(data) | Read encapsulated data and return the fragments as one continuous bytes.
`generate_pixel_data`(bytestream[, nr_frames]) | Yield an encapsulated pixel data frame.
`generate_pixel_data_fragment`(fp) | Yield the encapsulated pixel data fragments.
`generate_pixel_data_frame`(bytestream[, ...]) | Yield complete frames from buffer as `bytes`.
`get_frame_offsets`(fp) | Return a list of the fragment offsets from the Basic Offset Table.
`read_item`(fp) | Read and return a single Item in the fragmented data stream.
`parse_basic_offsets`(buffer, *[, endianness]) | Return the encapsulated pixel data's basic offset table frame offsets.
`parse_fragments`(buffer, *[, endianness]) | Return the number of fragments and their positions in buffer.
`generate_fragments`(buffer, *[, endianness]) | Yield frame fragments from the encapsulated pixel data in buffer.
`generate_fragmented_frames`(buffer, *[, ...]) | Yield fragmented pixel data frames from buffer.
`generate_frames`(buffer, *[, ...]) | Yield complete pixel data frames from buffer.
`get_frame`(buffer, index, *[, ...]) | Return the specified frame at index.

## Creating Encapsulated Data

`encapsulate`(frames[, fragments_per_frame, ...]) | Return encapsulated frames.
`encapsulate_buffer`(buffers[, has_bot]) | Return an `EncapsulatedBuffer` instance from buffers.
`encapsulate_extended`(frames) | Return encapsulated image data and values for the Extended Offset Table elements.
`encapsulate_extended_buffer`(buffers) | Return `EncapsulatedBuffer` as well as encoded offsets and lengths for the Extended Offset Table elements.
`fragment_frame`(frame[, nr_fragments]) | Yield one or more fragments from frame.
`itemize_fragment`(fragment) | Return an itemized fragment.
`itemize_frame`(frame[, nr_fragments]) | Yield items generated from frame.

Management class for encapsulating buffers:

class pydicom.encaps.EncapsulatedBuffer(buffers: list[BufferedIOBase], use_bot: bool = False)

  Convenience class for managing the encapsulation of one or more buffers containing compressed Pixel Data.

  Added in version 3.0.

  property basic_offset_table: bytes

    Return an encoded Basic Offset Table.

  property closed: bool

    Return `True` if any of the encapsulated buffers are closed.

  property encapsulated_length: int

    Return the total length of the encapulated Pixel Data value.

  property extended_lengths: bytes

    Return an encoded Extended Offset Table Lengths value from lengths

    Returns:

      The encoded lengths of the frame.

    Return type:

      bytes

  property extended_offsets: bytes

    Return an encoded Extended Offset Table value from offsets

    Returns:

      The encoded offsets to the first byte of the item tag of the first fragment for every frame, as measured from the first byte of the first item tag following the empty Basic Offset Table Item.

    Return type:

      bytes

  property lengths: list[int]

    Return the encapsulated item lengths.

  property offsets: list[int]

    Return the encapsulated item offsets, starting at 0 for the first item.

  read(size: int | None = 8192, /) → bytes

    Read up to size bytes of data from the encapsulated buffers.

    Parameters:

      size (int, optional) – The amount of data to be read, if `None` then all data will be returned.

    Returns:

      The data read from the encapsulated buffers.

    Return type:

      bytes

  readable() → bool

    Return `True` if all the encapsulated buffers are readable.

  seek(offset: int, whence: int = 0, /) → int

    Change the encapsulated buffers position to the given byte offset, relative to the position indicated by whence and return the new absolute position.

  seekable() → bool

    Return `True` if all the encapsulated buffers are seekable.

  tell() → int

    Return the current stream position of the encapsulated buffers