UsTK : Ultrasound ToolKit  version 1.0.0 under development (2020-06-26) under development (2020-06-26)
Tutorial: UsTK Ultrasonix server application installation


This tutorial explains how to install the UsTK ultrasonix TCP server application on a ultrasonix machine. Requirements:

  • Station type : Sonix touch / Sonix tablet
  • Ultrasonix research SDK version : porta 5.6.0 or newer
  • CMake software
  • Visual Studio compiler
  • UsTK and its dependencies, including Qt 5 (tested with Qt 5.5 on Windows XP with Visual Studio 2010).

The sonix touch station

The sonix tablet station

Configuration of the build

First login to the Ultrasonix machine.

Then install Qt 5.5 for MSVC 2010 on the Ultrasonix machine. You may download qt-opensource-windows-x86-msvc2010-5.5.0.exe and double click on this file to start installation.

Next, download Ultrasonix SDK on Ultrasonix research website, and extract it on a location of your choice (C:/Ultrasonix for example). Add a new environment variable to your windows system called PORTA_DIR, and pointing on the porta directory of the SDK (C:/Ultrasonix/SDK/porta for example). To this end, open a cmd.exe terminal and run:

C:\> setx PORTA_DIR C:\Ultrasonix\SDK\porta

If not already done, install CMake.

You may now download ViSP and UsTK source codes:

  • Create a workspace folder and enter in this folder
      $ mkdir <workspace>; cd <workspace>
  • Download ViSP and UsTK sources codes
      $ git clone
      $ git clone
  • Make a build directory (where UsTK and ViSP will be compiled together)
      $ mkdir visp-ustk-build; cd visp-ustk-build

Then you can configure the project using CMake:

  • Run cmake-gui, and specify the source directory of ViSP (<workspace>/visp), and put the build directory (<workspace>/visp-ustk-build).
  • In the VISP_CONTRIB_MODULES_PATH option, enter the location of UsTK source code (<workspace>/ustk).
  • Click "Configure" button, and verify that Porta and Qt have been found correctly with CMake checking that cmake option USE_QT5 is true and PORTA_LIBRARIES is correctly filled with your path.
  • Set Porta_LICENSE_PATH variable to the path that contains licenses_web file generally located in C:/Ultrasonix/SDK/porta/license
  • Click "Generate" button

If all went well the configuration step is OK, you can move on to compilation step.

Build the application

To build the application, there are two ways:

  1. Double click on <workspace>/visp-ustk-build/VISP.sln solution file in order to open the whole ViSP solution in Visual Studio. Then select Release in configuration manager, scroll to ustk-ultrasonix-server Visual Studio project and built this project.
  2. Or open directly ustk-ultrasonix-server.sln Visual Studio solution located in <workspace>/visp-ustk-build/apps/ustk/ultrasonix-server folder. Once opened in Visual Studio 2010, select Release in configuration manager and build the project.

If the build is successful, you can now run the server application located in <workspace>/visp-ustk-build/apps/ustk/ultrasonix-server/Release/ustk-ultrasonix-server.exe (see below).

Running the server application

Before running the application, verify that a ultrasound probe is connected to your station, and that your station is connected to a network. To run the application simply run the executable ustk-ultrasonix-server.exe generated in your build directory. In a console, you will see the following messages:

C:\...> ustk-ultrasonix-server.exe
porta instance created
TCP server Started
Server now listening on port# 8080

Now should appear a window asking "Do you want to keep blocking this program ?". Click on button "Unblock".

The server running on Ultrasonix Station is now ready.

On Ubuntu, you can run clients that are already provided as tutorials in:

  • <visp-ustk-build>/tutorial/ustk/ultrasonix/tutorial-ultrasonix-qt-grabbing-RF to grab RF 2D images
  • <visp-ustk-build>/tutorial/ustk/ultrasonix/tutorial-ultrasonix-qt-grabbing-pre-scan to grab pre-scan 2D images
  • <visp-ustk-build>/tutorial/ustk/ultrasonix/tutorial-ultrasonix-qt-grabbing-post-scan to grab post-scan 2D images

Other examples are provided in the same folder.

Use custom probes

In our lab, ustk server application is used with 5 probes only (C5-2, BPL9-5, BPC8-4, bi-plane, and 4DC7-3). So default imaging parameters are set from xml settings files provided by ultrasonix in our server application. If you want to use some other probes, you can prepare a file to link probe ids with ultrasonix imaging pararameters config filenames. Here is an example of config file content:

10 FAST-General (C5-2 60mm).xml
12 GEN-General (BPL9-5 55mm).xml
13 GEN-General (BPC8-4 10mm).xml
14 GEN-General (PAXY).xml
15 GEN-General (4DC7-3 40mm).xml

This is the default configuration of the application if no config file is provided.

Once your file (let's call it probeParameters.txt) is created, put it near ustk-ultrasonixServer binary. Then in a console, go into ustk-ultrasonixServer binary folder and run:

ustk-ultrasonix-server.exe --probeSettingsFile probeParameters.txt

This will take into account your imaging parameters file corresponding to the probe plugged when you initialize the server application.

Tips & Tricks

Here are some advices to resolve some known issues that may occur during application building or usage.

Compile error with Qt5Core that conflicts with target machine type x64

When building the application, if you face the following build issue:

Qt5Core.lib(Qt5Core.dll) : fatal error LNK1112: module machine type 'X86' conflicts with target machine type 'x64'

It meeans that with CMakeGUI you configure ViSP or the application with Visual Studio 2010 Win64. Since you downloaded and installed Qt 5.5 for Visual Studio 2010 (Win32) you have this conflict.

To solve this issue:

  • open CMakeGUI
    • remove the cache
    • configure the project with Visual Studio 2010
    • generate the solution files
  • open the solution file in Visual Studio 2010 and build again the application

Compile error with Porta 6

If you are using porta 6 SDK, you will probably face a compile issue in the header file provided by Ultrasonix:

(porta_wrapper.h) : unknown type name 'imagingModes'.

This error is due to a missing header file: imagingModes.h. Simply include this header in porta_wrapper.h to correct the issue.

Porta hardware initialization error with SonixTablet

If you are using a SonixTablet station, you'll have to change the default parameters to initialize porta. With this hardware, the usm and pci version have to be set to 4 (the default values in the server application are set to 3 and correspond to the right parameters for a SonixTouch machinestation). To set those values, you can use the --pci and --usm options as follow:

C:\...> ustk-ultrasonix-server.exe --usm 4 --pci 4

This will solve the initialization issues for SonixTablet stations.

Next tutorial

Once the server application is running on your Ultrasonix station, you can then go to the next Tutorial: UsTK grabber tutorial for ultrasonix station.