Concept: ChannelData
====================

The **ChannelData** concept in the USImgFormationPlugin refers to any 3D image, 3D+t data (a recorded sequence in a :class:`~imfusion.SharedImageSet`), or 3D image stream that includes the appropriate DataComponents. 
This concept is fundamental for processing ultrasound channel data. 
The optional DataComponents provide additional flexibility in processing and interpreting the data.

Required DataComponents
-----------------------

- :class:`~imfusion.ultrasound_image_formation.FrameAcquisition`

  This DataComponent is **mandatory** and contains all metadata describing the acquisition of the channel data. 
  It provides the necessary information to enable the full processing of the data.

Optional DataComponents
-----------------------

- :class:`~imfusion.ultrasound_image_formation.ChannelDataLayout`
  
  If present, this DataComponent describes the layout of the three semantic dimensions of the 3D data block of the channel data:
  
  - **Elements / Channels**
  - **Fast Time**
  - **Slow Time / Pulse Echo Emissions**
  
  The :class:`~imfusion.ultrasound_image_formation.ChannelDataLayout` maps each of the data x, y, and z axes to one of these semantics.
  If the :class:`~imfusion.ultrasound_image_formation.ChannelDataLayout` DataComponent is not provided, algorithms working on channel data will assume the default layout: **Channels, FastTime, SlowTime**.

- :class:`~imfusion.ultrasound_image_formation.BeamformingRois`
  
  This DataComponent is optional and describes the regions where the beamforming is performed in focused and ultrafast imaging.
  For focused imaging, the ROIs are represented as a line segment (two points: start and end of the scanline), while for ultrafast imaging, the ROIs are a polygon.
  If not provided, the regions are derived from the :class:`~imfusion.ultrasound_image_formation.FrameAcquisition`.