  The Linux Visualization Toolkit HOWTO
  Chris Slack, Christopher.Slack@med.ge.com
  v1.00, 12 November 1998

  This document describes how to install, build, and run the Visualization
  Toolkit (VTK) under Linux.  The intent is to solve some of the problems 
  users have experienced in the past and make running VTK under Linux an easy 
  and straightforward process.

  Table of Contents
  -----------------

  1. Introduction
    1.1  Acknowledgments
    1.2  Revision History
    1.3  New Versions of This Document
    1.4  Feedback
    1.5  Subscribing to the VTK Users List
    1.6  Distribution Policy
  2. Linux Preparation
    2.1  Installing Linux
    2.2  Installing Mesa
    2.3  Installing Tcl/Tk
  3. VTK
    3.1  Getting VTK
    3.2  Installing VTK
    3.3  User.make
    3.4  Configuring and Compiling VTK
    3.5  Final Steps
  4. Other Sources of Information
    4.1  Books
    4.2  Web Resources
    4.3  Real People
  5. Regression Test Configuration


  1.  Introduction

  This is the Linux VTK HOWTO.  It is intended to be a quick reference
  covering everything you need to know to install and configure the VTK
  libraries and executable under Linux.  Frequently asked questions about VTK
  under Linux are answered, and references are given to other sources of
  information on VTK.

  The scope of this document is limited to discussing what needs to be done
  in order to get VTK properly installed and running on a system running
  RedHat Linux 5.1.  Although many parts of this document may apply to other
  distributions of Linux the procedures which follow have only been tested
  using RedHat 5.1.

  1.1.  Acknowledgments

  Much of the information contained in this document came from the README
  file included in the VTK 2.1 distribution as well as from help by the VTK
  authors and the multitude of users on the vtkusers mailing list.

  1.2.  Revision History

     Version 1.0
  	Document created

  1.3.  New versions of this document

  New versions of this document will be posted periodically to the vtkusers
  mailing list (information on subscribing to this list can be found later in
  this document).  As this document changes it will also be updated in the
  VTK nightly distribution available at:

    ftp://vtk.scorec.rpi.edu/pub/vtk_nightly/

  1.4.  Feedback

  If you discover any problems or errors in this document, please feel free
  to contact me at the email address listed above.  We do our best to make
  VTK as high a quality piece of software that we can, and the documentation
  is no exception.  If you intend to become a serious user of VTK you may
  also want to consider subscribing to the VTK mailing list.

  1.5.  Subscribing to the VTK Users List

  The VTK users list is read and posted to by hundreds of VTK users and
  developers, including the authors, on a regular basis.  Any VTK user is
  welcome to subscribe to the list, and can do so by following the following
  instructions:

  TO SUBSCRIBE

  Email the following text:

      subscribe vtkusers

  in the body of a message to majordomo@gsao.med.ge.com (don't place it in
  the Subject: field!)

  TO UNSUBSCRIBE

  Email the following text 

      unsubscribe vtkusers

  in the body of a message to majordomo@gsao.med.ge.com (don't place it in
  the Subject: field!)

  TO SEND EMAIL TO THE LIST

  Send your email to the following address: 

      vtkusers@gsao.med.ge.com

  You must subscribe and unsubscribe from the same email address. If you
  subscribed to the list as joe@machine1.foo.com you must unsubscribe from 
  the same address. We hope to hear from you soon! 

  1.6.  Distribution Policy

  Copyright (c) 1993-1998 Ken Martin, Will Schroeder, Bill Lorensen.

  This software is copyrighted by Ken Martin, Will Schroeder and Bill
  Lorensen.
  The following terms apply to all files associated with the software unless
  explicitly disclaimed in individual files. This copyright specifically does
  not apply to the related textbook "The Visualization Toolkit" ISBN
  013199837-4 published by Prentice Hall which is covered by its own
  copyright.

  The authors hereby grant permission to use, copy, and distribute this
  software and its documentation for any purpose, provided that existing
  copyright notices are retained in all copies and that this notice is
  included verbatim in any distributions. Additionally, the authors grant 
  permission to modify this software and its documentation for any purpose, 
  provided that such modifications are not distributed without the explicit 
  consent of the authors and that existing copyright notices are retained in 
  all copies.  Some of the algorithms implemented by this software are patented,
  observe all applicable patent law.

  IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
  DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
  OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
  EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
  BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN
  "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
  MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.


  2.  Linux Preparation

  In order to properly install and run VTK under Linux one must first
  install Linux and the necessary additional packages correctly.  This
  section will guide the user through this fairly simple process. 

  This section is not meant to tell the user how to install Linux, rather
  it is assumed that they understand (or have another document which
  explains) how to install RedHat Linux 5.1 themselves.  What this section
  does intend to do is provide the user with the information needed to
  configure Linux with the options necessary to properly compile and run VTK. 

  2.1.  Installing Linux

  When installing Linux be sure to select all of the development options,
  including all compilers and libraries.  Once Linux has been installed the
  user will need to check to see that the X-windows system is functioning
  properly.  X should be run in 32-bit per pixel mode if possible, some of
  the lower depth X servers can cause problems in a few sections of VTK.  To
  ensure that you are starting X in 32bpp mode use the following command:

  startx -- -bpp 32

  If all goes properly you should get a graphical windows screen with a
  window and prompt in the center.  There are many ways to customize
  X-windows from various color schemes to whole new window managers.  If you
  are interested in such customizations look through the Linux documentation
  and the web to find endless numbers of possible configurations.  However,
  it is the advice of this author to install and test VTK before making any
  of these customizations if you have not already done so.  VTK should not
  have problems with most changes, but the nightly tests are run on a fairly
  plain Linux installation and thus the less that is different the less
  chance you are to have a major problem.

  2.2  Installing Mesa

  In order to compile and run VTK you will need a package called Mesa.
  Mesa is a package which provides OpenGL support for Linux.  The version of
  Mesa our testing has been done with is Mesa-3.0-2, and thus we suggest
  getting this version or higher.  You can download Mesa from a number of
  sites on the Internet, below is the site we found Mesa at, and seems to be
  a quite reliable site for RPMs:
  
    http://ftp.tuwien.ac.at/opsys/linux/RPM/Mesa.html

  Get the file Mesa-3.0-2.i386.

  You will also need the Mesa development option:

    http://ftp.tuwien.ac.at/opsys/linux/RPM/Mesa-devel.html

  Get the file Mesa-devel-3.0-2.i386.

  If there are only later versions of these file available they should work
  fine, but make sure that the binary and development packages are the same
  version or there could be conflicts between the shared libraries and the
  header files.

  Once you have both Mesa files follow the following instructions:

    1. Become root

    2. Issue the command: "rpm -i Mesa-3.0-2.i386.rpm"

    3. Issue the command: "rpm -i Mesa-devel-3.0-2.i386.rpm"

  That's it, Mesa is installed.  If you want to find out more about Mesa look
  in the /usr/doc/Mesa-3.0 directory, it will have been created after
  installing these packages.

  2.3  Installing Tcl/Tk

  If you are planning on running VTK with the Tcl/Tk options then you will
  need to have Tcl/Tk installed.  If you have installed the development
  options as described above then you should already have the Tcl/Tk
  libraries installed.  However, in order to build VTK you will also need the
  header files which were needed to build the Tcl/Tk libraries which are not
  installed as part of the Linux development options.

  Installing the Tcl/Tk headers which are necessary to build VTK is an easy
  and painless process.  One important thing to note is that the Tcl/Tk header
  files/source you install MUST be the same version of Tcl/Tk as the binary
  libraries which have already been installed.  With the RedHat 5.1
  distribution this is not an issue since all of the source packages which
  come on the CD's correspond to the binaries which are installed.  

  To install the Tcl/Tk source/header files follow the following
  instructions:

    1. Become root

    2. Insert RedHat 5.1 CD #2

    3. Issue the command: "rpm -i /mnt/cdrom/SRPMS/tcltk-8.0.2-16.src.rpm"

    4. Issue the command: "cd /usr/src/redhat/SOURCES"

    5. Untar the tcl8.0p2.tar.gz and tk8.0p2.tar.gz files 

  That's it, the Tcl and Tk sources along with the header files have been
  installed in the /usr/src/redhat/SOURCES/tcl8.0 and .../tk8.0 directories.
  You can leave these source trees where they are, or move them to another
  location if you desire, but you will have to modify the user.make file
  which is discussed later in this document.

  
  3.  VTK

  There are a number of options which can be specified when installing and
  configuring VTK, the following section describes just a few.  More detailed
  information about VTK configuration options can be found in the README file
  contained in the VTK root directory.

  3.1  Getting VTK

  There are a few different ways to obtain VTK.  One way is to purchase one
  of the VTK books mentioned later in this document, both contain the VTK
  source on CD.  Another way is to download VTK from the Internet.  There are
  generally two versions of VTK available at the official VTK distribution
  site.  One version is the official release version (currently 2.1).  The
  official release has been extensively tested with pieces hand-picked from
  various nightly releases to provide a stable, reliable release of VTK.  The
  advantages of the official releases are obvious, but the disadvantage is
  that the official releases don't change very often so any new features may
  not be picked up for several months.  If you are the type who wants the
  latest and greatest versions of everything you can obtain nightly releases
  of VTK.  These releases reflect all of the changes made to VTK up to hours
  before you may download it.  This includes new features, architecture
  changes, and bug fixes.  However, it also includes bugs, errors, and
  problems so be forewarned if you do decide to use a nightly release to
  build VTK.  One way to determine how good a nightly release may be is to
  look at the VTK Quality Dashboard.  This web page lists the results of the
  325 regression tests run every night on 5 different platforms.  Through
  this page you can see exactly what passed, what failed, why it failed, and
  which files have changed since the previous night, or the last month.  By
  using this page and some common sense you should be able to pick nightly
  releases with a strong degree of confidence that you will have a working
  system after you compile.

  Official VTK Releases
  ---------------------
    ftp://ftp.kitware.com/kitware/

  VTK Nightly Releases
  --------------------
    ftp://www.kitware.com/vtkData/Nightly.html

  VTK Quality Dashboard
  ---------------------
    http://vtk.scorec.rpi.edu/Nightly/MostRecentResults/

  3.2.  Installing VTK

  Installing VTK is a very short and simple process.  The tar file which
  contains the VTK source will expand into the necessary VTK directory
  structure.  Just follow the following instructions:

    1. Copy the vtk tar file to the top level directory you wish to have VTK
       installed under (generally either your home directory, or someplace 
       such as /usr/src or /usr/local/src). (NOTE: You do not have to be root
       to install or build VTK, if you have permissions to write to the
       directory you are installing into).

    2. Issue the command: "gunzip <VTK tar.gz FILENAME>"

    3. Issue the command: "tar xvf <VTK tar FILENAME>"

  That's it, the VTK source is now installed.

  3.3  User.make

  Once you are finished install the VTK source tree you will find a
  directory under the top level directory you chose called vtk.  In this
  directory will be a number of files and directories.  One such file in this
  directory is the user.make file.  This file allows the user to specify a
  number of things, the most important of which being the directories to look
  for certain header files and libraries.

  In the user.make file you will see a series of lines similar to the
  following:

    TCL_INCLUDE=-I/home/ausable/software/src/tcl7.6/tcl7.6/generic
    TCL_LIB=/common/software/tcl7.6/sun4/5.4/lib/libtcl7.6.a
 
    TK_INCLUDE=-I/home/ausable/software/src/tcl7.6/tk4.2/generic
    TK_LIB=/common/software/tk4.2/sun4/5.4/lib/libtk4.2.a
 
    MESA_INCLUDE=-I/home/martink/storage/Mesa-1.2.6/include
    MESA_LIB=/home/martink/storage/Mesa-1.2.6/lib-sun4-solaris/libMesaGL.a
 
  These lines MUST be changed to reflect the locations of the various
  packages you have already installed.  If you have followed the instructions
  above when installing the three packages reflected here (Tcl, Tk, and Mesa)
  and are running RedHat Linux 5.1 these lines should be changed to read as
  follows:

    TCL_INCLUDE=-I/usr/src/redhat/SOURCES/tcl8.0/generic
    TCL_LIB=/usr/lib/libtcl8.0.so
 
    TK_INCLUDE=-I/usr/src/redhat/SOURCES/tk8.0/generic
    TK_LIB=/usr/lib/libtk8.0.so
 
    MESA_INCLUDE=-I/usr/include/GL
    MESA_LIB=/usr/lib/libMesaGL.so

  If you chose to install these libraries and source trees in other places
  simply replace the directories and files above with the appropriate other 
  directories and files. 

  There is a problem with the version of the egcs compiler included with
  RedHat 5.1 which can cause segmentation faults when running certain aspects
  of VTK.  There are two solutions to this problem.  The first, and simplest,
  involves adding a compiler flag to the user.make file as follows:

  1. Edit user.make
  
  2. Find the commented out lines containing USER_CFLAGS and USER_CXXFLAGS

  3. Uncomment out those lines and add -D__NO_MATH_INLINES to the lines,
     an example is as follows:

       USER_CFLAGS = -O2 -D__NO_MATH_INLINES
       USER_CXXFLAGS = -O2 -D__NO_MATH_INLINES

     this will cause the compiler to use optimization level 2 and use no
     inline math, this will eliminate the core dumping problem.  The 
     alternative is to go out to the web and find the latest egcs compiler 
     (version 1.1 or later).  So far I have not been able to find an RPM 
     version of egcs 1.1, so this will involve getting the compiler, and 
     compiling, linking, and installing it.  Setting the flags is certainly 
     easier, and we have tested versions of VTK built in this manner and have 
     found no problems.

  3.4 Configuring and Compiling 1VTK

  As mentioned before there are a number of options when configuring VTK, the
  following are some of the more common ones.  

  In order to compile VTK you will first need to run the configure script
  found in the VTK root directory.  There are a few common options, some
  required, which you will want to consider including when you run this
  script.

    --with-mesa        Tells VTK to use Mesa for OpenGL. [REQUIRED FOR LINUX]

    --with-tcl         Tells VTK to compile with Tcl/Tk bindings. [Suggested]

    --with-shared      Tells VTK to use shared libraries. [Suggested]

    --with-tkwidget    Tells VTK to compile with tkwidget which allows VTK to
                       render into a window not created by VTK.

    --with-contrib     Tells VTK to compile with the contrib directory, this
                       contains classes contributed by a variety of VTK users.

    --with-patented    Tells VTK to compile with the patented directory, this
                       directory contains classes which are patented by The 
                       General Electric Company (GE), all appropriate patent 
                       law must be observed.

    --with-python      Tells VTK to compile with Python bindings. [UNTESTED]

    --with-java        Tells VTK to compile with Java bindings. [UNTESTED]

  Now run the configure script with the options you desire from the VTK root
  directory, here is an example:

    ./configure --with-mesa --with-tcl --with-shared --with-contrib

  Which will allow you to run VTK using Mesa, create a vtk executable to run
  Tcl/Tk scripts, using shared libraries, and contain any additional classes
  in ./contrib.  This script should run through successfully assuming you
  have followed the instructions above, and now you are ready to compile VTK.

  Here is the simplest step of this whole process, to compile VTK follow the
  following instructions:

    1. From the VTK root dir, Issue the Command "gmake"

    2. Wait awhile

  VTK should begin compiling, compile time will vary depending on the machine
  you use, on my PII-300 with 128M RAM it takes about 1.5 hours, on a P90
  about 5 hours, on a quad-processor Onyx2 with high speed RAID disks about
  15 minutes. 

  3.5  Final Steps

  Now that you have compiled VTK you're almost set to run.  There are now a
  a few choices you will have to make.  Assuming you build with shared
  libraries you will need to let the system know where to find them.
  Currently they are sitting in the 3-5 directories in which their source
  code lies, which is fairly inconvenient.  The suggestion of this author is
  to create a library directory somewhere to store the VTK shared libraries.
  The location of this directory will be left up to the user, for my
  examples I will use <YOUR VTK LIB DIR>.  Follow the following instructions
  to consolidate your *.so files in one location:

    1. Issue the command: "mkdir <YOUR VTK LIB DIR>"
  
    2. Issue the command: "cd <YOUR VTK LIB DIR>"
  
    3. Issue the command: "ln -s <YOUR VTK ROOT DIR>/*/*.so ."

  Now you have symbolic links to the shared libraries in your lib directory.
  By using these links you will only have to tell the system about one
  directory and whenever you recompile your libraries the changes will
  automatically be seen by the system.

  Now you will need to add a line to your .cshrc file:

    1. Change to your home directory

    2. Edit the file ".cshrc" with your favorite editor

    3. Add the following line:
       setenv LD_LIBRARY_PATH <YOUR VTK LIB DIR>

  If you already have an entry for LD_LIBRARY_PATH you will need to append
  your lib directory pathname to the end of that entry instead.  Also if you
  are not using csh, tcsh or another derivative you may need to use a
  different format for defining a variable.

  If you have built with tcl then you will need to make the executable
  created by VTK available to run.  The executable will be located in the
  directory "<YOUR VTK ROOT DIR>/tcl" and the file is called "vtk".  You have
  many choices here, you can always specify the full path to the
  executable, you can create an alias to point to the file, you can create a
  link to this file from a directory already in your path (i.e. -
  /usr/local/bin), or you can add the .../tcl directory to your path.  My
  suggestion would be either aliasing or creating a link to the file in
  /usr/local/bin.  This step will be left up to the user to decide.

  You're now ready to run VTK.  Start simple, there are a number of
  examples included with VTK.  A very simple example (and useful to see if
  everything is working) can be found in the directory "<YOUR VTK ROOT
  DIR>/graphics/examplesTcl" called Cone.tcl.  To run just execute the
  following command:

    ../../tcl/vtk Cone.tcl

  If you have already aliased or linked the vtk executable then the path is
  not necessary.  There are many other Tcl examples (thus we strongly suggest
  building with Tcl/Tk) included in the graphics, imaging, contrib, and
  patented directories all under the subdirs examplesTcl or examplesCxx, all
  of the source is there so run them, look at them, modify them, they are a
  great way to learn just what kinds of things VTK can do.


  4.  Other Sources of Information

  As with most documents this one is by no means a complete description of
  VTK, so included in this section are a variety of resources that you can
  use to learn more about VTK, it's installation, and it's features.

  4.1  Books

  There are two books published on VTK as follows:

    "The Visualization Toolkit, An Object-Oriented Approach to 3D Graphics"
    by Will Schroeder, Ken Martin and Bill Lorensen.
    Prentice Hall, Second Edition (ISBN 013199837-4)

    "The VTK User's Guide"
    by Will Schroeder and Ken Martin.
    Published by Kitware

  "The Visualization Toolkit" can be ordered through Amazon.com and is also
  available through local bookstores.

  "The VTK User's Guide" is available through the Kitware web site as
  listed below.

  4.2  Web Resources

  There are several web sites devoted to VTK, the following are a few of the 
  ones that exist at the time of the writing of this document:

  Kitware, Inc.
  -------------
    http://www.kitware.com/vtk.html

  This is the official homepage of VTK and is the place to find current
  releases, and the latest information about VTK as well as information about
  commercial support available for VTK.

  VTK Users List Archive
  -----------------------
    http://vr.ncsa.uiuc.edu/vtkuser/
  
  NCSA Archive of the VTK users list.

  Robert Riviere's VTK Object Browser 
  -----------------------------------
    http://www.inria/caiman/personnel/Robert.Riviere/vtk/reflect.html

  Convenient way of sorting through VTK objects.

  VTK 2.0 Man Pages
  -----------------
    http://bulky.aecom.yu.edu/vtk

  Online searchable help for VTK.

  VTK Data Files
  --------------
    http://www.acns.com/pub/vtk

  All of the data files necessary to run all of the examples included with
  VTK.

  There are many more web pages out there, these are just a few, the
  Kitware page has links to these and most of the other VTK related web sites
  out there.

  4.3  Real People

  The best way to get help on VTK from real people is to subscribe to the
  VTK users list.  Instructions for subscribing are listed above.  The users
  list is quite active, and a great way to get answers to just about any
  question you can think of about VTK.  The authors and developers of VTK
  check the list daily as well as a multitude of other users. Much of the
  content of this document was gather from information in the archives of the
  VTK users list.

  5.  Regression Test Configuration

  Each night we run approximately 325 regression tests on numerous platforms.
  One such platform is a RedHat Linux machine.  The system started from a
  base install of RedHat Linux 5.1, if a new package is not listed then it
  has not been installed.

    RedHat Linux 5.1 (from CD)
    Mesa 3.0-2
    Tcl/Tk 8.0.3
    egcs 1.1b

  From other testing we do it appears that the version of Tcl/Tk included
  with RedHat will work fine (8.0.2), and the standard version of egcs will
  function properly if used with the options specified in the above document.
