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


This tutorial expains how to run the virtual server and how to grab the ultrasound images on client side. It provides also help to format correctly your ultrasound sequences, so they could be read ans sent correctly with the virtual server.

Formatting correctly your data: image sequence used as input of the virtual server.

To use your sequence of ultrasound images in the virtual server application, the main information to precise is the timestamps of every frame: the server uses them to respect the delay between each frame sent. The virtual server can take 2 types of image sequences as input:

  • A 2D sequence using a xml file and a set of images in standard formats (png, pgm, jpeg...): available for sequence of pre-scan 2D or post-scan 2D images (based on usSequenceReader / usSequenceWriter)
  • A 2D or 3D sequence using metaheader format (mhd/raw): available for RF (2D and 3D), pre-scan (2D and 3D) and for post-scan 2D (based on usMHDSequenceReader and usMHDSequenceWriter)

Here is an example of how to load a sequence of pre-scan volumes written in metaheader format, and set to each frame a timestamp of your choice (expressed in ms since epoch):

#include <visp3/ustk_core/usMHDSequenceReader.h>
#include <visp3/ustk_core/usMHDSequenceWriter.h>
int main(int argc, char **argv)
std::string sequenceDirectory;
if (argc == 1) {
std::cout << "\nUsage: " << argv[0] << " [--input /path/to/mhd/sequence ] \n" << std::endl;
return 0;
for (unsigned int i = 1; i < (unsigned int)argc; i++) {
if (std::string(argv[i]) == "--input") {
sequenceDirectory = std::string(argv[i + 1]);
i = argc;
} else {
std::cout << "\nUsage: " << argv[0] << " [--input /path/to/mhd/sequence ] \n" << std::endl;
return 0;
std::vector<uint64_t> timestamp;
writer.setSequenceDirectory("/tmp"); // set here your outpur directory
uint64_t newTimestamp = 0;
int inc = 0;
// reading loop
while (!reader.end()) {
reader.acquire(image, timestamp);
// print your image informations
std::cout << image;
// add a timestamp of 100ms between each frame
for (unsigned int i = 0; i < timestamp.size(); i++) { = newTimestamp;
newTimestamp += 100;
if (inc % 2 ==
1) // to fit a virtual probe motor sweeping along Z axis (at every volume, frame order is inverted along Z axis)
std::reverse(timestamp.begin(), timestamp.end());
writer.write(image, timestamp);
return 0;

In this example, a default timestamp is set at first frame of the sequence and then it's incremented of 100ms at each frame.

Running the virtual server

The source code can be dowloaded by running the following svn command:

$ svn export

Then you have to run CMake to configure your project, and finally you can compile it.

The virtual server application requires in input a path to the sequence to replay. To run it go in the directory where the application is built, and run the following command (replace /path/to/your/sequence by the path to the sequence you prepared in previous section):

$ ./ustk-virtualServer --input /path/to/your/sequence

If you see the following message : "TCP server Started Server now listening on port# 8080" it means that your server is running correctly. Now you can use a client application to connect to it and grabbing the images using a grabber class as shown in next section.

Running the client

This section explains how to run a client application to grab the frames sent by the virtual server.

First, download the source codes of the clients using the following svn command:

$ svn export

Then use CMake to configure the project, and finally compile it.

To run a client application go in your binary directory (containing the applications you just built), and run the following command for example (case of pre-scan volumes sent by the server):

$ ./tutorial-ustk-virtual-server-preScan3D

If all is going well, you should see the following message : "init success waiting ultrasound initialisation...", and then the volumes are coming.