CreateValueMap

Traverses two hierarchies, computes the differences in their transformations, and outputs the differences to global value mapping template of the first hierarchy. Value-mapping templates provide a way for you to automatically modify the animation values in an action when you create clips. For example, you can add an offset so that two characters don't try to walk in the same place at the same time. Similar to connection-mapping templates, value-mapping templates let you map out information before you perform an action.

Each model can have multiple value-mapping templates and each of these templates can be active or not. The order of templates is the order of their creation, as listed in the explorer. You can automatically create a template that contains the offsets of the current transformation values between two objects or you can create an empty value-mapping template and then add rules manually.

Important: The two hierarchies must have the exact same topology, that is, the same number of children and the same subtree structure.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:

For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.

For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

Scripting Syntax

Parameters

Parameter Type Description

Obj1 String Root of the target hierarchy on which to create the value map.

Note: The mixer under this object's model will be the owner of the newly created value map.
Default Value: User is prompted to pick

Obj2 String Root of the hierarchy used as the reference pose
Default Value: User is prompted to pick

Mode Integer Specifies the portions of the pose that will be considered when evaluating the differences for the value map.
Default Value: 4 (all differences)

Possible Values:

Description:

0 Put no data into the template.

1 Put scaling differences into the template

2 Put rotation differences into the template

3 Put translation differences into the template

4 Put all differences into the template

Scope Integer Specifies whether to compute differences for local or global transformations
Default Value: 1 (local)

Possible Values:

Description:

0 Put global transform data into the template.

1 Put local transform data into the template.

2 Put both local and global transform data into the template.

UseNames Boolean Specifies how to compare the hierarchies.
Default Value: False

Possible Values:

Description:

False Use topology-based hiearchy matching.

True Use name comparison-based hiearchy matching.

MappingTemplate Property Returns the new mapping template.

Examples

1. VBScript Example

' This example illustrates various mapping template commands,

' for both connection and value mapping templates -- in particular

' how to create them and look at the data contained in them.

NewScene , False

' Create some objects for our example.

set oParent = CreatePrim( "Sphere", "MeshSurface", "Parent" )

set oChild = CreatePrim( "Cone", "MeshSurface", "Child", oParent )

posParams = "/kine.local.posx,kine.local.posy,kine.local.posz"

' Animate the sphere moving horizontally and the

' cone (child) moving down.

SetPositionKey oParent, 1, -5, 0, 0

SetPositionKey oParent, 50, 5, 0, 0

SetPositionKey oChild, 1, 0, 0, 0

SetPositionKey oChild, 50, 0, -2, 0

' Store an Action of this animation (on both objects).

set oSource = StoreAction( , oParent & "," & oChild & posParams, 2, _

			"Fun", True, 1, 50 )

' We want to map the animation to another "character", so we will

' use a connection mapping template.  CreateConnectionMap can look

' at identical hierarchies and automatically build an appropriate

' map.  (or you could build it yourself manually or using scripting)

' Here we'll build a hierarchy and use the auto-matching capability...

set oParent2 = CreatePrim( "Cube", "MeshSurface", "Top" )

set oChild2 = CreatePrim( "Cylinder", "MeshSurface", "Bottom", oParent2 )

' Translate it so we can demonstrate value mapping templates.

Translate oParent2, 2, 5, 0, siAbsolute, siView, siObj, siXYZ

Translate oChild2, 2, -5, 0, siAbsolute, siView, siObj, siXYZ

' Instantiate a clip driving the objects on which the animation was

' originally authored, for comparison.

set oClip = AddClip( "Scene_Root", oSource, , , 1, "Original" )

' Now create the connection map so we can apply the original animation

' on the other hierarchy.  Also, create a value map which will build

' offset expressions using the pose differences between the objects.

CreateConnectionMap oParent2, oParent, oCnxMap

CreateValueMap oParent2, oParent, 3, 1, False, oValMap

' Instantiate a clip which uses the connection map to remap to the

' second set of objects.  Also use the value map to create a clip

' effect with the appropriate offset for the second hierarchy.

set oClip = AddClip( "Scene_Root", oSource, , , 1, "Remapped", oCnxMap, oValMap )

' Let's take a look at the connection and value mapping templates

' that were created and used.

DumpTemplateInfo oCnxMap

DumpTemplateInfo oValMap

' Finally, a clip itself can be treated as a (value) mapping template.

' Let's look at one...

DumpTemplateInfo oClip & ".actionclip"

'==================================================

' Helper method to key an object somewhere at a given frame.

'==================================================

sub SetPositionKey( in_oObj, in_frame, in_posX, in_posY, in_posZ )

	Translate in_oObj, in_posX, in_posY, in_posZ, siAbsolute, siParent, siObj, siXYZ

	SaveKey in_oObj & posParams, in_frame

end sub

'==================================================

' Helper method to dump some mapping template info.

'==================================================

sub DumpTemplateInfo( in_Templ )

	' Get the actual object referenced by name in the argument.

	set oTempl = GetValue( in_Templ )

	msg = "Template: " & oTempl.fullname & Chr(10)

	numRules = GetNumMappingRules( in_Templ )

	if oTempl.type = "actionclip" then

		msg = msg & "(Clip acting as value map)" & Chr(10)

		bSupportsActive = true

	else

		bSupportsActive = false

	end if

	for i = 1 to numRules

		GetMappingRule in_Templ, i, param, expr, active

		msg = msg & Chr(9) & "Rule " & i & ": "

		if bSupportsActive then

			if active then

				msg = msg & "( active ) "

			else

				msg = msg & "(inactive) "

			end if

		end if

		msg = msg & param & " -> " & expr & Chr(10)

	next

	LogMessage msg 

end sub

' Running this script should log the following:

' ---------------------------------------------

'INFO : "Template: Mixer.MappingTemplate

'	Rule 1: Parent -> Top

'	Rule 2: Child -> Bottom

'"

'INFO : "Template: Mixer.ValueMappingTemplate

'	Rule 1: Top.kine.local.posx -> this + -3.000000

'	Rule 2: Top.kine.local.posy -> this + 5.000000

'	Rule 3: Top.kine.local.posz -> 

'	Rule 4: Bottom.kine.local.posx -> 

'	Rule 5: Bottom.kine.local.posy -> this + -8.000000

'	Rule 6: Bottom.kine.local.posz -> 

'"

'INFO : "Template: Mixer.Mixer_Anim_Track1.Remapped.actionclip

'(Clip acting as value map)

'	Rule 1: ( active ) Top.kine.local.posx -> this+-3.000000

'	Rule 2: ( active ) Top.kine.local.posy -> this+5.000000

'	Rule 3: ( active ) Top.kine.local.posz -> 

'	Rule 4: ( active ) Bottom.kine.local.posx -> 

'	Rule 5: ( active ) Bottom.kine.local.posy -> this+-8.000000

'	Rule 6: ( active ) Bottom.kine.local.posz -> 

'"

2. VBScript Example

' Create first hierarchy

CreatePrim "Cone", "NurbsSurface", "MyCone"

CreatePrim "Cylinder", "NurbsSurface", "MyCylinder", "MyCone"

SetValue "MyCylinder.cylinder.height", 2

' Create second hierarchy translated from the first one

CreatePrim "Cone", "NurbsSurface", "MyCone1"

Translate , 5, 0, 0, siAbsolute, siParent, SiObj, siX

CreatePrim "Cylinder", "NurbsSurface", "MyCylinder1", "MyCone1"

Translate , , , , siAbsolute, siParent

' Create a value map.

' Put local translation differences into the template,

' and use topology based hierarchy matching, starting

' with MyCone1 as the reference.

CreateValueMap "MyCone", "MyCone1", 3, 1, False

' Although it appears that nothing has happened,

' a value-mapping template was indeed created for MyCone.

' You can check for it in the

' Mixer > Templates > Value Mapping folder in the explorer.

' If you open the Value Mapping Template, you will see a translation

' of -5 along the X axis for MyCone relative to MyCone1

CreateValueMap

Introduced

Description

Scripting Syntax

Parameters

Examples

1. VBScript Example

2. VBScript Example

See Also