<HTML>
<header>
<title>VTK README</title>
<!-- Created by: will schroeder, July-1997 -->
<!-- Changed by: kenneth m martin, 5-Jun-1998 -->
<!-- Changed by: will schroeder, 30-Dec-2000 -->
<!-- Changed by: Bill Hoffman, 15-Jun-2000 -->
<!-- Changed by: will schroeder, 5-Dec-2001 -->
</header>
<body>
<h1>
<IMG ALIGN="middle" SRC=vtkLogo.jpg>
Welcome To The Visualization Toolkit
</h1>
<UL>
<LI> <A HREF="#Introduction">Introduction</A>
<LI> <A HREF="#Copyright">Copyright Notice</A>
<LI> <A HREF="#Organization">Organization</A>
<LI> <A HREF="#Documentation">Documentation</A>
<LI> <A HREF="#Installation">Installation</A>
<UL>
<LI> <A HREF="#Unix">Unix Installation</A>
<LI> <A HREF="#Cygwin">Cygwin Installation</A>
<LI> <A HREF="#PC">PC Installation</A>
</UL>
<LI> <A HREF="#Problems">Common Problems</A>
<LI> <A HREF="#Data">Getting Data</A>
<LI> <A HREF="#Running">Running VTK</A>
<LI> <A HREF="#NewClass">Adding A New Class</A>
<LI> <A HREF="#Help">Getting Help / Mailing List</A>
</UL>
<HR>
<h1><A NAME="Introduction">Introduction</h1>
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).<p>
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.<p>
The origin of VTK is with the textbook "The Visualization Toolkit, an
Object-Oriented Approach to 3D Graphics" published by Prentice Hall
(ISBN 013199837-4). VTK has grown (since its initial release in 1994)
to a world-wide user base in the commercial, academic, and research
communities.<p>
This README is written for VTK version 4.0 and greater. For more information,
additional resources, and the FAQ see the web page at
<A HREF="http://public.kitware.com/VTK">http://public.kitware.com/VTK</A><p>
<HR>
<h1><A NAME="Copyright">Copyright Notice</h1>
VTK has a generous open-source copyright modelled after the BSD license. Yes,
you can use VTK in commercial products. The only caveat is that if you use
any classes (there are a small number) in the VTK/Patented directory in
commercial application, you will want to contact the patent holder (listed in
the class header) for a license. The complete text of the copyright follows.
<pre>
Copyright (c) 1993-2001 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.
</pre>
<HR>
<h1><A NAME="Organization">Organization</h1>
The VTK 4.0 source code repository is organized into four major sections.
<ul>
<li>The source code is found in the directories Common, Rendering,
Filtering, Graphics, Imaging, Hybrid, Parallel, and Patented.<p>
<ul>
<li><b>Common</b>- Core classes
<li><b>Rendering</b>- Classes used to render
<li><b>Filtering</b>- Abstract superclasses for filtering data
<li><b>Graphics</b>- Filters that process 3D data
<li><b>Imaging</b>- Specialized image processing filters
<li><b>IO</b>- Classes for reading abd writing data
<li><b>Hybrid</b>- Complex classes that depend on imaging and graphics
<li><b>Parallel</b>- Parallel processing support such as MPI
<li><b>Patented</b>- Patented classes, to be used in
commercial applications only with a license
</ul>
</li><p>
<li><B>Examples</B> 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.<p></li>
<li>The <B>Utilities</B> directory includes things like jpeg, png,
and zlib source code. This code is used by VTK in various ways
(reading/writing data, etc.)<p></li>
<li>The <B>Wrapping</B> 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.<p></li>
</ul>
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.<p>
<HR>
<h1><A NAME="Documentation">Documentation</h1>
The ideal way to learn about the software is from the book it is designed to
support. You should be able to get the book from any local bookstore or from
our web page. The web page also contains some html reference pages for the
objects in VTK as well as a FAQ.
<pre>
The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics
by Will Schroeder, Ken Martin and Bill Lorensen.
Prentice Hall, Second Edition.
<A HREF="http://public.kitware.com/VTK/buy-books.php">http://public.kitware.com/VTK/buy-books.php</A>
</pre>
You can also order the VTK User's Guide from Kitware,Inc. See the
web page <A HREF="http://www.kitware.com/products/vtkguide.html">http://www.kitware.com/products/vtkguide.html</A><p>
On-line Doxygen man pages are also available at
<A href="http://public.kitware.com/VTK/doc/nightly/html/">
http://public.kitware.com/VTK/doc/nightly/html/</a><p>
<HR>
<h1><A NAME="Installation">Installation</h1>
The Visualization Toolkit can be built on both Unix and PC
(Windows 95/98/NT/2000) systems. VTK uses <A HREF="http://www.cmake.org">CMake</A>
for its build process. To build VTK for UNIX or Windows, you will first have to install CMake.
You can download CMake from: <A HREF="http://www.cmake.org"</A>http://www.cmake.org</A>
The following instructions assume that cmake is already installed.
<p>
<h3><A NAME="Unix">Unix Installation</h3><p>
The following instructions only apply to UNIX systems.
First we will give you the quick and dirty way to build VTK:
<p>
If you will be using C++ as your development language (no Tcl/Tk, Python or Java support):
<pre>
1) untar the src files
2) untar the data files
3) cd VTK
4) cmake -i (run cmake in wizard mode, where you have to answer questions about the build)
or
4) ccmake (run the terminal based interface to cmake where you interactively change build options)
5) if necessary change build options
6) make
</pre>
It is a very good idea to tell cmake what C and C++ compilers
you will be using. This can avoid many build problems.
On most systems you can pass this information to configure in the
following way:
<pre>
env CXX=/your/C++/compiler CC=/your/c/compiler cmake
</pre>
otherwise you must set CXX and CC in your environment and then
run ccmake (or cmake -i).<p>
If you want to build the VTK interpreter then you will
need to have Tcl and Tk (8.2 or newer). Look to <A href="http://www.scriptics.com">http://www.scriptics.com</A>
for information about getting Tcl and Tk. To turn on Tcl wrapping,
set VTK_WRAP_TCL to ON during the configuration process (as a post-build step, you might want to check the <A href="Wrapping/Tcl/README">Wrapping/Tcl/README</A> file). You will then have
to set the values for Tcl/Tk include directories and libraries.
If you are planning to build VTK for multiple architectures then you can
either make a copy of the entire VTK tree for each architecture and then
follow the instructions above. Or you can have one copy of
the VTK tree and compile it in a different manner (out-of-source). Instead of
running cmake from the VTK directory, create a new directory where you have some
free disk space (not in the VTK tree), a possible name would be
vtk-solaris. cd into this directory and then run cmake similar to the
following example:
<pre>
ls /home/joe_user
vtk vtk-solaris vtk-sgi
cd vtk-solaris
ccmake /home/joe_user/VTK
or
cmake -i /home/joe_user/VTK
</pre>
This will create makefiles in the vtk-solaris directory. Then you can run
make in vtk-solaris to compile VTK. Repeate this process for each
architecture you wish to build.<p>
<h3><A NAME="Cygwin">Cygwin Installation</h3><p>
The build process for Cygwin is almost exactly the same as the UNIX build process
(see previous section)
<p>
If you will be using C++ as your development language (no Tcl/Tk, Python or Java support):
<pre>
1) untar the src files
2) untar the data files
3) cd VTK
4) cmake -i (run cmake in wizard mode, where you have to answer questions about the build)
or
4) ccmake (run the terminal based interface to cmake where you interactively change build options)
5) if necessary change build options
6) make
</pre>
For tcl/tk support, you have to install the cygwin sources for tcl/tk, then
set the following options:
<pre>
TK_INCLUDE_PATH /usr/src/tcltk-20001125-1/tk/generic/
TK_INTERNAL_PATH /usr/src/tcltk-20001125-1/tk/win/
TK_XLIB_PATH /usr/src/tcltk-20001125-1/tk/xlib
</pre>
<h3><A NAME="PC">PC Installation</h3><p>
The PC build process uses the CMake GUI CMakeSetup. Then you use the
compiler make utility to compile as follows.
<pre>
1) Install vtk 4.0 distribution by unzipping into the appropriate directory.
2) Execute CMakeSetup. This will pop-up a little
GUI that allows you to tailor the build. It then starts
building .dsw and .dsp files for microsoft, or makefiles for borland.
You'll have to tell CMakeSetup
where you've placed your VTK source code, and where to build
the object code and dll's (we'll call it "vtkbin").
3) When CMakeSetup completes, start up msdev and load VTK.dsw.
Select ALL_BUILD project, and build it.
</pre>
We recommend a 300MByte minimum swap size or you'll have trouble
during the link phase.<p>
<HR>
<h1><A NAME="Problems">Common Problems</h1>
<ul>
<li>Strange compile errors on Unix. Make sure that you specify the
environment variables CXX and CC prior to running CMake.
(If you have already run CMake, do a "make clean" to remove
the cached CMake information.)
<li>Errors on Tcl or Tk include files. Make sure that you edit
CMakeCache.txt to point to the correct location.
<li>Errors on Tcl or Tk libraries. Make sure that you edit
CMakeCache.txt to point to the correct location.
<li>Link errors on Windows platforms. Make sure that the swap space is
at least 300 MByte.
<li>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.
</ul>
<HR>
<h1><A NAME="Data">Getting Data and Test Images</h1>
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 <A href="http://public.kitware.com/dashboard.php">http://public.kitware.com/dashboard.php</A>).
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.
<pre>
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:anonymous@public.kitware.com:/vtk/cvsroot login
(respond with password vtk)
cvs -d :pserver:anonymous@public.kitware.com:/vtk/cvsroot checkout VTKData
</pre>
<HR>
<h1><A NAME="Running">Running VTK</h1>
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.
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 <A href="Wrapping/Tcl/README">Wrapping/Tcl/README</A> 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:
<pre>
vtk mace.tcl
</pre>
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.
<HR>
<h1><A NAME="NewClass">Adding A New Class</h1> There are several ways to
extend VTK. The simplest way is, in your own code, create classes that
inherit from the appropriate VTK classes. This does not provide the benefit
of wrapping the C++ class into Tcl, Java, and Python. If you would like your
class to be wrapped into these languages, you will have to add your class to
the VTK build. This is the recommended procedure.
<pre>
1) Create a new directory called VTK/Local.
2) Create a file called LocalUserOptions.cmake in VTK/. In that file,
add the command "SUBDIRS(Local)". This will add the Local directory
to the build.
3) Create the .cxx and .h file for the new class in VTK/Local. Make
sure that you use VTK conventions to insure that the wrapping
occurs correctly. Complex code may break the wrapper parser;
use //BTX and //ETX around the code to fix this.
4) Create a CMakeLists.txt in VTK/Local. You can model it after
a CMakeList.txt file found in another directory
(like VTK/IO/CMakeLists.txt).
5) Rerun ccmake (Unix) or CMakeSetup.exe (Windows).
6) Then make/gmake (Unix) or msdev (Windows).
</pre>
<HR>
<h1><A NAME="Help">Getting Help / Mailing List</h1>
If you run into problems, your best bet is to join the VTK mailing list.
Visit <a href="http://public.kitware.com/mailman/listinfo/vtkusers">
http://public.kitware.com/mailman/listinfo/vtkusers</a> to join the list.
<p>
Commercial support contracts are available from Kitware at
<a href="http://www.kitware.com/products/vtksupport.html">
http://www.kitware.com/products/vtksupport.html</a>.
<p>
Kitware also provides consulting services. Read more at
<a href="http://www.kitware.com/products/consult.html">
http://www.kitware.com/products/consult.html</a>.
<p>
Training is also available from Kitware. See
<a href="http://www.kitware.com/products/vtktrain.html">
http://www.kitware.com/products/vtktrain.html</a>.
</body>
</HTML>
