CreateConnectionMap

Creates a connection mapping template for two hierarchies. You can create a connection-mapping template that automatically maps the object names in a source hierarchy to a target hierarchy. Connection-mapping templates are sets of rules used to convert object and parameter names in action sources to those that are available in a model. For example, if you have an action that animates a model with an object called LEFTARM, you can use a connection-mapping template to apply this action to another model with an object called left_arm.

Each model can have multiple connection-mapping templates and each of these templates can be active or not. You make connections when you instantiate an action clip. The rules from the first active template in the list are used.

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#).

Parameter	Type	Description
Obj1	String	Root of the target hierarchy on which to create the connection map. Note: The mixer under this object's model will be the owner of the newly created connection 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
MappingTemplate	Property	Returns the connection mapping template.

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 connection map.
' MyCone1 is the target of the map, which will contain mappings
' from the reference hierarchy (MyCone) to the corresonding
' objects in the target (MyCone1) hierarchy.
CreateConnectionMap "MyCone1", "MyCone"
' Although it appears that nothing has happened, 
' a connection-mapping template was indeed created 
' for MyCone1 and its child (since the two hierarchies have
' the same structure). 
' You can check for it in the
' Mixer > Templates > Connection Mapping folder in the explorer.
' If you open the property page for the Connection map you will
' see that the rule maps parameters on the objects named MyCone
' and MyCylinder to the corresponding parameters on the objects
' named MyCone1 and MyCylinder1.