This repository contains all related items for the Clarius Cast API

The Cast API is based on the Clarius Cast protocol that the Clarius App uses for streaming images to multiple clients at once. It's primary use is for research purposes when access to real-time images is required, the Cast API provides a relatively simple way to get started. The API is deployed on desktop only, primarily because Clarius uses Qt heavily, a library that can often introduce difficulties when deploying or linking on mobile platforms. For commercial users wanting to deploy on mobile, Clarius has created the Java-based Mobile API, specifically for interfacing to the Clarius App in an Android environment.

The Cast API does provide some mechanisms for control of the ultrasound probe, such as the ability to freeze, change parameters such as depth and gain; however these are generally considered secondary functions, as the main purpose of the Cast API is to easily obtain the images in real-time, as opposed to duplicating a control interface.

• Obtain greyscale and color Doppler images (cartesian data) in real-time over the wireless network
• Obtain greyscale and color Doppler raw images (polar co-ordinate data) in real-time over the wireless network
• Obtain 9-DOF IMU data in real-time over the wireless network **
• Obtain raw data such as IQ and RF signals once imaging is frozen **
• Obtain interleaved RF signals in real-time **
• Set dimensions of output images
• Work over a wireless LAN or on the probe's Wi-Fi network
• Notifications for imaging freeze and button presses
• Ability to freeze imaging, change basic imaging parameters, and change imaging modes

** separate software licensing may be required for features to function

• Must be executed while the Clarius App is running and connected to a probe, can be the same or different mobile device/PC
• Probe, mobile device, and PC/device must be on the same wireless network
• Raw data can only be captured while imaging is frozen, except when RF streaming is enabled from the App, in which RF frames are interleaved and streamed over the Cast API when there is a connection

• New API binaries and source code get published when Clarius releases a new App
• APIs must be updated to the latest version, there is no backwards or forwards compatibility with older/newer Apps due to a probe firmware check that the library performs upon a connection
• Binaries can be obtained in the releases section of the GitHub repositories

The Cast API communicates with the Clarius Probe directly, and makes use of TCP technologies to create a secondary connection to the device that is able to receive images.

                                  +-----------------------+
                                  | Mobile Device         |
+---------+                       |    +-------------+    |
|         |   Primary Connection  |    |   Clarius   |    |
|  Probe  +-----------------------|--->+     App     |    |
|         |                       |    +-------------+    |
|         |    Cast Connection    |                       |
|         +<--------------+       +-----------------------+
|         |               |
+---------+               |       +-----------------------+
                          |       | PC                    |
                          |       |    +-------------+    |
                          |       |    | Cast        |    |
                          +-------|--->+ Application |    |
                                  |    |             |    |
                                  |    +-------------+    |
                                  |                       |
                                  +-----------------------+

• Windows: Windows 10
• Linux: Ubuntu 20.04 and later
• macOS: macOS 10.15 and later

Structure:

• src/include API headers
• src/example example programs
• src/python python examples (import pycast modules from release package)

Example Programs:

• caster a simple standalone command-line program that must be run with proper input arguments. The Windows version currently requires the boost c++ libraries to be installed for program argument parsing. Images cannot be viewed, however data/images can be captured. A Linux makefile and a Visual Studio solution have been created to help with compilation.
• caster_qt a graphical program that allows real-time viewing of the ultrasound stream and implements more functionality than the console program. A Qt Creator project file has been created to help with compilation. A valid compiler and Qt binaries should be installed in order for a proper kit to be defined within the IDE.

Typical Usage:

init(callbacks, dimensions)
connect(network_params)

while (input)
  performAction(input)
 
imageCallback(image)
{
  processImage(image)
}

The Clarius App will display the network information on a top bar above the image for any probe licensed for the Cast API. The port and IP address are required to make a connection through the Cast API.

|||

Licenced probes also have the option for forcing the port by adjusting the Clarius Cast Permission setting within the App to "Research". This provides a potentially more streamlined method when automating connections from the custom software.

||

Since most connections will be made using the probe's own Wi-Fi network, it is important to ensure the computer running the Cast program is on the same network. Probe networks are typically prefixed with "DIRECT-", and the password is available for 60 seconds on the mobile device clipboard once the Clarius App has connected.

• When running under Windows, execution may require temporarily disabling the firewall defender or adding an exception for the executable - the latter is recommended. This is due to the use of randomized ports that the API makes use of for streaming images.