Format HSL scripts

You can maximize your efficiency and reduce the time it takes you to complete projects by creating scripts. Most people use Shogun Post to perform the same types of tasks repeatedly. Taking three hours to create a great script for performing a task that would only take you half an hour is a good investment— if you use the script just six times, it has paid for itself. If you use it a hundred times you have saved yourself almost a week of production time. Scripting is even more critical when you work with several motion capture professionals. Scripts enable you to ensure that all data is handled the same way by all operators, resulting in consistent data.

To be really useful, however, your scripts must be readable, easy to customize, and bulletproof. Follow these suggestions when you create scripts and you will find that you and your associates spend less time looking for bugs and more time producing high-quality motion capture animation:

Use spacing

Using the right spacing and indentation makes your scripts easier to read, easier to use, easier to customize. Spacing does not affect the execution of a script, so you can use as many spaces, line breaks, and tabs as you like.

The following is an example of a poorly spaced script. As you can see, it is difficult to understand the structure of the script, to identify the variables, or to figure out what the script does.

if ( ( `getCount $ selectionArray ` ) == 2 ){
vector $source1 = $selectionArray[0].Translation; vector $source2 = 
$selectionArray[1].Translation; vector $position = ( $source2 - $source1 );
float $distance = `getLength $position `; print ( "The distance between " + (
 string ($selectionArray[0]) ) +" and " + ( string ($selectionArray[1]) ) + " is " + ( string ( $distance ) ) + "mm ." );
} if ( ( `getCount $ selectionArray ` ) != 2 )
print "Must have exactly 2 nodes selected."; $text = "Default scaling";

Here is the same script that is easier to read with improved spacing:

if( ( `getCount $selectionArray` ) == 2 )
{
vector $source1 = $selectionArray[0].Translation;
vector $source2 = $selectionArray[1].Translation;
vector $position = ( $source2 - $source1 );
float $distance = `getLength $position `;

print ( "The distance between " + 
( string ($selectionArray[0]) ) +
" and " + ( string ($selectionArray[1]) ) +
" is " + ( string ( $distance ) ) + "mm ." );
}
else
{
print "Must have exactly 2 nodes selected.";
}
$text = "Default scaling";

Each command statement is on its own line. The If/Then loop elements are on their own lines. Variables are defined on their own lines. Print statements are structured so you can see at a glance what elements are being assembled. Take time to format scripts whenever you create them. You will find that the investment pays off the very next time you need to use them.

Add comments

HSL scripts without comments are like city maps without street names. They might take you somewhere, but you can not be sure it will be where you want to go.

Add comments to your scripts so it is easy for you and for others to understand what each section of the script does, and what data can be changed. To add a comment to a script, just put two forward slashes at the start of the comment line //.

// Default locator number is lucky.
 int $locator = 7;
 // Select the head markers and make a rigid body

Use a naming convention

If you develop and use some kind of consistent strategy you routinely use for defining variables and naming objects, you will save yourself hundreds, if not thousands, of hours of debugging time.
Follow these suggestions to use a convention to name variables and objects logically and concisely:

• Pick a case:

  Because the Shogun Post HSL Scripting Language is case sensitive, AUX1, aux1, and Aux1 are three entirely different names. Pick a naming strategy you can remember and live with. For example, you may want to make all object names uppercase and all variable names lowercase. That way you can quickly recognize whether a variable is an object, a variable, or a Shogun Post command (since those are frequently mixed-case). Whatever strategy you select, stick with it.

  By default, Shogun Post scripts start with a capital letter and use internal capitalization, that is, each keyword within the script name starts with a capital letter, for example: FillGapsRigid. This helps to distinguish Shogun Post scripts from commands.

• Use descriptive variable names:

  Pick variable names with meaning. Variables like x, I and tr mean nothing two hours after you write them. Avoid being overly descriptive because long times are hard to type and hard to debug. Consider putting in comments near where variables are defined to identify their use. Knowing that $rad is radius and not an angle measurement in rads is useful information.

• Avoid burying user-defined numbers or parameters:

  Define variables as close to the top of a script as possible. Make the variable assignments rational and easy to understand. Use the variable you set later in the script, and change its value as required. It is easiest to debug scripts when variables are initially defined at the top of a script with values like:

  float $headOffset = 150;
string $errorMessage = "Need to select object first.";

  Let's say you used the headOffset variable at the beginning of the script and used that variable instead of the actual number at each place in your script where it was needed. You could quickly change the value of headOffset to increase its accuracy.

• Bulletproof scripting:

  When composing HSL scripts, keep all levels of users in mind. Make sure that the HSL script considers user errors and handles these errors gracefully. Think about the errors that your HSL script might encounter. After checking for an error and finding that it is present, have a reasonable contingency action in your HSL script for that error, such as politely informing you of the missing components.

  Example:

  module $selected = `getModules -selected -primary`;
  int $num_selected = `getCount $selected`;
  string $primaryName;
  // This conditional will run if there was
  // at least one marker selected.
  if ( $num_selected >= 1 ){
        select;
        select $selected[0];
        $primaryName = `getProperty $selected[0] "Name" `;
        print ( "Made " + string( $primaryName) + " primary and only selection." );
        }
  // This statement will be executed if no markers were selected.
  if ( $num_selected == 0 ){
        print "No markers were selected.";
        } 

  In this example, if the user has not selected any markers, the script creates an error message rather than failing.

• Never overwrite data or files automatically:

  Many scripts modify hundreds or thousands of keys. Making a script which bakes that data over the original data or saves a file that overwrites the original is asking for disaster. Obviously, sooner or later someone is going to run that script, mangle data, and destroy the good data they had to start with. HSL scripting tools make it easy to save files with new names or create data on clips or layers. Use that functionality to protect your raw data.