# pydicom.encaps.encapsulate

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

  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

  See also

  `encapsulate_extended()`