# NAME

scriptsort - sort an animation script or scripts

# SYNOPSIS

scriptsort [-fsq] [-bbase] [-oframe_offset] < unsorted.script

# DESCRIPTION

Scriptsort reads an rt animation script from standard input and sorts the frames into the desired order. Typical uses include combining separate scripts into one script, or changing the frame order of an existing script.

Scriptsort organizes the input script into three different categories. The first category consists of numbered frames. Each frame begins with a start frame_num; command, and ends with an end; command. All of the text between those two commands makes up the body of the frame. When two frames with the same frame number are found in the input, they are merged into a single frame. The body of the merged frame is the concatenation of the two original frames, except that only one clean; command is ever printed in a single frame.

The second category consists of shell commands. Any line in the animation script which is not inside a frame and which begins with an exclamation mark is considered to be a shell command. Typically, each frame of an animation script might have an associated shell command following it to process the image just computed. The third category is "everything else". These are assumed to be global animation commands that don't belong to any frame and should be executed before the first frame.

Once the input has been sorted by category, output is produced according to the following method. First, all of the global animation commands that didn't belong to any frame are printed. Next, scriptsort determines the order in which to print the frames. This might be in ascending numerical order, or in a scrambled order which incrementally increases the time resolution of the script, depending on the -b option. Then scriptsort prints the frames in order. After each frame, the shell command

    !end_of_frame.sh frame_num

is added if any of the input frames which contributed to the frame had an associated shell command. When the animation script is run as input to rt, the user should create a shell script called "end_of_frame.sh" to perform any desired shell commands. The argument to "end_of_frame.sh" is the frame number.

The order in which the frames are printed out depends on an integer called the base integer, which must always be a power of two. By default, the base integer is one, in which case the frames are listed in order of increasing frame number. Larger powers of two cause the frames to be ordered in such a way that the time resolution of the animation script is incrementally increased. For example, an animation script sorted with a base integer of four calculates every fourth frame on the first pass, all of the remaining even frames on the second pass, and all of the odd frames on the final pass.

The following algorithm defines the order corresponding to a given base integer:

1. List all of the frames in order of increasing frame
  number. Then give each frame an index according to its position in the list. For example, if there are 61 frames numbered from 45 to 105, then the index of frame 45 is 0, and the index of frame 105 is 60.
2. Print all of the frames whose indexes are multiples of the base
  integer, beginning with the frame indexed by zero.
3. If the base integer is one, stop here. Otherwise, go to step 4.
4. Divide the base integer in half and print all of the frames whose
  indexes are odd multiples of the new base integer. Go to step 3.

The base integer can be set to any power of two with the -b# option. To automatically select the largest possible base integer for a given script, a non-positive argument should be used. If the specified integer is positive but is not a power of two, then a warning is printed and the integer is set to one, the default value.

# OTHER OPTIONS

-f
  forces a shell command to be printed after every frame, regardless of whether or not shell commands were found in the input script.
-s
  suppresses shell commands. No shell commands are printed, regardless of whether or not shell commands were found in the input script.
-q
  enables quiet mode. The status messages normally printed on standard error are suppressed.
-o
  frame_offset specifies an integer which should be added to all of the frame numbers. For example, suppose that the user wants to concatenate two animation scripts which begin at frame zero and are 300 frames long. He or she should run one script through scriptsort with an offset of 300 before doing the concatenation.

# AUTHORS

Christopher T. Johnson

Carl J. Nuzman

# COPYRIGHT

This software is Copyright (C) 1994 Geometric Solutions, Inc. Contributed to the US Army for unlimited distribution.