@spec encapsulated?(Dicom.DataSet.t()) :: boolean()

Returns true if the pixel data is encapsulated (fragment-based).

Encapsulated pixel data is stored as a list of fragments (first element is the Basic Offset Table, remaining elements are data fragments).

@spec frame(Dicom.DataSet.t(), non_neg_integer()) ::
  {:ok, binary()} | {:error, term()}

Extracts a single frame by zero-based index.

For native pixel data, uses zero-copy binary_part/3 without extracting all frames.

@spec frame_count(Dicom.DataSet.t()) ::
  {:ok, pos_integer()} | {:error, :no_pixel_data | :invalid_number_of_frames}

Returns the number of frames in the pixel data.

@spec frames(Dicom.DataSet.t()) :: {:ok, [binary()]} | {:error, term()}

Extracts all frames from pixel data.

For native pixel data, computes frame size from image dimensions and slices the pixel data binary.

For encapsulated pixel data:

• If BOT is present, uses offsets to group fragments per frame
• If no BOT and single frame, concatenates all fragments
• If no BOT and multi-frame, each fragment is one frame