VTK Tcl wrappers
===========================================================================

  I) Invoking the VTK package(s)
 II) Invoking additional packages
III) Installing the packages



=============================
  I) Invoking the VTK Tcl package(s)

Load the whole VTK API by issuing the following line before any invocation of a VTK command (typically at the top of your Tcl script):

        package require vtk

This will load all VTK components and the corresponding commands. Depending on how VTK was built, some components might not be available (since Hybrid, Parallel, Patented and Rendering can be excluded).

VTK may also be used on a component-by-component basis by requiring the component explicitly. Example:

        package require vtkrendering

The above line will resolve the dependencies and invoke (in that case) the vtkgraphics and vtkimaging packages automatically (which will trigger the vtkfiltering and vtkcommon packages too). This method can be used to speed-up startup-time since only the required commands will be loaded.



=============================
 II) Invoking additional packages


A) vtkinteraction
**************

The vtkinteraction package can be loaded to provide additional interaction support. 

        package require vtkinteraction

i) Tcl interactor: 

The vtkinteraction package creates a generic Tcl interactor inside a console widget, allowing you to issue any Tcl commands while running the script. Once the package is loaded, a hidden .vtkInteract widget is created. Bind a key or set the user method of your vtkRenderWindowInteractor to deiconify that widget:

        vtkRenderWindowInteractor iren
            [...]
            iren SetUserMethod {wm deiconify .vtkInteract}

Example: see Examples/GUI/Tcl/Mace.Tcl.


ii) 'vtkTkRenderWidget bindings':

The vtkinteraction package also brings a set of user-interaction bindings for the vtkTkRenderWidget class. It allows you to use this Tk widget in a way similar to the usual VTK interactor. Once the package is loaded, call ::vtk::bind_tk_render_widget to associate the bindings to the render widget:

        set ren [vtkTkRenderWidget .ren -width 300 -height 300 -rw renWin]
        ::vtk::bind_tk_render_widget $ren

Example: see Examples/GUI/Tcl/MaceTk.Tcl.


B) vtktesting
*************

Some developpers might load the vtktesting package to include additional facilities.

        package require vtktesting

Once loaded, the package provides the functions usually located in the following files:

        backdrop.tcl
        colors.tcl
        mccases.tcl



=============================
 IV) Installing the package index file

A good description of the package and library facilities is given in the Chapter 12 "Script, Libraries and Packages" (page 135) of "Practical Programming in Tcl & Tk", Brent B. Welch, ISBN 0-13-616830-2.

When a package is "required" by the 'package' command (see part I to III), the Tcl interpreter looks through a set of directories and their subdirectories for pkgIndex.tcl files. It sources those to build an internal database of packages (and version information).

pkgIndex.tcl files have been included in this VTK distribution to provide the packages described in the previous sections to the interpreter. They will load the corresponding DLLs, set some default behaviours/bindings/widgets and exit with an error message if the package could not be provided (DLL not found, for example).

The package facility assume that Tcl libraries (and packages) are kept in well-known directories (and their subdirectories). The list of well-known directories is kept in the auto_path Tcl variable. It is initialized by tclsh or wish to provide default directories, including the default Tcl script library directory. For example :

Windows:
--------

% puts $auto_path
C:/devel/langages/tcl/8.3/lib/tcl8.3 C:/devel/langages/tcl/8.3/lib C:/devel/langages/tcl/8.3/lib/tk8.3

Linux/Unix:
--------

root [1003] ~/tmp# wish
% puts $auto_path
/usr/lib/tcl8.3 /usr/lib /usr/lib/tk8.3

Now let's see how we can make Tcl aware of the VTK Tcl packages. Tcl provides a way for you to tell the Tcl interpreter to search for pkgIndex.tcl files in any user-specified directory (and its subdirectories). Just set the TCLLIBPATH environment variable to a set of space-separated directories to search in (warning: Windows users shall use '/' instead of '\'). 

If you store the VTK sources on your hard disk or if you use the CVS, add Wrapping/Tcl to TCLLIBPATH. For example:

Windows:
--------

TCLLIBPATH=S:/src/vtk/vtknew/Wrapping/Tcl

Now check auto_path :

% puts $auto_path
S:/src/vtk/vtknew/Wrapping/Tcl C:/devel/langages/tcl/8.3/lib/tcl8.3 C:/devel/langages/tcl/8.3/lib C:/devel/langages/tcl/8.3/lib/tk8.3

Linux/Unix:
--------

root [1011] ~/tmp# export TCLLIBPATH=/home/barre/vtk/Wrapping/Tcl
root [1012] ~/tmp# wish
% puts $auto_path
/home/barre/vtk/Wrapping/Tcl /usr/lib/tcl8.3 /usr/lib /usr/lib/tk8.3


This shall do the trick :))
Sebastien BARRE (sebastien.barre@kitware.com) 
