StageTools - Documentation (Customize)

Customizing the External Commands:

The StageTools suite uses by default the ImageMagick 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 the commands that are used for these functions.

We have already seen one way to modify these commands in the section on X resources. Sometimes, more extensive modification are needed, however. Another way to customize these commands is 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 ImageMagick 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} {
      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 ImageMagick), 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 ImageMagick, 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 dpvc@union.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 dpvc@union.edu.

Similarly, if you want change the animated GIF encoder, you will need to modify the file StageTools/module/BackStage/animGIF.tcl. The types of changes you will need to make are comparable to the ones for the MPEG encoder discussed above. Again, if you do this, please share your modifications by sending them to dpvc@union.edu.

StageTools Documentation web pages Created: 20 Aug 1997 Last modified: 17 Aug 2006 09:40:35 Comments to: dpvc@union.edu

Getting Started with StageTools Customization Instructions Customization using config files