Printable Version NEXT

Tcl Packages

Packages Introduction

Tcl packages provide a way to extend the capabilities of the SLIDE viewer. Packages also provide a way to share SLIDE content. Tcl packages are bundles of Tcl code which can be loaded using the package require command. The package require command provides a better mechanism for including Tcl libraries than the source and load commands.

The source command will always read and execute a given file. This may be wasteful in a SLIDE description file. There may be a Tcl library file called "foo.tcl" which is needed by multiple files, so which file should source "foo.tcl". Only the first file needs to source "foo.tcl", but it is sometimes hard to predict which file will be read first. Another alternative might be to source "foo.tcl" in every file. For many cases this is safe but slow. The Tcl interpreter has to reread the file and create the procedures every time source is invoked on it. This may not be a safe operation if "foo.tcl" is doing any one time initialization operations.

Fortunately, the Tcl package require mechanism solves these problems. Tcl functionality can be broken up into useful packages, this can be Tcl code or dynamically loaded compiled shared objects. The package require command tells Tcl to load a package if it is not already loaded. This prevents the user from trying to load a shared object twice which may have unpredictable results. Packages should define a dependency graph, i.e. a package should have a package require statement for all of the other packages which it depends on. With the dependency graph set up, the user should only need to require the packages which he is directly calling apon and all the other necessary functionality will be automatically loaded as well.

Tcl must know where to search for packages when it executes a package require statement. The environment variable SLIDE_LIBRARY must be set to a list of directories which contain SLIDE packages. The typical settings are the following.


setenv SLIDE_LIBRARY /project/cs/sequin/caffe/slide/lib


System Settings: SLIDE_LIBRARY = S:/slide/lib

There are number of Tcl packages which are provided with SLIDE. These are described in more detail in the following sections. This is also an ideal way of adding content to SLIDE and sharing it with other users.


slideui includes many standard utilities. It provides Tcl procedures which build GUI's for the different SLIDE primitives in the file "slideui.tcl. It also provides Tcl procedures for creating some basic polyhedrons in the file "geometry.tcl".


The file "slideui.tcl" provides two main types of procedures which are of the form CreateSLIDE*Object and CreateSLIDE*UI where * can be replaced by any of the standard SLIDE primitive names.

proc CreateSLIDE*Object { name }

This creates a global Tcl associative array called $name and initializes its the fields. In most cases, there is a one-to-one correspondence between the fields of the SLIDE primitives and the fields of this associative array object.

proc CreateSLIDE*UI { parent name }

This creates a Tk frame widget which is filled with GUI widgets to control the different fields of the associative array object. $name is the name of the associative array object which is to be manipulated by the GUI. $parent is the name of the parent widget to the frame which is to be created. The new frame is not packed by this procedure, and instead the frame widget name is returned by the procedure. This makes it possible to build larger control widgets by packing together many of these individual controls.

The following is an example of how to build a user interface for a SLIDE sphere primitive.

tclinit {
  CreateSLIDESphereObject oSphere
  toplevel .slfWindow.uiSphere
  set wFrame [CreateSLIDESphereUI .slfWindow.uiSphere oSphere]
  pack $wFrame

sphere oSphere
  shading { expr $oSphere(shading) }
  solid { expr $oSphere(solid) }

  radius { expr $oSphere(radius) } 
  zmin { expr $oSphere(zmin) } 
  zmax { expr $oSphere(zmax) } 
  thetamax { expr $oSphere(thetamax) } 

  zslices { expr $oSphere(zslices) } 
  thetaslices { expr $oSphere(thetaslices) } 

  texture ( {expr $oSphere(texture_0_0)} 
            {expr $oSphere(texture_0_1)} ) 
          ( {expr $oSphere(texture_2_0)} 
            {expr $oSphere(texture_2_1)} )  


The file "geometry.tcl" provides procedures for generating SLIDE polyhedrons. These procedures use the slide create interface to the SLIDE parser to create SLIDE point, face, object, instance, and group primitives. The generators functions fall into a number of categories.

The first category is functions which generate points, faces, and an object whose name is returned by the function:

proc CreateSLIDERegularPolygon { pcName uiSides }
proc CreateSLIDERegularPyramid { pcName uiSides fHeight}

The second category generates a group which instances the specified geometry in a predefined way. These procedures return the name of the newly created group. Currently all of these procedures assume that the instanced geometry is topologically equivalent to a regular polygon in the XY-plane with edge length one and with its first vertex on the X-axis.

proc CreateSLIDEEquilateralPyramid { pcName pcInstTriangle uiSides }
proc CreateSLIDETetrahedronSymmetry { pcName pcInstTriangle }
proc CreateSLIDECubeSymmetry { pcName pcInstSquare }
proc CreateSLIDEOctahedronSymmetry { pcName pcInstTriangle }
proc CreateSLIDECubeOctahedronSymmetry { pcName pcInstTriangle pcInstSquare }
proc CreateSLIDEDodecahedronSymmetry { pcName pcInstPentagon }
proc CreateSLIDEIcosahedronSymmetry { pcName pcInstTriangle }
proc CreateSLIDEDodecahedronIcosahedronSymmetry { pcName pcInstTriangle pcInstPentagon }

The third category uses the other procedures to generate full polyhedrons based on a unique core name. They all return the name of the toplevel group which is created.

proc CreateSLIDETetrahedron { pcName }
proc CreateSLIDECube { pcName }
proc CreateSLIDEOctahedron { pcName }
proc CreateSLIDECubeOctahedron { pcName }
proc CreateSLIDEOctaStar { pcName }
proc CreateSLIDEDodecahedron { pcName }
proc CreateSLIDEDodecaStar { pcName }
proc CreateSLIDEIcosahedron { pcName }
proc CreateSLIDEDodecahedronIcosahedron { pcName }

The last set of procedures generates one of every type of polyhedron. This can be more efficient than creating them one at a time because it is able to share partial geometry amongst all of the polyhedrons. For example every triangle is actually an instance of the same SLIDE face.

proc CreateSLIDEPolyhedrons {}
# returns a list of all of the top level polyhedron groups

# These create a selector group which can choose between all the
# different polyhedrons generated by CreateSLIDEPolyhedrons
proc SLIDEChooser { var field value }
proc CreateSLIDEPolyhedronChooserObject { name }
proc CreateSLIDEPolyhedronChooserUI { parent name lPolyhedrons }
proc CreateSLIDEPolyhedronChooser { pcName name lPolyhedrons }


parselib includes parsers for STL and SIF geometry files. These parsers read these other formats and generate SLIDE geometry which can be incorporated into the scene graph.


The STL parser is implemented in Tcl and it has the following interface:

CreateSTLObject { name fileName }

$name should be a unique name which will appear in the names of all of the primitives. $fileName should be the name of an STL input file. The function returns the name of a SLIDE object that be can instanced in the scene graph or an error if the file is bad.


The SIF parser is implemented in a C++ shared library and it is packaged so that it can be called apon from Tcl. It has the following interface:

CreateSIFObject { name fileName ?include_dir ...? }

$name should be a unique name which will appear in the names of all of the primitives. $fileName should be the name of an SIF input file. The function returns the name of the top level SLIDE group that can be instanced in the scene graph or an error if the file is bad.


curvelib includes C++ classes of parameterized curves. These curves can be used to generate a rigid body transformation which can be used to control the motion of objects, cameras, or lights in a SLIDE scene description.


iklib includes C++ classes which solve the inverse kinematics for different types of robot manipulators. These solutions can be applied to control the animation of articulated models.

[an error occurred while processing this directive]