entete.png /rio/vv?action=AttachFile&do=get&target=OS.png

David Sarrut, Pierre Seroul, Joël Schaerer, Simon Rit, Jef Vandemeulebroucke, Thomas Baudier, Bharath Navalpakkam, Gauthier Bouilhol, Romulo Pinho, Vivien Delmon and Maxime Pech, vv[at]creatis.insa-lyon.fr (Mailing List Subscription)

Bug Tracker, Travis CI.


1. VV ?

VV is an open-source and cross platform image viewer, designed for fast and simple visualization of spatio-temporal images: 2D, 2D+t, 3D and 3D+t (or 4D) images. VV runs (at least!) on Linux, Windows and Mac OS in 32 and 64 bits.

VV is more specifically designed for qualitative evaluation of image registration and deformation field visualization. It contains several tools for superimposing images using complementary colors or transparency, visualizing vector fields and defining landmarks. With a modern graphic card, navigation is fast and smooth.

VV is distributed under two open source licenses: BSD and CeCILL-B license from the CNRS, without restrictions and without warranty. Feel free to use it as you like! We would like to encourage you to share your experience by sending an email to vv[at]creatis.insa-lyon.fr briefly describing your use of vv. When using it for publications, please make reference to the article:

This work is still in progress, we welcome any advice or opinions that can make this software more useful.

Motion visualization

Image Overlay

attachment:popi.gif

attachment:vv1.1Overlay.png


2. Download VV

https://github.com/open-vv/vv

2.1. Binaries

Binaries are provided without any warranty. We advise you to compile it yourself.

Latest release is v1.4 (October 2016 / updated March 2018):

v1.3 (October 2012).

An archlinux package named vv is available through AUR.

v1.2 (May 2011).

v1.1 (July 2010).

2.2. Source code

The latest source code is available in a git repository. To download it, run:

git clone https://github.com/open-vv/vv.git vv

Releases:

2.3. Docker

You can download a docker image of vv. After install Docker, you just have to do (2GB):

systemctl start docker
docker pull tbaudier/vv

And to lauch vv with the Docker:

systemctl start docker
docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /home/tbaudier:/home tbaudier/vv

2.4. Examples of data

Click here to download examples of images.


3. Compiling VV ... where to begin?

In order to compile VV you need the following third party software:

A separate page details specific instructions to compile it statically, i.e. without links to dynamic libraries. The following instructions are linux/gcc oriented but it is easy to translate them to other OS/compilers.

3.1. CMake

CMake is a family of tools designed to build, test and package software.

You can download pre-compiled binaries and the source code here or via git:

git clone git://cmake.org/cmake.git

Installation instructions are available here.

CMake is used to build ITK, VTK and VV.

3.2. QT

Qt is a cross-platform application development framework widely used for the development of GUI programs.

We recommend you to install Qt5-devel and widget development library (Designer, Xml, Tools, Gui, Network, OpenGL, ...) with your package manager (e.g.: apt-get, Yum, Yast, ...)

You can download pre-compiled binaries or the source code here or via git:

git clone git://code.qt.io/qt/qt.git

A working version can be download here (.tar.gz) or here (.zip).

To compile it, you can try:

./configure -opensource -confirm-license -nomake examples -nomake tests -no-gtkstyle -qt-xcb
make -j4
make install

3.3. VTK

The Visualization Toolkit (VTK) is an open-source, freely available software system for 3D computer graphics, image processing and visualization.

VV is tested with VTK. You can download the source code here or via git. We recommend you to use version 7.1.0:

git clone https://github.com/Kitware/VTK.git vtk
cd vtk
git checkout v7.1.0
cd ..

Create a binary directory, get into it and run CMake:

mkdir vtk-binary
cd vtk-binary
ccmake ../vtk

You need to change the following build options for VV:

Module_vtkGUISupportQt=ON
Module_vtkGUISupportQtOpenGL=ON
Module_vtkRenderingQt=ON
Module_vtkViewsQt=ON
VTK_RENDERING_BACKEND=OpenGL
VTK_QT_VERSION=5
All Qt5...DIR to /usr/local/Qt-5.../lib/cmake/QT5...

And finally, compile it:

make

NB:

VTK_Group_Rendering:BOOL=ON

Qt5_DIR="/usr/local/Qt-5.../lib/cmake/Qt5"
Qt5Designer_DIR="/usr/local/Qt-5...lib/cmake/Qt5Designer"
Qt5Xml_DIR="/usr/local/Qt-5.../lib/cmake/Qt5Xml"
Qt5Network_DIR="/usr/local/Qt-5.../lib/cmake/Qt5Network"

3.4. ITK

To compile ITK from git: We recommend you to use version 4.13.0:

git clone https://github.com/InsightSoftwareConsortium/ITK.git itk
cd itk
git checkout v4.13.0
cd ..

Create a binary directory, get into it and run CMake:

mkdir itk-binary
cd itk-binary
ccmake ../itk

In CMake, change the following settings:

BUILD_SHARED_LIBS=ON
Module_ITKVtkGlue=ON

You need to specify the VTK path if it is not done automatically. More specially:

VTK_DIR="/VTK/VTK_bin"

And finally, compile it:

make

3.5. VV

Finally, to compile VV from git:

git clone https://github.com/open-vv/vv.git vv

mkdir vv-binary
cd vv-binary
ccmake ../vv
make

You have to set the correct paths to ITK binaries and Qt5 into ccmake prompt


4. Feature overview

4.1. Image IO

VV open and display images of various file formats :

Note the explicit distinction between 3D and 2D+t images. VV allows the reinterpretation of any n dim image as a (n-1) dim +t image. Any loaded image can be saved as another file format through the "save-as" menu.

VV also contains a minimal Dicom Browser to open images series (which works sometimes).

attachment:helpscreenshot.png

A 'play mode' is also available for temporal images in order to navigate into images during motion.

4.2. Registration evaluation

Five different tools for the qualitative and quantitative evaluation of registration are available. These tools work for 2D, 3D and 4D images.

4.2.1. Synchronized navigation

Probably the most simple but useful tool to visualize and compare up to four images at the same time. By combining the four different viewer panels and temporal capabilities, sophisticated synchronized navigation between several images orientations or time sequences can be achieved. Pixel values of each synchronized images at current cursor position are available.

4.2.2. Image fusion with complementary-colors

One conventional approach to qualitatively evaluate the result of an image registration procedure consists in comparing the reference image with the other image deformed by the sought transformation. Overlapping the two images allows to visualize the differences between the reference and registered images. VV provides an image fusion tool which merges two images into a single one : the image differences are enhanced with two different colors (for positive and negative differences) while the pixel color tends to the original grey levels when differences are low. Such approach is similar to the one used in the XVI software from Elekta which has proven useful for image comparison. The choice of the two complementary colors can be customized by the user with a simple slider. Both spatial (between slice) and temporal navigation remains as previously described. Pixel values and difference values at current cursor position are indicated in the left panel. This feature is for example used to overlay a reference 3D image onto a 4D image in order to appreciate the organs displacement with respect to the reference.

4.2.3. Image fusion by transparency

The last image comparison tool consists in superimposing two images with a given user-defined opacity value and colormap. Such feature is for example used for image comparison in the field of registration procedure, but is also used, in the field or radiation therapy, to superimpose computed dose distributions onto an anatomical image. Multimodality registration could also benefit from this tool. Pixel intensity range of the fusion image must be between [0-1000] (that will be changed in the future).

4.2.4. Deformation field visualization

Deformable registration results are often obtained in the form of deformation fields which represent the displacement of each image pixel from the reference image to the other image. In addition to quantitative analysis, we believe that it is important that researchers and clinicians can visualize such data. Conventional image differences such as the one described previously allow a fast evaluation of the registration result. However, it is well known that, as deformable registration is an ill-posed problem,a perfect match between the deformed image and the reference image can be obtained even though the deformation field itself is false. In order to evaluate a given registration, it is thus required to appreciate not only image differences but also the deformation field itself. However, it is not easy to visualize such a large amount of data : for example a typical deformation field encompassing the breathing motion of a 4D CT image of the thorax is a R3 -> R4 function, which can be represented by a 512*512*141*10 3D vectorial imagepopi-model. VV allows to load and display such data by superimposing on a given slice a set of 2D arrows representing the displacement vector at each point, projected according to the slice orientation. The sampling of the deformation field can be modified to increase or decrease the number of displayed vectors. This is for example useful when zooming (more vectors can be displayed when a large zoom factor is used), or to adapt the navigation speed according to the hardware capabilities. Components and norm of the displacement vector at current mouse position is continuously displayed in the 'Overlay' tab. In our group, this tool is used to quickly evaluate the results of a deformable registration algorithm or helps clinicians to quantitatively evaluate the displacement of a specific point in the image.

4.2.5. Landmark placement

The previously described features are mainly dedicated to qualitative and visual analysis. One of the most common ways to evaluate quantitatively a registration consists in computing the distance between anatomical landmarks defined by experts on both images to be registered. The tab 'landmarks' allow very simple landmarks selection : the physicians should press the space bar at the current mouse location to define a landmarks, displayed on the image. The set of labels can then be saved in a text file for further evaluation study.

4.3. Misc tools


4.4. Alternative/related software

The following software can also be used to display medical images :


5. FAQ

Here are a few known problems that we have encountered in the past. However if you do fall upon any new bug please feel free to report it here.

Binaries that you can download on this page are generated with specific Graphic Cards. Using these, the software may not work as fast as it is supposed to. That is why we advise you to compile your own VV version using source code. This way, it will be adapted to your own Graphic Card.

On win32 operating systems, memory allocation for a process is limited to 2Gb. Furthermore, when loading an image, memory must be allocated in a contiguous way. Using full resolution data, you may encounter problems opening images with the error message : " ... Description: Failed to allocate memory for image."

For now, the only way to shunt this problem is to use split files and to open them using menu "Merge images as one". 64 bits operating systems do not have such a limit.

On Linux, using vv with Compiz or advanced graphical desktop features have sometimes shown large degradation in performance. With NVIDIA card, you may have to use the following configuration option before using vv :

nvidia-xconfig --composite
nvidia-xconfig --render-accel
nvidia-xconfig --add-argb-glx-visuals -d 24

Some bugs in NVidia drivers affects vv with certain NVidia's card, leading to segfault on image rendering. Desactivating multithreading in OpenGL solves some of these bugs. You can do it with the following command :

export __GL_SINGLE_THREADED=1

To completely solves NVidia's issues you can download a recent nvidia driver >= 295.20

complete -A file -X '*.raw' vv

Set ITK_USE_SYSTEM_TIFF to ON

Different PNG and/or zlib libraries are used by vtk, gdcm, itk, qt and/or vv. Change itk and vtk cmake options, e.g., for ITK, to

ITK_USE_SYSTEM_PNG:BOOL=ON
ITK_USE_SYSTEM_ZLIB:BOOL=ON

With Linux, you have to install some complementary Qt5 libraries. You can find them with your favourite package manager:

libqt5WebKit5-dev
libqt5WebKitWidgets5-dev
qttools5-dev (or libqt5-qttools-devel)
qttools5 (or libqt5-qttools)

But a problem of pointer slowness can be detected. In a such case, we recommend you to install Qt5 using the source available here and follow the instruction in the compilation section.

You can build clitk tools to use main functionality of vv with command line. A help for all tools is availablehere.

Be sure to compile vv with a version of gcc using an older version of c++ than c++11.

We know, it's a choice. The voxel value display in the cross pointer panel is the value of the interpolated image (eg.: after a registration) and the mouse pointer value is the original one.

6. Developers

Want to help ? You can contribute by posting bugs or feature requests to: Bug Tracker. Tests can be carried out with the following test template (it's still under construction, so contributions are of course welcome).

You could also subscribe to our VV mailing list and follow the latest developments and features via Mailing List

6.1. Coding style

void Foo(bool isFoo)
{
  if (isFoo) {
    bar();
  } else {
    anotherBar;
  }
}

//--------------------------------------------------------------------
void myFunc()
{
}
//--------------------------------------------------------------------

astyle can be used to reset a file:

astyle --lineend=linux --indent=spaces=2 --brackets=linux --keep-one-line-statements toto.cxx

or a bunch of files:

find -iname "*.?xx" -exec astyle --lineend=linux --indent=spaces=2 --brackets=linux --keep-one-line-blocks {} \;

Note that kitware uses uncrustify for its code.

vv (last edited 2019-06-17 09:55:20 by ThomasBaudier)