David Sarrut, Pierre Seroul, Joël Schaerer, Simon Rit, Jef Vandemeulebroucke, Bharath Navalpakkam, Gauthier Bouilhol, Romulo Pinho, Vivien Delmon and Maxime Pech, firstname.lastname@example.org (Mailing List Subscription)
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 email@example.com briefly describing your use of vv. When using it for publications, please make reference to the article:
Seroul, P. and Sarrut, D. VV : Viewer for the evaluation of 4D image registration. 2008. presented at the MICCAI workshop Systems and Architectures for Computer Assisted Interventions. pdf bibtex
This work is still in progress, we welcome any advice or opinions that can make this software more useful.
2. Download VV
Binaries are provided without any warranty. We advise you to compile it yourself.
An archlinux package named vv is available through AUR.
Latest release is v1.3 (October 2012).
MacOS : use brew. VV requires vtk to be compile with --qt option, so you need to brew install the two packages. Please, type the following commands to download and compile everything:
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).
Fedora package (thanks to Fabrice Bellet): https://www.creatis.insa-lyon.fr/linux/fedora/13/i386/os/Packages/vv-1.2-4.fc13.i386.rpm (users of other versions of Fedora or of other architectures should adjust the URL accordingly).
v1.1 (July 2010).
Fedora package (thanks to Fabrice Bellet): https://www.creatis.insa-lyon.fr/linux/fedora/13/i386/os/Packages/creatis-release-13-2.noarch.rpm (users of other versions of Fedora or of other architectures should adjust the URL accordingly).
Windows 32 bits zipped
Windows 64 bits zipped
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
October 2012: vvSource-1.3.tar.gz
May 2011: vvSource-1.2.tar.gz
July 2010: vvSource-1.1.tar.gz
July 2008: vvSource-1.0.tar.gz
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:
The Gengetopt dependency is now optional, source code has been included in the vv source repository.
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.
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.
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.
The Visualization Toolkit (VTK) is an open-source, freely available software system for 3D computer graphics, image processing and visualization.
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
- If you are using a MAC OS, you need to enable the option VTK_USE_COCOA or VTK_USE_CARBON.
You need to specify the Qt path selecting the QT_QMAKE_EXECUTABLE binary if it is not done automatically.
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.
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
Set ITK_BUILD_ALL_MODULES to ON
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 :
- In 2 dimensions : hdr, mhd, jpeg, bmp, png, tiff, dicom...
- In 3 dimensions : hdr, mhd, dicom...
- In 4 dimensions : hdr, mhd, dicom...
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).
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
Pixel conversion: to convert the pixel type of an image, right click on the image name on the left panel, choose 'convert'.
Image resampling: in menu 'tool', choose resample with various option.
Image Arithmetic: to perform simple image unary or binary operation (addition, substraction ...)
Binarize Image: apply simple threshold (with interactive feedback)
Crop Image: crop an image
Dicom RT Struct import: in the menu 'file', select Open DicomRT Struct. Choose the different contours to be superimposed to the current image.
4.4. Alternative/related software
The following software can also be used to display medical images :
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.
- Graphic cards and binaries
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.
- Windows memory allocation failure
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
Bug with Nvidia drivers > 275.09.21 and < 295.20
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 :
To completely solves NVidia's issues you can download a recent nvidia driver >= 295.20
- What should I add to my .bashrc to exclude .raw files from the completion for vv?
complete -A file -X '*.raw' vv
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