The Listener API allows users to develop custom software that can receive the real-time ultrasound feed while the Clarius App is running and connected to a Clarius Scanner. Developers get access to the scan converted greyscale B mode image in real-time and have the option to display, process, and markup in real-time.
If users have purchased the Raw Data Capture option for a scanner, the API can also provide access to download raw data from the scanner when the App has set the Scanner for raw data collection. Note that raw data cannot be access in real-time, and must be downloaded over the wireless link once the scanner is frozen.
- Real-time access to B mode images
- Pure C interface or Qt-based Plugin interface for direct GPU rendering of image
- Up to 30 FPS - depending on imaging settings and WiFi configuration
- Supported on Wi-Fi routers or Clarius Scanner's Wi-Fi Direct
- If 3D Positional Data Package purchased for the Scanner, real-time streaming of 9DOF IMU data correlated with each image
- The Listener API cannot be used as a stand-alone application. The Clarius App must be running on an iOS or Android device and connected to a Scanner. If the Clarius App connection is broken, the Listener API will immediately lose it's connection.
- Qt programs can be written using the pure C API, however it is recommended that the Plugin version of the API is used to maximize performance of rendering, which avoids multiple buffer copies of image data. Console based programs or graphical programs written using GTK, MFC, etc. should be written using the pure C interface. The Plugin uses a QOpenGLContext to render images to a GPU buffer that the caller provides, whereas the C interface uses memcpy to move image data.
- Only reception of the ultrasound stream and associated data is possible, the API does not provide control for manipulating imaging parameters.
It is important to note that the API is built statically so that most system library dependency (such as Qt) is removed.
- Supported and tested as of version 5.1.0 of the Clarius App/API
- Note: Windows Firewall may need to be disabled or reconfigured for the API to receive images over the appropriate IP ports
- Supported and tested on Ubuntu 18.04 and 18.10
- Note: Some older versions of the Unicode or libc libraries may be required to install in order for program linking to be successful
- Supported and tested on version 10.0 and higher
- Supported and tested on various Android versions
- Supported and tested on iOS 11 and higher
The program must have 3 pieces of information in order to connect to a Scanner and receive the ultrasound stream:
- Wi-Fi network SSID and password
- Scanner IP address - typically network dependent, constant on Scanner's Wi-Fi Direct
- Listening Port - dynamically assigned, can be made persistent if required
Once the Scanner has a connection with the Clarius App, the Settings page will display the necessary information required to make the API connection.
- When connecting to the Scanner's Wi-Fi Direct, the Scanner IP address will remain a constant 192.168.1.1
- Wi-Fi Direct may yield better streaming frame rates, however a Wi-Fi router with external traffic may work just as well
To ensure static information for quicker connectivity:
- Use a Wi-Fi router with minimal external traffic that all devices (Scanner, mobile device, PC/device that Listener program is running) connect to automatically
- Configure the Scanner with a static IP on the router (the MAC address is displayed on the Settings screen within the App)
- Set a Static Listening Port by entering the App's Settings screen and toggling the setting on
The Listener API packages have fully documented source code (header files) and libraries, and also come with full working examples for both the C interface and Plugin interface.
A list of the current C API is as follows:
int clariusInitListener(int argc, char** argv, const char* dir, ClariusNewImageFn newImage, ClariusFreezeFn freeze, ClariusProgressFn progress, ClariusErrorFn err, ClariusReturnFn fn);
int clariusConnect(const char* ipAddress, unsigned int port, ClariusReturnFn fn);
int clariusDisconnect(ClariusReturnFn fn);
int clariusSetOutputSize(int w, int h);
int clariusSetNewImageFn(ClariusNewImageFn fn);
int clariusSetFreezeFn(ClariusFreezeFn fn);
int clariusSetProgressFn(ClariusProgressFn fn);
int clariusSetErrorFn(ClariusErrorFn fn);
int clariusRequestRawData(long long int start, long long int end, ClariusReturnFn fn);
int clariusReadRawData(void** data, ClariusReturnFn fn);
and make use of the following function and structure definitions:
typedef struct _ClariusImageInfo
long long int tm;
typedef struct _ClariusPosInfo
long long int tm;
typedef void (*ClariusReturnFn)(int retCode);
typedef void (*ClariusNewImageFn)(const void* newImage, const ClariusImageInfo* nfo, int npos, const ClariusPosInfo* pos);
typedef void (*ClariusFreezeFn)(int state);
typedef void (*ClariusProgressFn)(int progress);
typedef void (*ClariusErrorFn)(const char* msg);
Obtaining the Listener Packages
Once a Scanner and corresponding Listen API feature has been purchased, Clarius Support Team (firstname.lastname@example.org) can provide the appropriate links to download the API packages.