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

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

Bug Tracker, CDash.


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@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

2.1. Binaries

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

An archlinux package named vv is available through AUR.

Nightly build.

Latest release is v1.3 (October 2012).

brew install vtk --qt
brew install --HEAD http://www.creatis.insa-lyon.fr/~dsarrut/vv/vv.rb

(use with --HEAD option for compilation from git, or without --HEAD for the stable 1.3 release)

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 git://git.creatis.insa-lyon.fr/clitk vv

Releases:

2.3. 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.

Alternatively, we provide a superbuild CMakeLists.txt that automatically do all steps (QT, VTK, ITK and VV) for static compilations. In that case, you only need to have CMake and a compiler installed, download the CMakeLists.txt file and run

cmake superbuild-file-directory
make

where superbuild-file-directory contains the CMakeLists.txt file.

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.

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

git clone git://gitorious.org/qt/qt.git

Compilation instructions are available here.

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 5.6.1 and 5.10.1. We recommend to use the archives rather than the git but if you like living on the edge, you can download the source code here or via git:

git clone git://vtk.org/VTK.git vtk
git checkout v5.6.1

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

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

You need to change the following build options for VV:

Set VTK_USE_QT to ON
Set VTK_USE_QVTK_QTOPENGL to ON

NB:

3.4. ITK v3

ITK is an open-source, cross-platform system that provides developers with an extensive suite of software tools for image analysis.

Vv is tested with ITK 3.20.0. You can alternatively download the source code here or via git:

git clone git://itk.org/ITK.git itk
git checkout v3.20.0

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

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

NB: it is preferable to use the following options for registration:

Set ITK_USE_REVIEW to ON
Set ITK_USE_OPTIMIZED_REGISTRATION_METHODS to ON

3.5. ITK v4 (alternatively to ITK v3)

ITK v4 is still under development, vv git sources try to stay compatible with ITK v4 git sources.

The tagged version v1.2.0 of vv is compatible with itk v4.0a07:

git clone git://itk.org/ITK.git itk
git checkout v4.0a07

In CMake:

Set ITK_BUILD_ALL_MODULES to ON

3.6. VV

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


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

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 2014-02-04 07:09:11 by SimonRit)