Work with HSL data types

The following topics describe the types of data you can use in Shogun Post scripting, and shows how you can use them in arrays and convert a data type to another type.

Understand data types

You can address and access the following types of data from within a script:

• Boolean
• Float
• Int
• String
• Vector

Boolean

A boolean data type is a Boolean (logical) flag, that is one whose values can be evaluated as:

• true / false
• on / off
• yes / no
• toggle state

Float

A float data type is a floating point number, that is one that contains a decimal point.

Int

An int data type is a an integer, that is a whole number.

String

A string data type is any sequence of characters (letters, numbers, or special characters). Character names, marker names, bone names, and all other objects in Shogun Post are addressed using strings. In order to work with those objects, you must declare strings for them.

Objects or modules in Shogun Post are not required to have unique names as long as their paths are unique. In order to reference a particular object in the scene using a string, you must specify its module path. A module path is the path traversed from the top of the Shogun Post object hierarchy down to the module. A path you specify for a string in your script can consist of a full path, partial path, or only the object name.

Strings do not need to be surrounded in quotation marks unless they contain spaces or start with a number. You can include variables and special characters in strings by using the \ (backslash) escape character and a double quotation mark. You can concatenate (append) strings to other strings using the plus sign + arithmetic operator.

String examples

These example show you how to declare and work with strings.

// Declare a single string 
string $markers = "LFHD";
 
// Append strings
string $string = "test" + "one";
 
//Include quotation mark
Print "print the \" ";
 
// Specify full path name
Actor_1\root\lfemur\ltibia
 
// Look for top-level node named rfemur
rfemur\>
 
// Find first rfinger object that has no children 
// (i.e. is a leaf node in the hierarchy)
<\rfinger
 
// Find first descendent of relbow named rfinger where relbow is a top-level node
relbow\\rfinger 
// Find first descendent of rfemur named rfoot where rfemur may be a 
// top-level node
\\rfemur\\rfoot
 
// Find descendent named ltoe of Actor1 whose immediate parent is lfoot:
Actor_1\\lfoot\ltoe
 
// Select objects by module path and name
select rfemur\>
zoomView -selected;

Strings sample script

This example shows how to declare and work with strings.

// Declare your strings
string $a ;
string $b ;
string $c ;
boolean $start_pos;
// Retrieve some properties
$a = `getStringProperty LFHD Rotation_Order` ;
print $a;
$b = getStringProperty( LFHD, Name );
print $b;
// Return array of any selected modules in the scene
string $selected[] = `getModules -selected`;
string $junk = string($selected[0]);
print $junk;
// Determine if that module has any keys on it or not
$start_pos = `hasKey $junk Translation`;
print ( " Does the object have any keys " + string ($start_pos) );

Vector

A vector data type is a one-dimensional array of three floating points or integers (stored as floating points). This data type is used to list X,Y,Z positions or X,Y,Z rotations for a given object. When you are working with captured marker data or animated skeletons, you frequently have to edit or evaluate hundreds or thousands of points stored in vector variables.

You assign components of vectors by including a period (.) between the vector variable name and each x, y, or z component. For example:

vectorName.x

Vector examples

These examples show you how to assign a vector variable and display its x,y, and z values to the Log:

//Assign three vector values separately
vector $translation = <<2.33, 4.55, 6.57>>;
float $ Xcomponent = $ translation.x; //Assigned 2.33
float $ Ycomponent = $ translation.y; // Assigned 4.55
float $ Zcomponent = $ translation.z; // Assigned 6.57
print $translation;
//Assign all three vector values simultaneously
vector $rot = <<8.99, 0.11, 2.33>>;
float $ Xcomponent = $ rot.X;   //Assigned 8.99
float $ Ycomponent = $ rot.Y;   //Assigned 0.11
float $ Zcomponent = $ rot.Z;   //Assigned 2.33
print $rot;
print $ Xcomponent;
print $ Ycomponent;
print $ Zcomponent;

This example shows you how to assign a vector variable for rotation:

rotation $rotation = <[8.99, 0.11, 2.33]>;
float $Xcomponent = $rotation.x;   //Assigned 8.99
float $Ycomponent = $rotation.y;   //Assigned 0.11
float $Zcomponent = $rotation.z;   //Assigned 2.33

The script below can be run on an empty scene. It shows you how to set the value of a vector to any set of three numbers. This is useful because you can use this to set keys by script.

// Define the variable you will use to store the vector
vector $vec;
// Assign the vector as a set of three numbers
$vec = <<1,0,0>>;
// Print the $vec variable
print $vec;
// Change the value of the magnitude of a vector's translation value
setLength $vec 2.6;
// print the $vector
print $vec;

This example shows you how to get the dot product of two vectors.

vector $a = <<5 , 1, 6 >>;
vector $b = <<4 , 4, 2 >>;
float $c = `dot $a $b`;
print (string ($c));

Vector sample script

You can use the following script as a guide and a template for working with vector data. Note that this is not the most useful application of vector editing or arithmetic but its an easy to understand application which can be adapted to many purposes. Refer to the comments to see what each set of statements does.

// Define variables for use in the script. Note that the $mod
// variable is used to store the name of the object you want to adjust.
// The vector variables, $vec and $rot will store position and rotation values
string $mod = LFWT;
vector $vec = `getVectorProperty $mod Translation`;
vector $rot = `getVectorProperty $mod Rotation`;
// In the following line, you define $output as a statement that
// identifies the object being modified, and its X, Y, Z position
string $output = string( $mod ) + "'s Translation is " + string( $vec );
// This prints the statement.
print( $output );
// This set of statements selects the $mod object, selects its
// entire ranges, then all keys in that range
select $mod;
selectRange -all;
selectKeys -ranges;
// This statement sets the X, Y, Z position of $mod
// to the X, Y and Z values stored in the $vec variable
setProperty -r "Translation" $vec.x $vec.y $vec.z;
print( "Just set the property on LBWT!!! Ugly, ain't it?" );

Use arrays

Shogun Post allows you to declare an array of boolean, float, int, string, or vector data types.

You declare (initialize) an array by including the array size in square brackets after the variable name. For example:

data_type $variable_name[array_size]

Shogun Post uses a zero-based system, so in order to access an element in an array, the index of the first element must be 0 (zero).

You assign a value to an element of the array using the equals sign (=). For example:

$variable_name[array_element] = [value]

Array examples

This example shows you how to create an array and print the data to the command line:

int $frames[3];
$frames[0] = 1; //Assigned 1 to first element of array
$frames[1] = 5; //Assigned 5 to second element of array
$frames[2] = 10; //Assigned 10 to third element of array
print $frames;

This example shows you how to assign a value of 30 to the second element of an array (remember, array elements start at 0 (zero):

$intArray[1] = 30;

This example shows you how to create output in sequential order:

int $array[3];
$array[0] = 1;
$array[1] = 2;
$array[2] = 3;
print $array;

This gives the output:

1
2
3

However, note that the following example produces output in reverse order:

int $array[];
$array = [[ 1, 2, 3 ]];
print $array;

This gives the output:

3
2
1

Use data type conversions

From time to time you will have to convert data from one type to another. For example, you may need to convert an integer to a string.

You can use the following methods to convert data from one type to another:

• Explicit type conversion
• Integer division truncation
• Precision and Maximum Numerical Sizes
• Range Wrap-Around

Explicit type conversion

You can convert values to different data types using type casting. This script fragment demonstrates type conversion and prints results to the Log.

 // Value:15.0
 float $conversion = float(15);
 int $start = 123;
 string $frame = string($start); // Value: "123"
 // printing values
 print $start;
 print $frame;
 print $conversion;

Integer division truncation

In arithmetic operations, Shogun Post will use displayed values to determine the data type of a constant or variable when no data type is declared. For example:

// Result: 0
float $tuna = 1/2;
print $tuna;

The numbers 1 and 2 are integers because they have no decimal points. Therefore, integer 1 is divided by integer 2, resulting in 0 with a remainder of 1. Shogun Post discards the remainder.

In this example, tuna is a float variable, so Shogun Post converts the integer value 0 to floating point value 0, then assigns this value to tuna. The fractional component of the value can be obtained by converting one or more of the integer operands to a float. For example:

//Result: 0.5
float $tuna = 1.0/2.0;
print $tuna;

By adding the decimal point, 2.0 becomes a floating point number. The number 1 is converted to a float and divided by the number 2.0, resulting in the value 0.5 which is assigned to tuna. This may also be accomplished using the method shown in the following example:

//Result: 0.5
 float $tuna = float (1) /2;
 print $tuna;

The number 1 is converted to a float, thus causing the 2 to be converted to a float also. This allows a float division to take place, and maintains the fractional result of 0.5.

Precision and maximum numerical sizes

There are limits to the precision sizes of floats and integers. The maximum size is dependent on the user's machine, as defined in the C++ programming language. Floats have limited precision, so you must be careful to avoid round-off errors that occur in long calculations (when exceeding fifteen digits).

//Value: -1294967296.000000
float $sushi = 1.5 + 1000000000 3;
print $sushi;

Range wrap-around

Exceeding the limited range of a variable causes it to wrap-around to the variable's minimum range which may result in errors. The negative results may occur when the minimum range of a variable is exceeded and it wraps around to the variable's maximum range.

//Value: -2147483648
int $tuna = 2147483647 + 1;
//Value: 2147483647
int $salmon = -2147483648 - 1;
//Value: -2147483648
int $dolphin = 2147483648;
//Value: -2147483647
int $mackerel = 2147483647 +2;
print $tuna;
print $salmon;
print $dolphin;
print $mackerel;