pydicom.encaps.get_frame

pydicom.encaps.get_frame(buffer: bytes | bytearray | ReadableBuffer, index: int, *, extended_offsets: tuple[list[int], list[int]] | tuple[bytes, bytes] | None = None, number_of_frames: int | None = None, endianness: str = '<') → bytes[source]

Return the specified frame at index.

Added in version 3.0.

Note

When the Basic Offset Table is empty and the Extended Offset Table isn’t supplied then it’s possible to return a frame at a higher index than expected from the supplied number_of_frames value provided there are sufficient excess fragments available.

Parameters:

  • buffer (bytes | bytearray | readable buffer) – A buffer containing the encapsulated frame data, positioned at the first byte of the basic offset table. May be bytes, bytearray or an object with read(), tell() and seek() methods. If the latter then the buffer will be reset to the starting position if the frame was returned successfully.

  • index (int) – The index of the frame to be returned, starting at 0 for the first frame.

  • number_of_frames (int, optional) – Required for multi-frame data when the Basic Offset Table is empty, the Extended Offset Table has not been supplied and there are multiple frames. This should be the value of (0028,0008) Number of Frames or the expected number of frames in the encapsulated data.

  • extended_offsets (tuple[list[int], list[int]] or tuple[bytes, bytes], optional) – The (offsets, lengths) of the Extended Offset Table as taken from (7FE0,0001) Extended Offset Table and (7FE0,0002) Extended Offset Table Lengths as either the raw encoded values or a list of their decoded equivalents.

  • endianness (str, optional) – If "<" (default) then the encapsulated data uses little endian encoding, otherwise if ">" it uses big endian encoding.

Returns:

A single frame of encoded pixel data.

Return type:

bytes

References

DICOM Standard Part 5, Annex A