Caret Scripting


Included with the caret distribution is a program named caret_command.  The purpose of caret_command is to provide a command line interface to many of Caret5’s underlying operations.


There are several ways to run caret_command.  First, caret_command may be run in a terminal window in which caret_command is followed by parameters to perform an intended operation.  Second, there is a graphical user-interface within Caret5 that allows the immediate execution of each of caret_command’s operations.  Third, Caret5 contains a graphical-user interface to a script builder that is used to assemble a sequence of caret_command operations.


Command Line


One way to run caret_command is through entering commands in a terminal window.  This is probably familiar to old Unix users and old DOS users.  For a list of caret_command operations, run “caret_command –help”, which will list a brief summary of each of caret_command’s operations (about 160 at this time).  To see a full description of each operation, run “caret_command –help-full”.  To see a full description of a single operation, specify the operation without any parameters.  For example, the output of “caret_command –surface-curvature” is shown below.


noodle 8 % caret_command -surface-curvature


      caret_command -surface-curvature 







         [-mean-column-name  name]

         [-gaussian-column-name  name]


         Generate curvature measurements for the surface.


         The column names are optional, and, if not specified

         are Folding (Mean Curvature) and Gaussian Curvature



         The "input-surface-shape-file-name" does not needs

         to exist.



In the command listed above, required parameters are contained within less-than and greater-than symbols (“< >”).   Optional parameters are contained within square brackets (“[ ]”).


GUI single command execution


Within Caret5, a graphical user-interface to each caret_command operation is provided.  To access this interface, select “Caret Command Executor” from the Window menu.  The Caret Command Executor window contains several section.  The section labeled Commands lists all of caret_command’s operations.  When a command in this section is selected, help information about the command is displayed in the “Command Description” section and an interface for setting each of the command’s parameters is provided in the “Parameters” section.  Once the parameters have been entered, pressing the Execute push button will execute the caret_command operation.




Script Builder


The script builder is available by selecting Caret Command Script Builder from the Window Menu.  The script builder provides a graphical user-interface for constructing a sequence of caret_command operations.  Buttons along the bottom of the script builder window include New (start a new script), Open (open an existing caret script file), save (save the script in the window to a caret script file), Run (Run the script in the window), and Close (close the window).


On the left side of each command is a sequence of buttons.  These buttons are Add (add a new operation before or after the current operation), Del (delete the current operation), Help (show help information about the operation), Up (move the current operation so that it is above the operation immediately above), and Down (move the current operation so that it is below the operation immediately below).


Since the name of a file or other parameter may be used by multiple commands, the script builder allows variable to be defined using the –script-variable-set command.  In addition, the –script-variable-read command allows the script to ask the user for a variable value.  All variable names must begin with a dollar symbol ($).




Creating a caret_command manual HTML or PDF Manual


There are many operations available from caret_command.  There are several ways to generate a manual containing all of the commands.  Within caret_command are the operations –help-html and –help-pdf which are used to generate a manual containing all of caret_command operations.  The manual may be generated by running caret_command on the command line or by using the Command Executor user-interface.



Running a Caret Script File


There are several ways to run a script file.  The first, is by loading the script into the Script Builder and pressing the “Run” push button.  The second is on the command line using caret_command (e.g.  caret_command –script-run file.script).  If any command in the script file fails, no additional commands are executed.


Conversion to a scripting language


Using the operation “-script-convert”, a caret script file may be converted to a scripting language.  Currently, caret script files may be converted to either Bourne Shell (/bin/sh) or DOS Shell (Windows’ “.bat” files).  A successful strategy may be to develop a script using Caret’s Script Builder so that it operates on a specific set of files.  Once the Caret script is functioning properly, convert the script to a shell script so that more complex programming structures may be added.

Metric/Paint/Shape column names/numbers


For commands that require a parameter that identifies an existing column identifier, the column may be identified by its name or its column number starting at one.



Surface Shape Commands


If you look through the help commands, you will notice that there are no operations for surface shape files.  Keep in mind that metric and surface shape files are the exact same file format.  So, any operation that uses a metric file will also accept a surface shape file.