# Welcome To The Visualization Toolkit

- Introduction
- Copyright Notice
- Organization
- Documentation
- Compilation
  - Building with CMake
  - Configuration Options in CMake
- Installation
- Common Problems
- Getting Data
- Running VTK
- Adding A New Class
- Getting Help / Mailing List

# Introduction

VTK is an open-source software system for image processing, 3D graphics, and visualization. VTK includes many advanced algorithms (e.g., surface reconstruction, implicit modelling, decimation) and rendering techniques (e.g., volume rendering, LOD control).

VTK is used by academicians for teaching and research; by government research institutions such as Los Alamos National Lab in the US or CINECA in Italy; and by many commercial firms who use VTK to build or extend products.

The origin of VTK is with the textbook "The Visualization Toolkit, an Object-Oriented Approach to 3D Graphics" originally published by Prentice Hall and now published by Kitware, Inc. (Third Edition ISBN 1-930934-07-6). VTK has grown (since its initial release in 1994) to a world-wide user base in the commercial, academic, and research communities.

This README is written for VTK version 5.0 and greater. For more information, additional resources, and the FAQ see the web page at http://www.vtk.org

# Copyright Notice

VTK has a generous open-source copyright modelled after the BSD license. Yes, you can use VTK in commercial products. The complete text of the copyright follows.

    Copyright (c) 1993-2005 Ken Martin, Will Schroeder, Bill Lorensen
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

     * Redistributions of source code must retain the above copyright notice,
       this list of conditions and the following disclaimer.

     * Redistributions in binary form must reproduce the above copyright notice,
       this list of conditions and the following disclaimer in the documentation
       and/or other materials provided with the distribution.

     * Neither name of Ken Martin, Will Schroeder, or Bill Lorensen nor the names
       of any contributors may be used to endorse or promote products derived
       from this software without specific prior written permission.

     * Modified source versions must be plainly marked as such, and must not be
       misrepresented as being the original software.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

# Organization

The VTK source code repository is organized into four major sections.

- The toolkit source code is found in the following directories next to this README. In some cases an additional README.html file may be found in the named directory. Please see these for more information.
  - Common- Core classes commonly used by other kits
  - Filtering- Pipeline implementation superclasses
  - Rendering- Classes used to render visualizations
  - Graphics- Filters that process 3D data
  - Imaging- Specialized image processing filters
  - IO- Classes for reading and writing data
  - VolumeRendering- Classes for rendering volume visualizations
  - Hybrid- Complex classes that depend on imaging and graphics
  - Widgets- Classes for interactive visualizations
  - Parallel- Parallel processing support such as MPI
  - GenericFiltering- Part of an adaptor framework supporting integration of VTK with external systems

- Examples that are reasonably well documented are found in the VTK/Examples directory. You may wish to start with the examples found in the Tutorial directory.

- The Utilities directory includes things like jpeg, png, and zlib source code. This code is used by VTK in various ways (reading/writing data, etc.)

- The Wrapping directory contains code related to VTK's automated wrapping process. The wrapping process automatically generates Tcl, Python, and/or Java bindings depending on how the build process is configured.

There are hundreds of testing examples located in the Testing/ directory under each source code directory (e.g., Graphics/Testing). These are undocumented tests but can be helpful in some cases.

# Documentation

The ideal way to learn about the software is from two books: The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics and The VTK User's Guide both published by Kitware, Inc. (Note: The Visualization Toolkit was originally published by Prentice-Hall, the third edition is published by Kitware.) You may order the books from the following locations (Amazon.com also carries the books.)

      The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics (Third Edition)
      by Will Schroeder, Ken Martin and Bill Lorensen.
      Kitware, Inc.,
      ISBN 1-930934-07-6
      http://www.kitware.com/products/vtktextbook.html

      The VTK User's Guide (VTK 4.2 Edition)
      Kitware, Inc.,
      ISBN 1-930934-08-4
      http://www.kitware.com/products/vtkguide.html

On-line Doxygen man pages are also available at http://www.vtk.org/doc/nightly/html/

# Compilation

The Visualization Toolkit can be built on UNIX, PC (Windows 95/98/NT/2000/XP), and Mac OSX Jaguar (or greater) systems. VTK uses CMake to generate its build system. To build VTK one must first install CMake version 2.0 or higher. CMake may be downloaded from http://www.cmake.org/HTML/Download.html. The instructions below cover the basics of running CMake for VTK under the assumption that CMake is already installed. See the CMake web page for details on intalling and running CMake.

Compiling VTK requires a complete VTK source tree. Running VTK tests requires a complete VTK data tree. Now is the time to extract the source and data archives if one has not done so already. These instructions assume there is a directory "`VTK`" containing the source code and optionally a sibling direcory "`VTKData`" containing the data.

## Building with CMake

CMake must be run to generate a build system for VTK. The build system may be placed either in the VTK source tree (an in-source build) or in a separate binary tree (an out-of-source build). We strongly encourage use of out-of-source builds because they make it easy to have multiple builds with different configurations sharing the same source tree. Once a single in-source build has been created it is the only build tree that can be associated with that source tree. A source tree may not be used both for an in-source build and an out-of-source build, but any number of out-of-source builds may share a source tree that does not have an in-source build. Having multiple out-of-source builds is particularly useful for installing VTK on multiple architectures using a single source tree on a shared disk.

CMake provides both a command-line tool and interactive interfaces. Advanced users may wish to use the command-line tool but here we document the CMake interactive interface for each platform:

- Windows
  Run the CMakeSetup dialog to get started. It must be executed from an environment configured to run the compiler to be used. In the case of the Visual Studio IDE no special environment is needed and CMakeSetup can be started from its icon. In the case of a Visual Studio NMake, Borland C++, or MinGW build the CMakeSetup dialog should be executed from a command prompt with the appropriate environment set.

  The dialog prompts for the location of the source and binary trees. There may also be prompt for the build system generator to be used ("Build For:"). Once these are set then CMake is ready for a first pass at configuring the VTK build system. Use the "Configure" button to initiate this process. If there was no earlier prompt for the build system generator a separate dialog will appear during the first configuration step to prompt for generator selection. After a while the dialog will present a set of configuration options. See below for details on the meaning of each of these options. After setting the options as desired press "Configure" again to make another pass at configuring VTK. New options may appear when earlier options are adjusted. Keep adjusting options and pressing "Configure" until the desired configuration is reached. Finally press the "Generate" button to actually generate the build system.

  Now that the build system has been generated the corresponding native tools can be used to build VTK. In the case of the Visual Studio IDE simply run it and load the VTK workspace or solution file from the binary tree specified in the CMakeSetup dialog. Select and build the `ALL_BUILD` target. In the case of a Visual Studio NMake, Borland C++, or MinGW build use the corresponding make tool (`nmake`, `make`, and `make`, respectively) from the command line.

- UNIX / Cygwin / Mac OSX
  CMake should be run from the command line on these platforms. The current working directory should be set to the desired binary tree location in which the build system should be generated. One command-line argument is used to specify the location of the source tree. CMake will usually choose the system C and C++ compilers automatically but it can be told to use specific compilers through the "`CC`" and "`CXX`" environment variables.

  A typical in-source build for VTK might look like this:

  > `$ ls -d VTK
  > VTK/
  > $ cd VTK
  > $ ccmake .
  > $ make
  > `

  A typical out-of-source build for VTK might look like this:

  > `$ ls -d VTK
  > VTK/
  > $ mkdir VTK-build
  > $ cd VTK-build
  > $ ccmake ../VTK
  > $ make
  > `

  In the above examples the call to `ccmake` may be replaced by

  > `$ env CC=/your/c/compiler CXX=/your/C++/compiler ccmake /path/to/VTK
  > `

  in order to tell CMake to use specific C and C++ compilers. Setting the environment in this way will only change the compilers the first time CMake is run for a specific build tree. Do not attempt to change the compiler of an existing build tree. Instead one should create a separate build tree for each desired compiler.

  The `ccmake` tool is a curses-based dialog that may be used to interactively configure VTK. When it appears press 'c' on the keyboard to run the initial configuration of the VTK build system. Eventually a set of configuration options will appear. These may be edited using the arrow-keys and the ENTER key for navigation. See below for details on the meaning of each of these options.

  Once the options have been set as desired press 'c' again to reconfigure. New options may appear when earlier options are adjusted. Keep adjusting options and pressing 'c' until the desired configuration is reached. Finally press 'g' to actually generate the build system. Now that the build system has been generated just run `make` or `gmake` to build VTK.

  NOTE: The `ccmake` curses dialog is the most commonly used interactive interface for CMake on UNIX-like platforms, so these instructions assume it is available. Some system administrators may not have installed curses in which case `ccmake` will not be available. On these platforms one may use the command "`cmake -i`" in place of `ccmake` and follow the on-screen instructions to configure VTK. A last resort is to use the command-line interface to `cmake`, but that is beyond the scope of this document. See CMake documentation for further details.

## Configuration Options in CMake

VTK is a large toolkit providing a wide variety of functionality. Several configuration options are available to customize the VTK build system. These options are configured through an interactive CMake interface as described above. Note that not all options are available on all platforms, and some options are available only when other options are set to a particular value.

The interactive CMake interface provides brief documentation for every option. Some options have more meaning than can be described in one sentence, so additional documentation is provided here:

- BUILD_SHARED_LIBS

  Sets whether the compiled VTK libraries will be shared libraries or static libraries. When linking executables against static libraries the needed symbols will be copied from the libraries into the executables enabling them to run without access to the original libraries. When linking executables against shared libraries references to the symbols are placed into the executables. This has the advantage that many executables can share a large library without producing many copies of its code.

  Shared libraries have the disadvantage that they must be found at runtime in order for an executable to run. Each operating system supporting shared libraries has a component known as the dynamic loader. This component is responsible for finding the shared libraries needed by an executable when it is run. In order to run VTK executables from the build tree when using shared libraries one may need to help the dynamic loader find the libraries (usually the bin subdirectory of the build tree).

  On Windows, the dynamic loader will look for shared libraries in the directory containing the executable, in directories listed in the PATH environment variable, and in some system directories. Since VTK places all of its executables and libraries in the same directory nothing needs to be set to get them to run. However, when one builds outside projects against VTK the PATH environment variable must be set to point at the directory containing the VTK shared libraries.

  On UNIX-style platforms, the dynamic loader will use an environment variable such as LD_LIBRARY_PATH (Linux and many UNIX systems) or DYLD_LIBRARY_PATH (Mac OSX) to look for shared libraries. In order to run VTK executables from the build tree one must set the appropriate environment variable to point at the directory containing the VTK shared libraries (unless VTK_USE_RPATH is ON, see below). The same environment setting must be used for running outside projects build against the shared VTK libraries.

- VTK_USE_RPATH

  This option is available on non-Windows platforms when the BUILD_SHARED_LIBS option is set to ON. It enables/disables the use of the rpath (runtime-path) feature available on most UNIX-style platforms. If this option is enabled VTK libraries and executables will be linked with an rpath pointing at the location in the build tree containing them (usually the bin subdirectory). This allows them to run from the build tree without setting any environment variables to help the dynamic loader find the needed shared libraries.

  Warning: enabling VTK_USE_RPATH DISABLES THE INSTALL TARGET so that the build cannot be used to install VTK! This is necessary because the installed executables and libraries would contain references back to the build tree. Running them would load libraries from the build tree, which may have been updated or built with an incompatible configuration since the last installation. VTK release versions set this option to OFF by default so that it is easy to build and install VTK from a source distribution. VTK development versions set this option to ON by default so that dashboard builds and developers (which typically have many VTK build trees) can run without setting any environment variables for the dynamic loader.

- VTK_WRAP_TCL

  Enable/Disable automatic generation of VTK bindings in the Tcl language. In order to build the Tcl-based VTK interpreter one will need to have Tcl and Tk version 8.2 or newer. Look to http://www.tcl.tk for information about getting Tcl and Tk. To turn on Tcl wrapping, set VTK_WRAP_TCL to ON during the configuration process. One may then have to set the values for Tcl/Tk include directories and libraries during the next CMake configure iteration. If there is more than one version of Tcl installed on the computer, make sure all the TCL_* and TK_* configuration options are set consistently to use the proper version. This is especially important when Cygwin is installed because the Cygwin Tcl will not work for a native Windows VTK build and a Windows Tcl will not work for a Cygwin VTK build. When building the Tcl/Tk wrappers on Cygwin one must also install the Cygwin sources for Tcl/Tk and set TK_XLIB_PATH to "/usr/src/tcltk-20030901-1/tk/xlib" or the corresponding directory for one's Cygwin Tcl version. See Wrapping/Tcl/README for details on using the Tcl wrappers once they are built.

- VTK_WRAP_PYTHON

  Enable/Disable automatic generation of VTK bindings in the Python language. In order to build the Python-based VTK interpreter one will need to have Python installed. Look to http://www.python.org for information about getting Python. To turn on Python wrapping, set VTK_WRAP_PYTHON and BUILD_SHARED_LIBS to ON during the configuration process. One may then have to set the values for Python include directories and libraries during the next CMake configure iteration. If there is more than one version of Python installed on the computer, make sure all the PYTHON_* configuration options are set consistently to use the proper version. This is especially important when Cygwin is installed because the Cygwin Python will not work for a native Windows VTK build and a Windows Python will not work for a Cygwin VTK build. In order to use Tkinter with VTK-Python make sure that the Tcl/Tk libraries that are set correspond to the same version used by Tkinter.

  Note that the VTK-Python modules are now installed by default via 'make install', which is a change from previous VTK versions. The automatic python module installation is highly configurable. The Wrapping/Python/README.txt file documents the installation procedure and the VTK-Python modules.

- CMAKE_INSTALL_PREFIX

  When VTK is installed all files are placed in a directory structure rooted at the directory specified by CMAKE_INSTALL_PREFIX.

# Installation

Installing VTK from a source distribution requires first that it be compiled in a build tree. See the compilation section above for details. Once VTK has been compiled in a build tree one may build the install target to actually put VTK in an installation tree. If VTK was built using a CMake Makefile generator then this is done by running "make install" from the top of the build tree. If VTK was built using a CMake project file generator (such as Visual Studio), then building the INSTALL project from inside the IDE will install VTK. The installation process will install all files in a directory structure rooted at the directory specified by CMAKE_INSTALL_PREFIX.

# Common Problems

- Strange compile errors on UNIX, typically involving system headers and types. Make sure that you specify the environment variables CC and CXX prior to running CMake. If you have already run CMake you must create a fresh build-tree and start again. If you ran CMake in the source tree then you must delete the source tree, re-extract the sources, and start again.
- Errors on Tcl or Tk include files or libraries. Make sure that you set the TCL_* and TK_* configuration variables to the correct location when running CMake.
- Link errors on Windows platforms. Make sure that the swap space is at least 300 MByte.
- Link error with borland: TCL82.LIB contains invalid OMF record, type 0x21 (possibly COFF). You have to convert Tcl libraires from coff to omf with the Borland utilitiy coff2omf. Once you have created OMF versions, re-run cmake to tell it where the Borland versions of Tcl and Tk are located. Also, make sure that you are using Tcl/Tk 8.3.2.

# Getting Data and Test Images

Many of the examples require data. There are two ways to get data. The first is to download the file VTKData.tgz. The second is to access the data via CVS checkout. The CVS checkout also includes many test images used by the testing process (see http://public.kitware.com/dashboard.php). These can be used if you wish to test VTK or submit testing dashboards. The VTKData.tgz contains only data in compressed form is therefore can be obtained much faster.

      1) Download the data at ftp://public.kitware.com/pub/vtk/VTKData.tgz

      2) Checkout the data from CVS using the folling commands:
         cvs -d :pserver:anoncvs@www.vtk.org:/cvsroot/VTK login
            (there is no password...just press enter)
         cvs -d :pserver:anoncvs@www.vtk.org:/cvsroot/VTK checkout VTKData

# Running VTK

Many C++ examples will be compiled if BUILD_TESTING and/or BUILD_EXAMPLES are enabled in CMake. To run these C++ examples just type their name. (They will be found in the binary build directory.) If you have built shared libraries, make sure the PATH environment variable (Windows) or the LD_LIBRARY_PATH (Unix) point to the shared libraries (see above documentation of the BUILD_SHARED_LIBS for details). If you have enabled Tcl wrapping, you will want to set TCLLIBPATH to point to the VTK/Wrapping/Tcl directory and check the instructions located in the Wrapping/Tcl/README file. You will then run the VTK executable found in the bin directory where the code was compiled. Assuming that the executable VTK is in your path, or has been aliased, you would type:

      vtk mace.tcl

Note that most Tcl scripts allow you to type "u" in the render window to obtain an interpreter. You can use the interpreter to modify the application at run-time.

If you have enabled Python Wrapping you should read the instructions located in the Wrapping/Python/README.txt file.

# Writing Your Own Class

There are several ways to extend VTK. The simplest way is, in your own code, create classes that inherit from the appropriate VTK classes. Please see the `vtkLocal` example for instructions to build your classes outside VTK.

# Getting Help / Mailing List

For general information go to the VTK web site http://www.vtk.org

If you run into problems, your best bet is to join the VTK mailing list. Visit http://www.vtk.org/mailman/listinfo/vtkusers to join the list.

Commercial support contracts are available from Kitware at http://www.kitware.com/products/vtksupport.html.

Kitware also provides consulting services. Read more at http://www.kitware.com/products/consult.html.

Training is also available from Kitware. See http://www.kitware.com/products/vtktrain.html.