Alpha_1 User's Manual

Utilities

This document describes the general usage of the Alpha_1 utility programs. The utilities are used in conjunction with the interactive applications in Alpha_1 such as c_shape_edit. These programs usually process data which has been stored in binary files (.a1 files). The System Overview section of the Alpha_1 Introduction provides a high-level description of the organization of the system and the various types of data files.

Most Alpha_1 utility programs have an associated set of options which control various parameters affecting the computations. The values for these options are passed along when the program is executed, so they are set beforehand. All options have default values which represent the most common usage.

Table of Contents

Input and Output

Output from most programs goes to the Unix "standard output" or stdout. This is usually your terminal, and since many output forms are binary data, you will want to redirect stdout to a file. An example might be

 
render cup.a1 >cup.rle
The "greater-than" symbol redirects stdout to the named file, in this case "cup.rle".

The input for most programs also comes from the Unix "standard input," or stdin, which can be redirected to come from a file with the "less-than" symbol. The Alpha_1 utility programs, however, usually redirect stdin for you. So in the example above, the render command is actually redirecting the file "cup.a1" to the standard input of the render program.

Aside from redirecting stdin for you, most of the commands for running Alpha_1 utilities also concatenate a series of files if desired to form one input stream.

Alpha_1 Data Files

Alpha_1 data files are used to store a wide variety of object-oriented data. Objects can be points, lines, B-spline curves, surfaces, graphs, hierarchies, lists, etc. Alpha_1 data files are named with a .a1 file name extension by convension. These files are machine independent, compressed binary files.

A human-readable text form of .a1 files is available for inspection, but data in this form is considered temporary. Almost all the Alpha_1 programs deal exclusively with the binary form. Data should never be stored permanently in text form as the format may change with future releases of the system and the files may become unreadable.

The "Conv/Deconv" Utilities

The conv/deconv utilities are used to convert between the text and binary form of Alpha_1 data files. To explicitly create a binary file, the conv program takes a stream of data (which may be binary, text, or mixed) and converts it to the binary form.

conv files
Output
<binarystream> Convert input text binary stream. The input may contain binary data mixed in with the text data.
files
<filelist> Files to be converted. They may be text or binary.

For example: 

conv file1 file2 file3 ... >file.a1
Output is to standard out (usually the terminal), so it will be necessary to redirect the output to a file as shown above. (Typing a binary file to your screen is generally a bad idea.)

Since the output of most Alpha_1 programs is binary, if the output needs to be examined, the deconv program can be used to turn the object stream back into a text form.

deconv files
Output
<textstream> Convert input binary stream to text stream.
files
<filelist> Binary files to be converted.

General Utility Options

The general UNIX shell syntax for Alpha_1 utility programs is as follows: 
<program> [-pipe]
          [-state state-file]
          [-help]
          [...any a1 defaults...]
          [files ...]
The "pipe" flag is used to specify that the output of one program will be directed into another one. (The flag is necessary since data is generally compressed on output to disk storage; this allows that step to be skipped if the data will flow immediately into another program.) The "state" flag can be used to specify a file of Alpha_1 program options to use. If not given, the file "a1state" on the current directory is used. Any flags which can be given through an Alpha_1 state file can also be specified on the command line. The "help" flag prints information about these options. All of the above flags may be abbreviated by their first character (i.e., -p, -s, and -h).

As an example, consider running a model through the "srf_mash" program and then into "a1ps" to see the subdivision pattern of the surface tessellation: 

srf_mash -pipe -objresolution 0.05 mymodel.a1 | a1ps >mymodel.ps

Program Options

The flags or options which control the actions of most of the Alpha_1 utility programs are set by a mechanism which is called a1defaults. For example, the program for generating a PostScript line drawing of a surface has options which allow the user to specify how closely the isoparametric lines are spaced, how smoothly the lines are drawn, and even whether isoparametric lines are produced at all. There are a large number of these options, and the details will be described as each utility program is described. Here we will confine the discussion to the general mechanisms for setting values which are common to all the utilities.

The user's choices for options are usually recorded in a special file called a state file, rather than typing them on the command line. Only values which differ from the system defaults need to be specified, so these files are typically very small. There are several ways to change a option setting in a state file:

The last option is the most difficult to use, and is not recommended in general. Most people tend to use aset and aunset. There is a companion to aset and aunset called aprint which just displays the options for a particular program. This is handy if you can't quite remember how to spell the name of the option, or what its current setting is.

The aset and aunset programs allow a single option to be set to a new value or restored to an old value. Both arguments are optional.

aset [ statefile ] [ option-name value ]
Output
<textfile> Normally, the given statefile is modified to set the specified value.
statefile
<string> The name of the state file to be modified or created. If this option is omitted (and it usually is), then the file named "a1state" on the current directory will be used.
option-name value
<string> <any> The option to be set is given first, in the form program.option, specifying which option of which program is to be changed. The value must be of an appropriate type for the given option. For boolean flags, the keyword values on and off are used. If no option/value pair is given, the aset program describes the contents of the given state file (or the default state file if none is given).
The aunset program is used to reset a option to the default system value. This is equivalent to deleting the line from the state file.
aunset [ statefile ] option-name
Output
<textfile> Normally, the given statefile is modified to reset the specified value.
statefile
<string> The name of the state file to be modified. If this option is omitted, then the file named "a1state" on the current directory will be used.
option-name
<string> The option to be reset, in the form program.option, specifying which option of which program is to be changed.
aprint [ statefile ] program
Output
<Nil> The current settings of all options (including ones that have not been changed from the defaults) for the specified program are printed to the screen.
statefile
<string> The name of the state file to search for settings. If this option is omitted, then the file named "a1state" on the current directory will be used.
program
<string> The name of the program for which settings are to be listed.
So a sample invocation of the PostScript generation program mentioned above (a1ps) might be: 
aset a1ps.crvfineness 25.0
aset a1ps.isolines off
aset a1ps.meshes on
a1ps mydata.a1 >mydata.ps
Normally, the state file which has been created must be passed to the program when it is invoked. Programs will search for the default file named "a1state" if no other file is specified on the command line.

"Defed" Program

An alternative method for setting up the state file is the interactive Motif program defed which allows modification of the option settings through a menu-driven graphical interface. The program first shows a main selection window that shows all Alpha_1 programs listed in the master "a1defaults" file:

To edit a selected program, use the edit button of the main window. This should pop up an edit box for that program, e.g.:

You can edit more than one program at the same time. However, the only way to change the name of the state file being operated on is to restart the program.

The clear button will unset the changes to the default values of that program. To save all saved changes to the state file, use the save button from the main window.

defed [statefile ]
Output
<textfile> The given statefile is modified.
statefile
<string> The name of the state file to be used for initial values and modifications.

"Editdefs" Program

Another alternative for setting up the state file is the editdefs program. It is an interactive (command-driven) program which accepts simple commands for modifying the state file.

editdefs [ program [ statefile ] ]
Output
<textfile> The resulting state file is written to the standard output.
program
<string> The name of the program for which options will be edited. This sets an initial state, but options of any program may be edited during any execution of editdefs.
statefile
<string> The name of the state file to be used for initial values. If this option is omitted, then the system defaults will be used for all options.
The editdefs program accepts simple commands which specify actions to be performed on the set of known defaults. All may be abbreviated by their first letter.

prog name
Set the current program to the named one. This allows the program name to be omitted when specifying the individual settings of default values. This can be set initially from the command line as well.

display [ program ]
Displays all the defaults for the specified program. If the program name is omitted, then the current program (as set by the prog command above) is used.

display [ program.default ]
Displays the current setting for the specified option.

set [ program.default value ]
Set the value for the specified program option.

set [ default value ]
Set the value for the specified option of the current program (as set by the prog command or specified in the command line).

set [ .default value ]
Set the value of the specified option for all programs which use that option. This sets a global default.

edit
Interactively, list the value of each option associated with the current program, allowing them to be changed individually. A new value may be typed in for each option, or a carriage-return entered to leave the value as it stands. Typing the word "quit" (which may not be abbreviated within the edit command) exits the editing mode before reaching the end of the options list.

help
Print a message describing the commands.

quit
Writes the resulting state file (all options which have been set to values different from the system defaults) to the standard output and exits the editdefs program.

abort
Exit the editdefs program without writing out the results.

So the same a1ps example done above with aset could also be done with editdefs as follows (the editdefs prompt is shown): 

editdefs a1ps a1state >newstate
editdefs> s crvfineness 25.0
editdefs> s isolines off
editdefs> s meshes on
editdefs> q

a1ps -state newstate mydata.a1 >mydata.ps
Here is the resulting state file, which could easily be created with a text editor: 
a1ps.crvfineness:       25.0
a1ps.meshes:            on
a1ps.isolines:          off
However, the text editor does not let you know if you misspelled a name, and gives you no help (like editdefs) in remembering the names. The editdefs method may be simplest for new users. Experts may prefer the aset/aunset combination, and command scripts are best done with aset and aunset.

Command-line Options

Finally, we mention one other method that can be used instead of, or in addition to, the state files. The options can be typed directly onto the command line as name/value pairs, as in: 
a1ps mydata.a1 -isolines off -meshes on >mydata.ps
This form is nice if you just want to make a change temporarily, and then have later executions go back to the values in the state file. The command line specifications override the state file values. There are some disadvantages to using this exclusively. First, it's a little harder to get one massive line typed correctly. Second, the state files provide a sort of automatic history mechanism. The data which was used on the previous execution is readily available, and with a bit of care on the user's part, all the parameters for significant computations can be kept together.

Suppose a helicoptor model is to be generated in three standard views, using a standard set of shading parameters. We might have the following files:

copter.a1
The geometric data.

copter1.mat
The viewing matrix for the first view.

copter2.mat
The viewing matrix for the second view.

copter3.mat
The viewing matrix for the third view.

a1state
The state file describing shading parameters, image size, and shading mode.

The three images could all be rendered with: 

render copter1.mat copter.a1 >copter1.rle
render copter2.mat copter.a1 >copter2.rle
render copter3.mat copter.a1 >copter3.rle
Alpha_1 User's Manual Home Page
Alpha_1 User's Manual. Version 98.01.
Copyright © 1998, University of Utah
a1-web@gr.cs.utah.edu