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