UsTK : Ultrasound ToolKit  version 1.0.0 under development (2020-04-04) under development (2020-04-04)
Tutorial: Installation from source for Linux Ubuntu

In this tutorial you will learn how to install UsTK from source on Linux Ubuntu. These steps have been tested with Ubuntu 17.04 and Ubuntu 18.04 (64 bit) distributions, but should work with any other distribution as well.

To build and install UsTK there are two ways:

Build UsTK using installation script

Get the sources

First, create a workspace in $HOME/ustk-ws that will contain UsTK and ViSP sources, build and dataset:

$ export USTK_WS=$HOME/ustk-ws
$ mkdir -p $USTK_WS

Prior to build and install UsTK, you have to download the sources. To achieve this, run the following command:

$ git clone https://github.com/lagadic/ustk $USTK_WS/ustk

Git will clone the UsTK source code in $USTK_WS/ustk folder.

Run installation script

Then you can run the installation script for ubuntu:

$ sh $USTK_WS/ustk/script/install-ubuntu.sh

This will download all third-parties and build the library (it will take some time). You will have to enter your password to install required packages, and confirm a few questions during the process.

Once build, you may now Build UsTK documentation.

Build UsTK using command line

We give hereafter all the instructions to build UsTK from source.

Install third-parties

UsTK has optional third-parties that you can install running:

  • XML2: XML2 library is used by UsTK for I/O (ultrasound image or sequence of images settings). This 3rd party could be installed from existing packages.
    $ sudo apt-get install libxml2-dev
  • VTK with Qt4 or Qt5 support: VTK library is used by UsTK for visualization (GUI). This 3rd party could be installed from existing pre-build packages.
    $ sudo apt-get install libvtk6-qt-dev
  • FFTW: FFTW library is used by RF to pre-scan converters. This 3rd party could be installed from existing pre-build packages.
    $ sudo apt-get install libfftw3-dev
  • armadillo: armadillo library is used for elastography. This 3rd party could be installed from existing pre-build packages.
    $ sudo apt-get install libarmadillo-dev

Build UsTK

  • First, create a workspace in $HOME/ustk-ws that will contain UsTK and ViSP sources, build and dataset:
    $ export USTK_WS=$HOME/ustk-ws
    $ mkdir -p $USTK_WS
  • Download ViSP and UsTK sources codes
    $ git clone https://github.com/lagadic/visp $USTK_WS/visp
    $ git clone https://github.com/lagadic/ustk $USTK_WS/ustk
  • Make a build directory (where UsTK and ViSP will be compiled together)
    $ mkdir $USTK_WS/ustk-build; cd $USTK_WS/ustk-build
  • Configure the build setting UsTK as a ViSP external contrib module
    $ cmake ../visp -DVISP_CONTRIB_MODULES_PATH=$USTK_WS/ustk
  • Note that with the previous command, all ViSP modules will be build besides UsTK. Since ViSP modules related to AR, detection, computer vision or tracking are not used by UsTK, their build could be turned off in order to speed up UsTK build. This could be achieved using:
    $ cmake ../visp -DVISP_CONTRIB_MODULES_PATH=$USTK_WS/ustk -DBUILD_MODULE_visp_ar=OFF -DBUILD_MODULE_visp_blob=OFF -DBUILD_MODULE_visp_detection=OFF -DBUILD_MODULE_visp_klt=OFF -DBUILD_MODULE_visp_mbt=OFF -DBUILD_MODULE_visp_me=OFF -DBUILD_MODULE_visp_tt=OFF -DBUILD_MODULE_visp_tt_mi=OFF -DBUILD_MODULE_visp_vision=OFF -DBUILD_MODULE_visp_visual_features=OFF -DBUILD_MODULE_visp_vs=OFF
  • Now on unix-like OS build ViSP and UsTK using:
    $ make -j4
Note
There are Known issues that may appear and for which we propose fixes.

How to install UsTK dataset

Some examples or tutorials are working with ultrasound medical images. We propose a dataset that contains 2D or 3D ultrasound data in https://github.com/lagadic/ustk-dataset. To use this dataset you may set the USTK_DATASET_PATH environment variable like:

$ git clone https://github.com/lagadic/ustk-dataset $USTK_WS/ustk-dataset
$ export USTK_DATASET_PATH=$USTK_WS/ustk-dataset

Build UsTK documentation

To build UsTK documentation as a stand alone documentation (i.e.. without all ViSP classes prefixed by "vp"):

$ cd $USTK_WS/ustk-build
$ make -j4 ustk_doc

Install UsTK

We don't recommend to install UsTK in /usr/local. If you want to do the installation anywa, run:

$ cd $USTK_WS/ustk-build
$ make -j4 install

Uninstall UsTK

To uninstall UsTK, run:

$ cd $USTK_WS/ustk-build
$ make -j4 uninstall

Known issues

No rule to make target '/usr/lib/x86_64-linux-gnu/libproj.so'

This issue may appear on Ubuntu 16.04 LTS

$ make
make[3]: *** No rule to make target '/usr/lib/x86_64-linux-gnu/libproj.so', needed by 'lib/libvisp_ustk_gui.so.3.0.2'. Stop.
CMakeFiles/Makefile2:6995: recipe for target 'modules/ustk_gui/CMakeFiles/visp_ustk_gui.dir/all' failed

This issue is related to vtk installation where libproj.so is a dependency that is not installed with vtk.

$ grep libproj /usr/lib/cmake/vtk-6.2/VTKTargets.cmake
INTERFACE_LINK_LIBRARIES "vtkIOXML;vtkInfovisLayout;vtkInteractionStyle;vtkInteractionWidgets;vtkRenderingCore;vtkViewsCore;/usr/lib/x86_64-linux-gnu/libproj.so"

The fix consists in installing libproj-dev package:

$ sudo apt-get install libproj-dev