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.
render cup.a1 >cup.rleThe "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.
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.
- <binarystream> Convert input text binary stream. The input may contain binary data mixed in with the text data.
- <filelist> Files to be converted. They may be text or binary.
conv file1 file2 file3 ... >file.a1Output 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.
- <textstream> Convert input binary stream to text stream.
- <filelist> Binary files to be converted.
<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
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 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 ]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.
- <textfile> Normally, the given statefile is modified to set the specified value.
- <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).
aunset [ statefile ] option-name
- <textfile> Normally, the given statefile is modified to reset the specified value.
- <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.
- <string> The option to be reset, in the form program.option, specifying which option of which program is to be changed.
aprint [ statefile ] programSo a sample invocation of the PostScript generation program mentioned above (a1ps) might be:
- <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.
- <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.
- <string> The name of the program for which settings are to be listed.
aset a1ps.crvfineness 25.0 aset a1ps.isolines off aset a1ps.meshes on a1ps mydata.a1 >mydata.psNormally, 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.
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 ]
- <textfile> The given statefile is modified.
- <string> The name of the state file to be used for initial values and modifications.
editdefs [ program [ statefile ] ]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.
- <textfile> The resulting state file is written to the standard output.
- <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.
- <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.
- 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.
- 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.
- Print a message describing the commands.
- 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.
- 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.psHere is the resulting state file, which could easily be created with a text editor:
a1ps.crvfineness: 25.0 a1ps.meshes: on a1ps.isolines: offHowever, 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.
a1ps mydata.a1 -isolines off -meshes on >mydata.psThis 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:
- The geometric data.
- The viewing matrix for the first view.
- The viewing matrix for the second view.
- The viewing matrix for the third view.
- 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