CS530 - Spring 2018
Project 0 - VTK Installation

A prerequisite to any actual visualization work in this class is to install VTK on your local machine and ensure that it works properly. VTK is an open source library written in C++ that has been successfully tested on all sorts of platforms and most operating systems. In particular, Windows, Mac OSX, and Linux are all extremely well supported. A fair amount of documentation designed to help users and potential developers is available in the VTK Wiki. The instructions below can mostly be found in the Building VTK rubric.

Prerequisites

To install VTK according to the instructions below you must first ensure that you have a C++ compiler installed on your machine. If you are using a Windows computer, you will need Visual Studio, which you can obtain for free from ITaP. If you are using a Linux machine, you should not have to do anything since compilers are usually part of the standard installation. Finally, if you are using a Mac, you will need to install the developer SDK on your machine if you have not done so already.

If you are using OSX you will need to install the latest version of XCode and the associated command line developer tools. Corresponding explanations are provided here.

Getting VTK

There are two ways to acquire the source code of VTK. Both are equally valid options for this class.

Since you downloaded the C++ source code of VTK, the next step is now to compile the software using CMake. Before you do so however, you should download the datasets that are used by the examples.

Getting VTKData

The examples that come with VTK make use of a number of interesting datasets that you should download as well. This will help you familiarize yourself with the syntax of typical VTK programs by running the examples and see what they do. The latest version of the data is available here. Download it and unpack it to a convenient location.

You then need to set an environment variable named VTK_DATA_ROOT to the path of VTKData to let VTK know where to find it. The procedure to set an environment variable in Windows varies depending on the version of Windows that you have. This is explained here.

Under Linux or OSX you can define an environment variable in the current shell by typing:

setenv VARIABLE value

if you are using csh (or tcsh). If you want that variable to be set globally, you need to add that declaration to the .cshrc (or .tcshrc) file in your home directory. If you are using bash, the corresponding syntax is

export VARIABLE=value

and that line should be added to .bashrc to make the change global.

Getting CMake

CMake is an open source cross-platform build system. You can download a version of CMake compatible with your operating system here. Note that CMake can either be installed from source or downloaded directly in executable format. I recommand that you choose the latter option and download the most recent binary distribution of CMake. If you choose to install CMake yourself, instructions are provided here.

Building VTK with CMake

Now that you have installed a compiler, downloaded the VTK source code, and installed CMake, you have assembled all the pieces necessary to build VTK. The instructions do so on Windows, Linux, and Mac are provided here. If you are on a Windows machine, keep in mind that Visual Studio will be necessary. If you have a Linux machine or a Mac, the instructions are fundamentally identical (you simply need to use Terminal under Mac).

Assuming that you have installed the VTK source under directory <SOURCE_DIR>(*) (say “~username/code/VTK”), on Mac/Linux, to bring up the CMake interface for configuration:

mkdir <SOURCE_DIR>/build

cd <SOURCE_DIR>/build

ccmake ..

Under ccmake, you will initially find an empty cache. Initialize the cache by typing ‘c’ (for configure). This may take a little while depending on your machine. At this stage, CMake is looking through your computer to determine what it is and what programs and libraries are available.

On Windows, simply open CMake, and put in <SOURCE_DIR> as the source code location, and <SOURCE_DIR>/build as where to build the binaries. Click Configure, and select the Visual Studio version you have installed on your computer, then CMake will create an initial configuration.

Once CMake has completed this initial inspection, some parameters would need to be modified. Make sure to select BUILD_EXAMPLES and BUILD_SHARED_LIBS (type return to toggle between ON and OFF) and replace Debug by Release under CMAKE_BUILD_TYPE (On Mac/Linux, typing return once activates the edit mode, typing it again exits the edit mode). If you plan on using Python or TCL as your programming language in assignments, you would need to activate VTK_WRAP_PYTHON or VTK_WRAP_TCL respectively. Otherwise, if you plan to use C++ for your programming assignments, those 2 options are not necessary. Many examples found on the VTK Wiki are written in Python and TCL, therefore it may be useful to enable them even if you only plan to use C++. VTK_WRAP_JAVA is optional and will only be useful if you use Java as your programming language. Under VTK_DATA_ROOT you should see the location at which you installed VTKData (which CMake picked up from the environment variable). If you have QT installed on your machine, you may select VTK_GROUP_QT. On a Mac, you should make sure that VTK_USE_COCOA is selected and VTK_USE_CARBON is not. Once this is done, configure again (type ‘c’ or press the Configure button again). If your selection caused additional parameters to be automatically set by CMake, those will appear preceded by an asterisk. Configure one last time to rerun the configuration with those parameters. For what it is worth, here is a screen shot of the configuration that I obtained under OSX 10.8.4 for VTK 6.1 and here is the corresponding configuration under Linux for VTK 6.0.0.

For Max/Linux, if the reconfiguration was successful, you should now see “Press [g] to generate and exit” at the bottom of your window. Type ‘g’. CMake should exit after having generated a Makefile. Once back to the shell, simply type

make

(and wait). It may take a really long time (in the ballpark of several hours) if your machine is slow. If you have a parallel processor (most computers do these days), you can speed up the build process by running make in parallel through

make -j <N>

where <N> is the number of threads available on your machine. On a laptop, 2 or 4 are likely numbers while on a desktop computer you should have between 8 and 16 threads. Note that threads and cores are different things and that hyperthreading allows a machine with n cores to run 2 x n threads (e.g., a quadcore machine can run 8 threads in parallel).

On Windows, after successful configuration, press Generate, and then Open Project. It will open up the Visual Studio with the solution loaded. Select "Release" as your build configuration, and then build the project (Menu -> Build -> Build Project).

Making Sure that Things Work

If the build completed successfully, you should now have produced two executables named vtk (if you selected the Tcl wrapper) and vtkpython (if you selected the Python wrapper). If you compiled VTK under Windows, the executables are located under <SOURCE_DIR>\build\bin\release. Under OSX or Linux the executables will be under <SOURCE_DIR>/build/bin. In the following, I refer to the location of these executables as <EXEC_DIR>.

The easiest way to verify that things work as they should is now to try and run some of the VTK examples that come with the source code. These examples are located under <SOURCE_DIR>/Examples. Here are a few examples of what you should be getting.

<EXEC_DIR>/vtkpython <SOURCE_DIR>/Examples/VisualizationAlgorithms/Python/ClipCow.py

<EXEC_DIR>/vtkpython <SOURCE_DIR>/Examples/VisualizationAlgorithms/Python/officeTubes.py

<EXEC_DIR>/vtkpython <SOURCE_DIR>/Examples/Rendering/Python/CADPart.py

<EXEC_DIR>/vtkpython <SOURCE_DIR>/Examples/VolumeRendering/Python/VolumePicker.py

If your installation runs these examples correctly, you should be set. If you encountered any problem along the way, please consult the discussion forum titled “VTK Installation” on Piazza.

(*) Make sure that this directory contains the file CMakeLists.txt.