## CreateValueMap

### Introduced

v1.0

### Description

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

    CreateValueMap( [Obj1], [Obj2], [Mode], [Scope], [UseNames], [MappingTemplate] );

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

### See Also

AddMappingRule CreateConnectionMap DeleteMappingRule GetMappingRule GetNumMappingRules SetMappingRule