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 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 pip
to 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
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.
There are two ways to acquire the source code of VTK. Both are equally valid options for this class.
Download the latest stable source release
By far the simplest option to obtain the source code of VTK consists in downloading the most recent stable release. At present, the latest release is 9.0.1. Corresponding instructions are available here.
Obtain VTK using Git
If you are already familiar with git and wish to benefit from subsequent VTK updates, you have the option to download VTK from the source repository. The corresponding procedure is described here. Note that this approach will provide you with a pre-release version of VTK (Version 8.9).
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.
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.
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.
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).
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.
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 .
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.
The next example is found under <SOURCE_DIR>/Examples/Rendering/Python/
in the source code directory.
python CADPart.py
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.
For your convenience, I am providing you with a tar file containing all the Python programs and datasets needed to perform the tests above.
(*) Make sure that this directory
contains the file CMakeLists.txt
.