			 StageTools Release 1
			     August 1997


CUSTOMIZATION:

The StageTools suite has been designed so that it is possible to
customize many of its features.  There are three main methods:
1) setting X resources in a user's .Xdefaults file; 2) setting up an
initialization file in a user's home directory; 3) modifying the TCL
code in the StageTools directory.

The first method is useful for the user who wants to individualize the
appearance (fonts, sizes, widget geometry, etc) of the StageTools
modules.  There is a wide range of X resources set up specifically for
such purposes (see the X RESOURCES section below).  There are also
resources that can be used to specify the user's preferred image
viewer, web browser, etc.  Using X resources is the easiest way to
customize the StageTools.

The second method allows more advanced users to make more extensive
changes to the StageTools modules.  Each module reads an
initialization file from the user's home directory when it starts up.
For example, StageManager looks for ~/.StageManager and executes it if
it exists.  These initialization files are TCL files that can do
pretty much anything you want:  they can set the default values for
menu choices, change the appearance of windows, even replace internal
commands with customized versions.   See the section on USER
CUSTOMIZATION for more.

Finally, the third method makes it possible to perform system-wide
customization.  This will not usually be necessary, except perhaps to
set the default fonts, sizes, etc.  The other reason to make such
changes is to specify the unix commands that will be used to convert
image formats and to combine images into MPEG movies and animated GIF
files.  See CUSTOMIZING THE EXTERNAL COMMANDS below for more
information.


X RESOURCES:

[needs to be written]


USER CUSTOMIZATION:

[needs to be written]


CUSTOMIZING THE EXTERNAL COMMANDS:

The StageTools suite uses by default the ImageMajick package for image
conversions, mpeg_encode for making MPEG movies, and gifmerge for
creating animated GIFs.  Your site may not have all of these
installed, so you may need to change what commands are used for these
functions.

You can customize these commands by editing the StageTools/lib/commands.tcl
file; all the modules look here to find out what commands to use for
these functions.  The routines in this file each return a string that
is the command to perform for that function.  For example, the command
_viewer(Image) should accept an optional file name and return a string
that contains the command to perform in order to view the file.  The
other procedures in the file work the same way.  Several of these
commands look up X resources to find the command to use, so this
provides an easy way for users to customize the commands they want to
use.  The defaults are set in the "option" commands at the top of the
commands.tcl file.

You may want to edit either the option commands or the procedure
definitions themselves.  For example, the ImageMajick package no
longer produces compressed GIF files (in an attempt to avoid patent
troubles), so the GIF files it produces are much larger than they need
to be; you may want to substitute some other command for producing GIF
files.  Here is one possible solution:

    proc _cmd(Convert) {old new type w h colors dither} {
      global _image
      set options "-geometry ${w}x${h} +comment"
      if {$colors != ""} {
	if {$dither} {append options " -dither"} \
                else {append options " +dither"}
	append options " -colors $colors"
      }
      switch $type {
        jpg {append options " -quality $_image(quality)"}
        gif {return "convert $options $old PNM:- | pnm2gif > $new"}
      }
      return "convert $options $old $type:$new" 
    }

Here, a "switch" statement has been added that uses an alternate
command when .gif files are needed:  convert is used first (to get the
colors and size correct) but it produces a PNM image, which is passed
to "pnm2gif" for conversion to .gif format.  If you do not have the
"convert" program (part of ImageMajick), then you may need to use
separate programs for the sizing and color reduction steps; you can
string them into a single command using pipes or the "... && ..."
format.

The _cmd(Convert) procedure is used in two distinct ways:  1) to
convert ppm files to other formats, and 2) to resize an existing
image.  If you do not have a program like "convert" that can read any
input format and produce any output format, you may need to have a
more complicated switch statement that takes into account both the
input and the output formats.  Usually you can tell the format from
the file extension, but this is not always the case.  You can make the
following assumptions:  the "type" variable always gives the type of
the output file, and if the old name is not the same as the new name,
then the file extension of the old name gives its type (if you don't
recognize the type, assume it is PPM).

If you modify _cmd(Convert) to work with packages other than
ImageMajick, please consider sending us a copy of your code so that we
can share it with others who may also want to use the same package.
Send your modifications to <mailto:software@geom.umn.edu>.

[More examples are needed here]


If you plan to change the MPEG encoder, you will also need to edit the
StageTools/module/BackStage/mpeg.tcl file, as this file includes the
procedures that write the .param file that is passed to mpeg_encode.
Since this command file is specific to mpeg_encode, if you want to
substitute some other MPEG encoder, you will most likely need to
modify the .param file format.  There are procedures in mpeg.tcl that
are called to write the data at the beginning of the file, the data at
the end of the file, and the data for individual frames of the file.
If you modify mpeg.tcl to work with some other MPEG encoder, please
consider sending us a copy of your code so that we can share it with
others who may also want to use the same encoder.  Send your
modifications to <mailto:software@geom.umn.edu>.
