VTK README


Welcome To The Visualization Toolkit

Introduction

VTK is an open-source software system for image processing, 3D graphics, volume rendering and visualization. VTK includes many advanced algorithms (e.g., surface reconstruction, implicit modelling, decimation) and rendering techniques (e.g., hardware-accelerated 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. 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 directory "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:

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:

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

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