Clarius Device vs. ClariusOEM Device

PLUS supports two different interfaces to Clarius probes. This documentation is for the CAST API based PLUS device. Using this approach, a phone/tablet is connected to the probe, and the PC running PLUS retrieves images indirectly via this phone/tablet.

In contrast, the (relatively newer) Clarius support uses the Clarius OEM API which connects directly with the probe using the Bluetooth Low Energy (BLE) and Wi-Fi interfaces of the PC running PLUS. This device also exposes US controls for the Clarius, and real-time battery / button state streaming accessible as MRML node attributes on the Image node in 3D Slicer. The primary limitation of this interface is that for now it's only available on Windows. If possible, we recommend using this device. Documentation for the OEM API based PLUS device is available at Clarius ultrasound systems (OEM API)

Supported hardware devices

This device is used for image acquisition from Clarius ultrasound systems using the CAST API.
Link to manufacturer's website: https://clarius.com
Link to the CAST API: https://github.com/clariusdev/cast
Link to the IMU coordinate system documentation: https://github.com/clariusdev/motion
Link to the raw data documentation: https://github.com/clariusdev/raw

Supported platforms

Windows 64 bits

Connection

Requires a connection to the same network as the Clarius
Directly connecting to the Clarius's network is possible, however it can easily become congested
It is recommended to use a local Wi-Fi network instead:
- Establishing a local Wi-Fi connection

Device configuration settings

Device
- Type = "Clarius"
- IpAddress Ip address of probe on connected network
- TcpPort Clarius cast tcp port
- FrameWidth Desired frame width. If the frame size is not supported the default will be used.
  
  Default = "640"
- FrameHeight Desired frame height. If the frame size is not supported the default will be used.
  
  Default = "480"
- ImuEnabled
  
  Default = "FALSE"
- ImuOutputFileName
  
  Default = "ClariusImuData.csv"
- WriteImagesToDisk
  
  Default = ""FALSE""
- DataSources Multiple DataSource child elements are allowed, one for each data type (PortName indicates the data type)
  - DataSource
    - Type Type should be Video for images and Tool for IMU data
    - PortName
      - B B-mode image data
      - Rf RF data
      - Accelerometer IMU accelerometer data
      - Gyroscope IMU gyroscope data
      - Magnetometer IMU magnetometer data
      - OrientationSensor IMU orientation data

Example configuration file for Clarius B-mode image acquisition

<PlusConfiguration version="2.1">
  <DataCollection StartupDelaySec="1.0" >
    <DeviceSet
      Name="PlusServer: Clarius ultrasound device"
      Description="Broadcasting acquired video through OpenIGTLink"/>
    <Device Id="VideoDevice"
      Type="Clarius"
      IpAddress = "192.168.1.1"
      TcpPort = "5828"
      FrameWidth = "640"
      FrameHeight = "480"
      ImuEnabled = "TRUE"
      ImuOutputFileName = "ImuOutput.csv"
      WriteImagesToDisk = "FALSE">
      <DataSources>
        <DataSource Type="Video" Id="Video" PortName="B" PortUsImageOrientation="UN"/>
      </DataSources>
      <OutputChannels>
        <OutputChannel Id="VideoStream" VideoDataSourceId="Video" />
      </OutputChannels>
    </Device>
    <Device
      Id="CaptureDevice"
      Type="VirtualCapture"
      BaseFilename= "ClariusRecording.igs.mha"
      EnableCapturingOnStart="FALSE"
      RequestedFrameRate="25"
      EnableCapturing="TRUE" >
      <InputChannels>
        <InputChannel Id="VideoStream" />
      </InputChannels>
    </Device>
  </DataCollection>
  <CoordinateDefinitions>
    <Transform From="Image" To="Reference"
      Matrix="
      0.2 0.0 0.0 0.0
      0.0 0.2 0.0 0.0
      0.0 0.0 0.2 0.0
      0 0 0 1" />
  </CoordinateDefinitions>
  <PlusOpenIGTLinkServer
    MaxNumberOfIgtlMessagesToSend="1"
    MaxTimeSpentWithProcessingMs="50"
    ListeningPort="18944"
    SendValidTransformsOnly="false"
    OutputChannelId="VideoStream" >
    <DefaultClientInfo>
      <MessageTypes>
        <Message Type="IMAGE" />
      </MessageTypes>
      <ImageNames>
        <Image Name="Image" EmbeddedTransformToFrame="Reference" />
      </ImageNames>
    </DefaultClientInfo>
  </PlusOpenIGTLinkServer>
</PlusConfiguration>

Example configuration file for Clarius B-mode image acquisition with IMU data

<PlusConfiguration version="2.1">
  <DataCollection StartupDelaySec="1.0" >
    <DeviceSet
      Name="PlusServer: Clarius ultrasound device"
      Description="Broadcasting acquired video through OpenIGTLink"/>
    <Device Id="VideoDevice"
      Type="Clarius"
      IpAddress = "192.168.1.1"
      TcpPort = "5828"
      FrameWidth = "640"
      FrameHeight = "480"
      ImuEnabled = "TRUE"
      ImuOutputFileName = "ImuOutput.csv"
      WriteImagesToDisk = "FALSE">
      <DataSources>
        <DataSource Type="Video" Id="Video" PortName="B" PortUsImageOrientation="UN"/>
        <DataSource Type="Tool" Id="Accelerometer" PortName="Accelerometer" />
        <DataSource Type="Tool" Id="Gyroscope" PortName="Gyroscope" />
        <DataSource Type="Tool" Id="Magnetometer" PortName="Magnetometer" />
        <DataSource Type="Tool" Id="TiltSensor" PortName="TiltSensor" />
        <DataSource Type="Tool" Id="FilteredTiltSensor" PortName="FilteredTiltSensor" />
        <DataSource Type="Tool" Id="OrientationSensor" PortName="OrientationSensor" />
      </DataSources>
      <OutputChannels>
        <OutputChannel Id="VideoStream" VideoDataSourceId="Video">
          <DataSource Id="Accelerometer"/>
          <DataSource Id="Gyroscope"/>
          <DataSource Id="Magnetometer"/>
          <DataSource Id="TiltSensor"/>
          <DataSource Id="FilteredTiltSensor"/>
          <DataSource Id="OrientationSensor"/>
        </OutputChannel>
      </OutputChannels>
    </Device>
    <Device
      Id="CaptureDevice"
      Type="VirtualCapture"
      BaseFilename= "ClariusRecording.igs.mha"
      EnableCapturingOnStart="FALSE"
      RequestedFrameRate="25"
      EnableCapturing="TRUE" >
      <InputChannels>
        <InputChannel Id="VideoStream" />
      </InputChannels>
    </Device>
  </DataCollection>
  <CoordinateDefinitions>
    <Transform From="Image" To="Reference"
      Matrix="
      0.2 0.0 0.0 0.0
      0.0 0.2 0.0 0.0
      0.0 0.0 0.2 0.0
      0 0 0 1" />
  </CoordinateDefinitions>
  <PlusOpenIGTLinkServer
    MaxNumberOfIgtlMessagesToSend="1"
    MaxTimeSpentWithProcessingMs="50"
    ListeningPort="18944"
    SendValidTransformsOnly="false"
    OutputChannelId="VideoStream" >
    <DefaultClientInfo>
      <MessageTypes>
        <Message Type="IMAGE" />
        <Message Type="TRANSFORM" />
      </MessageTypes>
      <ImageNames>
        <Image Name="Image" EmbeddedTransformToFrame="Reference" />
      </ImageNames>
      <TransformNames> 
        <Transform Name="AccelerometerToVideoDevice" />
        <Transform Name="GyroscopeToVideoDevice" />
        <Transform Name="MagnetometerToVideoDevice" />
        <Transform Name="TiltSensorToVideoDevice" />
        <Transform Name="FilteredTiltSensorToVideoDevice" />
        <Transform Name="OrientationSensorToVideoDevice" />
      </TransformNames>
    </DefaultClientInfo>
  </PlusOpenIGTLinkServer>
</PlusConfiguration>

Example configuration file for Clarius B-mode image and RF data acquisition

<PlusConfiguration version="2.1">
  <DataCollection StartupDelaySec="1.0" >
    <DeviceSet
      Name="PlusServer: Clarius ultrasound device (B-Mode and RF)"
      Description="Broadcasting acquired video from Clarius cast through OpenIGTLink. Port 18944 contains B-Mode images, while port 18945 contains RF images."/>
    <Device
      Id="VideoDevice"
      Type="Clarius"
      IpAddress = "192.168.1.1"
      TcpPort = "5828"
      FrameWidth = "640"
      FrameHeight = "480"
      ImuEnabled = "TRUE"
      ImuOutputFileName = "ImuOutput.csv"
      WriteImagesToDisk = "FALSE">
      <DataSources>
        <DataSource Type="Video" Id="BModeVideo" PortName="B" PortUsImageOrientation="UN"/>
        <DataSource Type="Video" Id="RfVideo" PortName="Rf" PortUsImageOrientation="UN"/>
      </DataSources>
      <OutputChannels>
        <OutputChannel Id="BModeVideoStream" VideoDataSourceId="BModeVideo" />
        <OutputChannel Id="RfVideoStream" VideoDataSourceId="RfVideo" />
      </OutputChannels>
    </Device>
  </DataCollection>
  <PlusOpenIGTLinkServer
    MaxNumberOfIgtlMessagesToSend="1"
    MaxTimeSpentWithProcessingMs="50"
    ListeningPort="18944"
    SendValidTransformsOnly="false"
    OutputChannelId="BModeVideoStream" >
    <DefaultClientInfo>
      <MessageTypes>
        <Message Type="IMAGE" />
      </MessageTypes>
      <ImageNames>
        <Image Name="BModeVideo" EmbeddedTransformToFrame="BModeVideo" />
      </ImageNames>
    </DefaultClientInfo>
  </PlusOpenIGTLinkServer>
  <PlusOpenIGTLinkServer
    MaxNumberOfIgtlMessagesToSend="1"
    MaxTimeSpentWithProcessingMs="50"
    ListeningPort="18945"
    SendValidTransformsOnly="false"
    OutputChannelId="RfVideoStream" >
    <DefaultClientInfo>
      <MessageTypes>
        <Message Type="IMAGE" />
      </MessageTypes>
      <ImageNames>
        <Image Name="RfVideo" EmbeddedTransformToFrame="RfVideo" />
      </ImageNames>
    </DefaultClientInfo>
  </PlusOpenIGTLinkServer>
</PlusConfiguration>