GetMappingRule

Introduced

1.0

Description

Gets a rule in a connection or value mapping template, or in a clip value map.

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

    GetMappingRule( MappingTemplate, [Index], [From], [To], [Active], [PoseOffset] )

Parameters

Parameter | Type | Description
MappingTemplate | String | Mapping template or clip value map.
Index | Integer | Specifies the rule to modify. Rules are numbered starting at 1, but an index of 0 also refers to the first rule. Default Value: 0 (the first rule)
From [out] | String | Returns the "From" part of the rule.
To [out] | String | Returns the "To" part of the rule.
Active [out] | Boolean | Gets the activeness of the rule. Possible Values: • False: The rule is inactive. • True: The rule is active.
PoseOffset [out] | Boolean | Gets the pose offset flag for the rule. Possible Values: • False: The object is not pose offset. • True: The object is flagged for pose offset.

Examples

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 ->
    '"

See Also

AddMappingRule | CreateConnectionMap | CreateValueMap | DeleteMappingRule
GetNumMappingRules | SetMappingRule |  |

Autodesk Softimage v7.5