ネイティブ配列の使用

戻り値の配列を使用する

一部のコマンド、メソッド、およびプロパティは値の配列を戻します。 使用するスクリプト言語に応じて、Visual Basic のセーフ配列または配列の配列のいずれかを取得できます。 たとえば、VBScript または JScript から GetMarking()コマンドを実行すると、Visual Basic のセーフ配列を取得し、PerlScript から GetMarking()を実行すると、ネストされた配列(配列の配列)を取得します。また、Python の場合は、タプルを取得します。

VBScript では、ネイティブ配列は SafeArray と呼ばれ、Softimage オブジェクト モデルのように Variant 内部と Automation スクリプティング オブジェクトで使用される標準的な配列です。 以下のような VBScript 以外のスクリプト言語では、異なる方法が使用されます。

• JScript

• PerlScript

• Python

VBScript

SafeArray は、VBScript のネイティブ配列であるため、標準的な VBScript メソッドを使用して戻された配列を操作できます(詳細は、http://msdn.microsoft.com/を参照)。

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

JScript で戻された配列を操作するには、いくつかの制限があります。JScript にはネイティブの Array オブジェクトがありますが、そのオブジェクトは SafeArray ではないため、多次元をサポートしないからです。 ただし、Softimage インターフェイスの多くの部分で、SafeArray の代わりに JScript の配列を提供できます。 たとえば、JScript のネイティブ配列を Envelope.SetDeformerWeights(Weights パラメータ)に渡すことができますが、Envelope.GetDeformerWeights は SafeArray を戻します(Envelope.SetDeformerWeights の例を参照)。

さらに、JScript では、VBArray と呼ばれる特殊なオブジェクトも利用できます。 VBArray オブジェクトは、SafeArray から読み取る(たとえば、多次元の上限/下限値にアクセスする)ことができる関数を提供し、VBArray を JScript ネイティブの Array に変換する toArray()と呼ばれる便利なメソッドも提供します。

ほとんどのスクリプト開発者は、値を読み取るだけの場合でも JScript 配列で操作したがります。この理由は、VBArray を JScript 配列に変換するのは非常に簡単(var jsArray = vbArray.toArray();)で、JScript の Array オブジェクトには、操作に便利なメソッドが数多くあるためです(VBArray はデータへの基本的なアクセスを提供するためだけに設計されています)。

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

PerlScript を使用している場合に取得するエレメントは、以下を含む配列へのリファレンスです。

• 値(戻された配列が 1 次元の場合)

• 値の配列へのリファレンス(戻された配列が 2 次元の場合)

• 値の配列へのリファレンスの配列へのリファレンス(戻された配列が 3 次元の場合)

つまり、戻された配列内でネストされた配列を逆参照して、各次元を抽出する必要があります。 ほとんどの場合、SDK 関数は 1 次元の配列を戻します。したがって、ネストされた配列に含まれるエレメントは 1 つだけであると想定されるため、この配列を逆参照するだけで操作できます。 多次元配列の場合、ネストされた配列に複数のエレメントが含まれます。それぞれのエレメントは、「PerlScript の例: 戻された多次元配列をループする」に示す方法で逆参照することができます。

$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

Python は ActiveX スクリプト エンジンを使用するため、すべての SafeArray をタプルに自動的に変換します。 タプルは、Python で利用できる次の 2 種類の配列の一つです。

• タプル: 多くの場合、関数から複数の値を返すために使用される固定シーケンス。VBScript の静的配列とほぼ同じ。

• リスト: 値の動的配列。VBScript の動的配列とほぼ同じ。

Python では、タプルやリストの操作にさまざまな種類の非常に強力な関数が利用できます。 詳しくは、「詳しく調べるには」に記述された Python サイトのいずれかを参照してください。

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