Working with Return Value Arrays

Some commands, methods, and properties return an array of values. Depending on the scripting language you use, you may get either a Visual Basic safe array or an array of arrays. For example, if you run the command GetMarking() from VBScript or JScript, you get a Visual Basic safe array; if you run GetMarking() from PerlScript, you get nested arrays (array of arrays); and from Python, you get a tuple.

In VBScript, the native array is called a SafeArray, which is the standard array used inside Variants and for Automation scripting objects like the Softimage object model. For scripting languages other than VBScript, different strategies must used:

• JScript

• PerlScript

• Python

VBScript

Since SafeArrays are native to VBScript, you can work with a returned array using the standard VBScript methods (see http://msdn.microsoft.com/ for more information).

Dim arrMarkedParams, strItem, i
GetPrim "Null"
SetMarking "kine.local.pos,kine.global.pos"
AddToMarking "kine.local.ori"
arrMarkedParams = GetMarking()
for i=0 to UBound(arrMarkedParams)
   strItem = arrMarkedParams(i)
   LogMessage "Value of item at index " & i " = & strItem
next

' Expected result:
'INFO : Value of item at index 0 = kine.local.pos
'INFO : Value of item at index 1 = kine.global.pos
'INFO : Value of item at index 2 = kine.local.ori

JScript

There are some restrictions in working with returned arrays in JScript, because while JScript has its own native Array object, it is not a SafeArray and it does not support more than one dimension. However, many parts of the Softimage interface allow you to provide JScript arrays instead of SafeArrays. For example, you can pass in a native JScript array to Envelope.SetDeformerWeights (Weights parameter) but Envelope.GetDeformerWeights returns a SafeArray (see the example for Envelope.SetDeformerWeights.

In addition, JScript also provides a special kind of object called a VBArray. The VBArray object provides functions that allow you to read from a SafeArray (for example, access to multiple dimensions, upper- and lower-bounds) and also provides a handy method called toArray(), which converts the VBArray to a native JScript Array.

Most scripters prefer to work with a JScript array even if they only need to read the values, because converting a VBArray to a JScript array is very simple (var jsArray = vbArray.toArray();) and the JScript Array object has many more methods that are useful to work with (the VBArray is really only designed to provide basic access to the data).

GetPrim( "Null" );
SetMarking( "kine.local.pos,kine.global.pos" );
AddToMarking( "kine.local.ori" );

// GetMarking() returns a VBArray, which you can 
// convert to a JS Array with the toArray() function
var vbaMarkings = new VBArray( GetMarking() );
var jsaMarkings = vbaMarkings.toArray();
for ( var i=0; i<jsaMarkings.length; i++ ) {
	LogMessage( jsaMarkings[i] );
}

// Expected result:
//INFO : kine.local.pos
//INFO : kine.global.pos
//INFO : kine.local.ori

var vbaMarkings = new VBArray( GetMarking() );
var jsaMarkings = vbaMarkings.toArray();

var jsaMarkings = GetMarking().toArray();

// Returns a ClusterElementCollection
var cls_prop_elems = vertexcolor.Elements;

// Returns a VBArray
var vbValues = cls_prop_elems.Array;
Application.LogMessage( "# of dimensions: " + vbValues.dimensions() );
for ( var d=1; d<=vbValues.dimensions(); d++ ) {
   Application.LogMessage( "range of dimension " + d + ": " + vbValues.lbound(d) + ".." + vbValues.ubound(d) );
}

// Display info
var gridtable = MakeMeAPPG( vbValues );
InspectObj( gridtable, "", "", siModal, false );

// Change info
grid_mod = gridtable.Parameters("VertexColorChart").Value;
grid_mod.SetCell( 0, 0, 1.23 );
DeleteObj( gridtable );
gridtable = MakeMeAPPG( grid_mod.Data );

// Re-display modified info
InspectObj( gridtable, "", "", siModal, false );

// ***************************************
//
// 		Functions to support PPG
//
function MakeMeAPPG( in_SafeArray )
{
   var gprop = ActiveSceneRoot.AddProperty( "CustomProperty", false, "Visual2DArray" );			
   var gparam = gprop.AddGridParameter( "VertexColorChart" );
   var ugrid = gparam.Value;
	
   // Set bounds of this grid
   ugrid.ColumnCount = in_SafeArray.ubound(1)+1;
   ugrid.RowCount = in_SafeArray.ubound(2)+1;
   ugrid.Data = in_SafeArray;
	
   // Set up the labels
   var tmp = new Array( "R", "G", "B", "A" );
   for ( var c=0; c<ugrid.ColumnCount; c++ ) {
      ugrid.SetColumnLabel( c, tmp[c]) ;
   }
   for ( var r=0; r<ugrid.RowCount; r++ ) {
      ugrid.SetRowLabel( r, "Cluster " + r.toString() );
   }
	
   // Return the Property Set (not the Grid itself)
   return gprop;
}

PerlScript

What you get when using PerlScript is an element which is a reference to an array containing:

• Values (when the returned array is 1-dimensional)

• References to arrays of values (when the returned array is 2-dimensional)

• References to arrays of references to arrays of values (when the returned array is 3-dimensional)

This means that you need to extract each dimension by dereferencing the nested array inside the returned array. In most cases, SDK functions return a 1-dimensional array, so you can expect the nested array to contain a single element, which you simply dereference to work with. In the case of multi-dimensional arrays, the nested arrays contain multiple elements, each of which can be dereferenced as demonstrated in PerlScript Example: Looping through a (multi-dimensional) returned array.

$Application->GetPrim( "Null" );

# Mark some parameters on the null
$Application->ClearMarking();
$Application->SetMarking( "kine.local.pos,kine.global.pos" );
$Application->AddToMarking( "kine.local.ori" );

# The GetMarking command is supposed to return a 1-dimensional array...
my $array = GetMarking();
for $item (@$array) {
   $Application->LogMessage( "Marked parameters: $item" );
}

# Expected result:
#INFO : kine.local.pos
#INFO : kine.global.pos
#INFO : kine.local.ori

my $uvw_prop = $object->Material->CurrentUV;
my @rtn = $uvw_prop->Elements->Array;

for my $array_ref (@nested_array) {
   for my $value_for_u_v_or_w (@{$array_ref}) {
      # ...
   }
}

Python

Since Python (using the ActiveX Scripting Engine) converts all SafeArrays to tuples automatically. Tuples are one of two types of arrays available in Python:

• tuples—fixed sequences which are often used to return multiple values from functions, roughly equivalent to VBScript's static arrays.

• lists—dynamic arrays of values, roughly equivalent to VBScript's dynamic arrays.

Python provides a wide variety of very powerful functions for working with tuples and lists. For more information, refer to one of the Python sites mentioned in Where to Find More Information.

Application.GetPrim( "Null" )
Application.SetMarking( "kine.local.pos,kine.global.pos" )
Application.AddToMarking( "kine.local.ori" )
markings = Application.GetMarking()
i = 0
for mrk in markings
   Application.LogMessage( "Value of item at index " + str(i) + " = " + mrk )
   i = i + 1

# Expected result:
#INFO : Value of item at index 0 = kine.local.pos
#INFO : Value of item at index 1 = kine.global.pos
#INFO : Value of item at index 2 = kine.local.ori