CS53000 - Spring 2021
Assignment 0 - VTK Installation and Testing

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.

If You Plan To Use Python

If you intend to use Python to complete the programming assignments, you are in luck. If Python is not already installed on your system, you can download it from python.org or by manually selecting the binary corresponding to your operating system in the list available here. Note that you will need to use Python 3 in this class (this will save unnecessary headaches on my end). For the same reason, I will ask you to install version 3.7 or later.


With Python installed in your machine, you will simply use pipto install VTK. Before you do so, you may want to double check that your specific setup is not among the special cases discussed here. With that out of the way, all that is left to do is to run:


> pip install vtk


If You Plan To Use C++

If you prefer to use C++ for the programming assignments, you will need to build VTK. Depending on your platform, and assuming that you do not intend to modify the VTK source code, this may be as simple as to use a package manager. Otherwise, you will need to build and install VTK from source. These various cases are considered below.

If You Are Using a Mac

Under OSX, VTK can be installed effortlessly using widely used package managers. In particular, both Homebrew and Macports offer installations of VTK version 8 with the necessary header files to write your own VTK applications. Make sure to select a variant that supports Qt5 (this happens by default with Homebrew).

If You Are Using Linux

Under Linux, package managers can also be used to install VTK. In the case of Ubuntu, version 7.1 of VTK is available with Qt support. Similarly, Fedora offers recent versions of VTK with separate Qt bindings.


In all other cases, you will need to build VTK from source...

If You Need To Build VTK From Source

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 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). Regardless whether you plan to use Python or not as your programming language in assignments, you should activate VTK_WRAP_PYTHON. Many examples found on the VTK Wiki are written in Python, therefore it is useful to enable them even if you only plan to use C++. 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.15.2 for VTK 8.9 and here is the corresponding configuration under Ubuntu Linux for VTK 8.9.

For OSX/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 you managed to install VTK successfully, you should now be able to run the examples that come with VTK source code. Assuming that your VTK installation supports Python (which will be the case if you followed any of the instructions above), you next and final step consists in running a few Python examples that will test the main VTK functionalities. If you installed VTK from source, these examples will be found under <SOURCE_DIR>/Examples. If not, I am attaching at the bottom of this page the python programs and data files that you will need to perform the tests discussed below.

Cow slicing

The first example is located under <SOURCE_DIR>/Examples/VisualizationAlgorithms/Python/ in the source code.


python ClipCow.py


Note that the program will look for the cow dataset in the VTK_DATA_ROOT directory. If you did not install VTKData or if that directory is not defined by an environment variable (see corresponding explanations above), you can specify the data path directly on the command line.


python ClipCow.py -D data_dir


where data_dir is the path to the datasets. Note that VTK datasets are then expected to be found under data_dir/Data. If you are using the attached files, simply use the current directory as path.


python ClipCow.py -D .


Air flow in an office

The second test program is found in the same directory as ClipCow.py.


python officeTubes.py



Use the same instructions as previously to specify the data location if you did not install VTKData or if VTK_DATA_ROOT is not defined.


CAD part

The next example is found under <SOURCE_DIR>/Examples/Rendering/Python/ in the source code directory.


python CADPart.py



Head Slicing

The final example is located under <SOURCE_DIR>/Examples/VolumeRendering/Python in the source code directory.


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

Programs and Datasets

For your convenience, I am providing you with a tar file containing all the Python programs and datasets needed to perform the tests above.

project0_data.tar.bz2.


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