Python script commands

Warning:This information is for advanced users only. Errors in Python scripting can seriously mess up your SFM session. The dragons found here make the Element Viewer's dragons tremble in fear. Proceed with extreme caution.

The following are the commands that are currently recognized by the SFM scripting system, which can be used for constructing character rigs.

You can find source code for the vs module here: C:\Program Files (x86)\Steam\steamapps\common\SourceFilmmaker\game\sdktools\python\2.7\win32\Lib\site-packages\vs

Warning:Be aware that the SFM team may change the script bindings and thus break all external scripts at any time.

Where an argument to an SFM script command to select DAGs is a DagName, the argument is handled as follows:

• "<animationSet name>"—Selects all DAGs that are members of the animationSet, e.g., "spy".
• "<ControlGroup name>"—Selects all the DAGs that are members of the control group, e.g., "Body", for the current animation set.
• "<control name>"—Selects the DAG that corresponds to the control name, e.g., "bip_head", for the current animation set.

The second and third of these can be prefaced by an animationSet name followed by ":" to specify DAGs that are members of a specific animation set, e.g., "spy:Body", "spy:bip_head", or "w_shotgun:weapon_bone".

Vectors means a list of 3 values in game units (about 1" each) in 3-space for X, Y, Z axis, e.g., [0, 0, 1] or [0.0, 0.0, 1.0], which in world space would point up.

Rotation means a list of 3 values representing Euler angles using degrees for rotation, e.g., [0, 0, 90].

AddControlToDisplaySet

Warning:This method is deprecated and no longer presented in the latest version of SFM

AddControlToDisplaySet( displaySetName, controlName, [remove=boolean] )

Description: Add the control group to the specified display set.

Arguments:

• displaySetName: Name of the display set to which the control is to be added.
• controlName: Name of the control to add. Controls are represented by an "Element" but elements can be many things. What we mean here by control is only one of 2 elements: a DmeTransformControl or a DmElement. They're the only things you'll find in the control field of the animationset—e.g., bone controls (DmeTransformControls) and facial controls (DmElement)—where AddControlToDisplaySet looks.

Parameters:

• remove (boolean) [default=False]: If True, this parameter specifies that the controls should be removed from the specified group instead of added.

Examples:

# Create a "Left" display set, add the left hand and foot, then hide the display set
sfm.CreateDisplaySet( "Left" )
sfm.AddControlToDisplaySet( "Left", "rig_hand_L" )
sfm.AddControlToDisplaySet( "Left", "rig_foot_L" )
sfm.HideDisplaySet( "Left", hide=True )

# Remove the hand from the "Left" display set
sfm.AddToDisplaySet( "Gun", "rig_hand_L", remove=True )

AimConstraint

AimConstraint( targetDag1, [targetDag2], [targetDagN], slaveDag, [name=string], [group=string], [mo=boolean], [w=float], [wu=vector], [wuSpace=string], [refObject=string], [controls=boolean] )

Description: Create an aim constraint. The command may either use the existing selection or create a temporary selection in line. The constraint will be applied to the last DAG node in the selection and will use all of the proceeding DAG nodes in the selection as targets. Returns DmeConstraintTarget if success, None if error.

Multiple targets may be specified with weights so that the target the slaveDag is constrained to is a weighted average of the target locations. If the sum total of all AimConstraint weights is less than 1.0, then it will blend with the existing animation. If over 1.0 it's the same as 1.0 unless there are multiple targets and in that case, they are all normalized to 1.0 and their weights treated proportionately.

You can only have one aim constraint per slaveDag. When calling AimConstraint, it will create a new aim constraint if none present otherwise on repeat calls it will add a new source target to the list of targets of that constraint with its weight.

If weight control and channel are not created, you won't be able to change the weights outside the Element Viewer. Set control to False if you're creating a constraint where there's only one target so the weight isn't important and you're not interested in animating the weights. If no control or channel, when AimConstraint is evaluating, there's nothing that will be able to change the weight.

Arguments:

• targetDag1: Name of the DAG node that is to be aimed at. Multiple targets may be specified.
• slaveDag1: Name of the DAG node of which the orientation is to be constrained to aim at the target location.

Parameters:

• name (string): Name to assign to the new constraint.
• group (string): Name of the control group to which the constraint is to be assigned.
• mo (boolean) [ default=False ]: Maintain offset, if True the slaveDag will maintain its current orientation for the current location of the target.
• w (float) [ default=1.0 ]: Weight to be applied to all of the targets specified. If different weights are required separate commands may be used to add multiple targets with different weights to the same constraint.
• wu (vector) [ default=[0, 0, 1] ]: World up vector, vector to be used as the world space up in the aim constraint calculation. Only the direction is used, its magnitude is irrelevant. This is the vector the constrained DAG will try to maintain as its up vector. By itself, the aim vector does not completely constrain an object because the aim vector does not control how the object might rotate about the aim vector. The orientation of the object about the aim vector is controlled by the world up vector. Ultimately, you need 2 vectors to define a space. First is aim direction, second is the closest to the world up vector that is orthogonal to the aim vector. If the aim vector and the world up vector are the same or even close in direction, then the constraint will produce spinning or little adjustments to make it fly around. It's best to pick a world up vector that is not likely to be coincidence with the aim vector. If you're doing it for a character, often the pelvis is used so you avoid problems if lying down.
• wuSpace (string) [ default="World" ]: The specification of the space in which the world up vector is defined in as opposed to the space the aimconstraint is operating in.

"World" : Up vector is defined in world space

"Parent" : Up vector is defined in the space of the parent of the constrained DAG node

"RefObject" : Up vector is defined in the space of another DAG node the is specified by the refObject

"Object" : Up vector is defined in the space of the Object. Might not make sense for AimConstraint as it would be evaluating the constraint using the space you're defining.

• refObject: Name of the DAG node to be used as the reference space for the world up vector.
• control (boolean) [ default=True ]: If True, create weight controls and channel. If False, weight control and channel not created.

Examples:

# Create an aim constraint to make the head's rotation follow the "look at" rig handle previously defined.
sfm.AimConstraint( "rig_lookAt", "rig_head", wu=[ 0, -1, 0 ], wuSpace="refObject", refObject="rig_pelvis", mo=True )

BeginRig

BeginRig( rigName, [append=boolean] )

Description: Returns rig DAG node (DmeRig) of a created or existing rig and sets the active rig being built. If error, returns None. If a new rig is created, it will be added to the scene.

There must be a selected shot or the function will return None.

If it fails to create the rig or there is already an existing rig and append is False, the function will return None.

BeginRig() cannot be nested if already building a rig; you must call EndRig() first before calling BeginRig() again.

Parameters:

• append (boolean) [ default=False ]: If the rig already exists, only return it if append is True. If append is False, BeginRig() will return None. This allows the caller to choose to add to a rig or not; you wouldn't in the case of rig_biped_simple, but in other cases you might have multiple scripts each adding onto the same rig.

Examples:

# Start the biped rig to which all of the controls and constraints will be added
rig = sfm.BeginRig( "rig_biped_" + animSet.GetName() );
if ( rig == None ):
       return

ClearSelection

ClearSelection()

Description: Clear the current selection, removing all currently selected DAG nodes.

Examples:

sfm.ClearSelection()

CreateAnimationSet

CreateAnimationSet( animsetName, target=object )

Description: Create an animation set for the specified element. Returns vs.movieobjects.CDmeAnimationSet if success, None if error.

Parameters:

• target (object): Element for which animation set is to be created

Examples:

# For some reason it is required to pass target DAG with the use of explicit target=dagObject
animSet = sfm.CreateAnimationSet( "spy", target=DagSpy)

CreateAttachmentHandle

CreateAttachmentHandle( attachmentName )

Description: Create a DAG and associated position transform control for the specified attachment position and it will add to rig if there's a current rig. Returns vs.movieobjects.CDmeDag if success, returns None if no animsetcontext or gamemodel or failed to create attachment handle.

CreateAttachmentHandle() creates a DAG node for an attachment point within a model. Normally, attachment points are used by the game engine to hang hats or place guns or other static props. The SFM has overloaded this capability, allowing the model to be authored with attachment points useful for the SFM, such as for rigging. The model has some named point that is relative to some bone, and this function creates a DAG at the current location of that point. It will put DAG in the rig as a position transform control. The attachment points themselves are fixed in position and not animatable. Creating DAGs for them automatically, rather than just for a script, would imply that they're editable and they would just clutter up the UI.

Examples:

attachmentDag = sfm.CreateAttachmentHandle( "pvt_heel_R" )

CreateDisplaySet

Warning:This method is deprecated and no longer presented in the latest version of SFM

CreateDisplaySet( name )

Description: Create a display set with the specified name. A display set is a grouping of controls that may be toggled between being shown or hidden in the UI. Any one control may only belong to a single display set at one time.

• The DisplaySet name is not an optional argument. Returns DmeControlDisplaySet if success, None if error.

Examples:

# Create a "Gun" display set, add all of the controls within the "w_shotgun" animation set and then hide the display set
sfm.CreateDisplaySet( "Gun" )
sfm.AddToDisplaySet( "Gun", "w_shotgun" )
sfm.HideDisplaySet( "Gun", hide=True )

CreateRigHandle

CreateRigHandle( handleName, [pos=vector], [rot=vector], [group=string], [posControl=boolean], [rotControl=boolean] )

Description: Create a rig handle DAG node. Returns DmeRigHandle if success, None if error. A position and orientation may be specified; if they are not specified, the rig handle will be at the origin. The rig handle is always created in world space. The Parent() command may be used to make it a child of another node. If it's known that the rig handle is going to be constrained for either position or orientation, then there's no reason to create a control or channel. A rig handle that isn't constrained is created that should not be moved, only rotated. The handle can't be moved within the animationSet editor. Constraints can still move it, but the user can't. It's conceivable you could put a rig handle under a ControlGroup like bip_head rather than a proper ControlGroup like Body but probably not the best idea and would probably break something having two DAGsDAGs under that ControlGroup.

Arguments:

• handleName : Name to assign to the new rig handle.

Parameters:

• pos (vector) [ default=[ 0, 0, 0 ] ]: World space position to create the handle at.
• rot (vector) [ default=[ 0, 0, 0 ] ]: World space rotation to assign to the rig handle.
• group (string) : Name of the control group to which the new rig handle should be assigned; if not specified, it will be placed directly under the animation set.
• posControl (boolean) [ default=True ]: If True, CreateRigHandle() will create a position control and channel for the rig handle. If False, then no control or channel will be created.
• rotControl (boolean) [ default=True ]: If True, CreateRigHandle() will create a rotation control and channel for the rig handle. If False, then no control or channel will be created.

Examples:

# Create a rig handle at the origin, and place it in the selection group "rigHandles"
sfm.CreateRigHandle( "newRigHandle", group="rigHandles" )   

# Create a rig handle at the location of the DAG node with the name "someDagNode"
handlePos = sfm.GetPosition( "someDagNode" )
handleRot = sfm.GetRotation( "someDagNode" )
sfm.CreateRigHandle( "newRigHandle", pos=handlePos, rot=handleRot )

EndRig

EndRig()

Description: Ends the definition of the current rig and sets that no rig is currently being built. Only one rig can be under construction (active) at a time.

Examples:

1. End the rig definition

sfm.EndRig()

FindDag

FindDag( dagName )

Description: Find and return the DAG (DmeDag) within the current or specified animation set. Returns None if error or dagName not present. The animation set may be specified in the form "AnimationSetName:DagName" or the just "DagName" may be used to find the DAG in the current animation set.

This is a generic command that provides access to the DAG, allowing access to all of the member functions that are provided by the DAG interface or use for functions that take DAG node objects as arguments.

Examples:

parentDag = sfm.FindDag( parentName )
sfm.GenerateSamples( childName, parent=parentDag )

FirstSelectedDag

FirstSelectedDag()

Description: Command to get the first DAG node in the currently active selection list. Returns DmeDag if success, returns None if error or none present.

Examples:

tmpDag = sfm.FirstSelectedDag()

GenerateSamples

GenerateSamples( [dagNode1], [dagNode2], ... [dagNodeN], [parent=string], [pos=boolean], [rot=boolean], world=boolean] )

Description: Resample the position and orientation of the selected DAG nodes and store in the logs for each node. The command either can be run on the current selection or can create a new temporary selection in line. The parameters allow only position or only rotation samples to be generated. If one or the other is False the existing values for that component will not be modified. If both are False the function will return without taking any action.

Parameters:

• parent (string): If specified the logs will be generated in the space of the specified node instead of in world space.
• pos (boolean) [default=True]: If True, position samples will be generated, if False, position samples will not be generated.
• rot (boolean) [default=True]: If True, rotation samples will be generated, if False, rotation samples will not be generated.
• world (boolean) [default=False]: If True, generate samples in world space ignoring any parent. If False, use local space unless parent specified.

Examples:

sfm.GenerateSamples( "rig_pelvis" )
sfm.GenerateSamples( "rig_hand", parent="rig_pelvis" )
sfm.GenerateSamples( "rig_neck", parent="rig_neck", pos=False, rot=True )

GetCurrentAnimationSet

GetCurrentAnimationSet()

Description: Returns the current animation set (DmeAnimationSet). If error or no current animation set, returns None.

Examples:

animSet = sfm.GetCurrentAnimationSet()

GetCurrentFrame

GetCurrentFrame()

Description: Get the current frame number of the location of the head. The frame number is returned relative to the shot, so that if the frame is at the start of the shot the return value will be 0.

Examples:

frame = sfm.GetCurrentFrame()

GetCurrentRig

GetCurrentRig()

Description: Returns rig DAG node (DmeRig) of the current rig, returns None if error. This is set by BeginRig and cleared by EndRig. There are several SFM utility functions that will do things with the rig while it's active (if active, do one thing; if not, do another). Rather than having to pass the rig into each of the utility functions, they call GetCurrentRig().

Examples:

rig = sfm.GetCurrentRig()
if ( rig != None ) :
     rig.AddElement( element, animSet )

GetCurrentShot

GetCurrentShot()

Description: Returns the current shot (DmeFilmClip) if success. If error or no currently selected shot, returns None.

Examples:

shot = sfm.GetCurrentShot()    # Get the currently selected animation set and shot

GetPosition

GetPosition( [dagNode], [space=string], [refObject=string ] )

Description: Return the position of the specified DAG node in the specified space. Selection may be for more than one dagNode so will return average position. The command may use the current primary selection or specify the DAG node(s) directly in line. Returns vector with x,y,z position if success, None if error.

Parameters:

• space (string) [default="World"]: Specifies the space in which the position of the DAG node should be returned.

"World" : Returns the position of the DAG node in world space.

"Parent" : Returns the position of the DAG node in the space of its parent.

"RefObject" : Returns the position of the DAG node in the space of the specified reference DAG node.

"Object" : Returns the position of the DAG node in Object space. For GetPosition(), this should return 0,0,0 as the position of the transform in its own space.

• refObject (string) : Name of the DAG node to be used with the RefObject space. If space="RefObject" is specified then refObject parameter will be used to determine which DAG node will define the space in which the position will be returned. Unclear what happens if this parameter isn't supplied when required.

Examples:

footPosWorld = sfm.GetPosition( "bip_footR" )
footPosLocal = sfm.GetPosition( "bip_footR", space="Parent" )
footPosModel = sfm.GetPosition( "bip_footR", space="RefObject", refObject="rootTransform" )

GetRotation

GetRotation( [dagNode], [space=string], [refObject=string ] )

Description: Return the rotation of the specified DAG node in the specified space. Selection may be for more than one dagNode so will return average rotation. The command may use the current primary selection or specify the DAG node(s) directly in line. Returns vector of Euler angles if success, None if error.

Parameters:

• space (string) [default="World"]: Specifes the space in which the rotation of the DAG node should be returned.

"World" : Returns the rotation of the DAG node in world space

"Parent" : Returns the rotation of the DAG node in the space of its parent

"RefObject" : Returns the rotation of the DAG node in the space of the specified refrence DAG node

"Object" : Returns the orientation of the DAG node in Object space. For GetRotation(), this should return 0,0,0 as the orientation of the transform in its own space.

• refObject (string) : Name of the DAG node to be used with the RefObject space. If space="RefObject" is specified then refObject parameter will be used to determine which DAG node will define the space in which the rotation will be returned.

Examples:

footRotWorld = sfm.GetRotation( "bip_footR" )
footRotLocal = sfm.GetRotation( "bip_footR", space="Parent" )
footRotModel = sfm.GetRotation( "bip_footR", space="RefObject", refObject="rootTransform" )

HideDisplaySetCommand

Warning:This method is deprecated and no longer presented in the latest version of SFM

HideDisplaySet( displaySetName, [hide=boolean] )

Description: Hide or show the specified display set. This changes the hide attribute of the specified display set so that all of the controls that are in the display set will either be hidden or shown.

Arguments:

• displaySetName: Name of the display set to be hidden or shown.

Parameters:

• hide (boolean) [default=True]: Flag specifying if the group should be hidden (True) or shown (False).

Examples:

sfm.HideDisplaySet( "Gun", hide=True )

sfm.HideDisplaySet( "Gun", hide=False )

IkConstraint

IkConstraint( endTarget, slaveRoot, slaveEnd, [pvTarget=string], [poleVector=vector], [name=string], [group=string], [mo=boolean] )

Description: Create a two-bone IK constraint that orients two bones such that the end of the second bone is as close to the endTarget as possible. There can only be one intervening bone between the slaveRoot and slaveEnd so that the slaveEnd has to be the grandson of the slaveRoot. The command may either operate on the current selection or create a new temporary selection in line. Returns DmeConstraintTarget if success, None if error. The IK solution is a rotation plane model, using a pole vector to define the plane. The pole vector will determine the direction of the bend in the bones if the target is not past the length of the two bones.

Parameters:

• name (string): Name to assign to the new constraint.
• group (string): Name of the control selection group to which the constraint is to be assigned.
• mo (boolean) [ default=False ]: Maintain offset, if True the rotation of the bones will be maintained relative to their current rotation. If False the bones will be re-oriented such that x axis of points down the chain.
• poleVector (vector) [ default=[0, 1, 0] ]: A world space vector defining the pole vector that determines the direction in which the bones will bend.
• pvTarget (string) [ default "" ]: Name of a DAG node to be used to define the pole vector, if specified, this completely overrides the poleVector parameter.

Examples:

# Create a two-bone IK constraint that constrains the two bones connecting the start and end joints.
# If the endTarget is past the length of the two bones, the bones will line up pointing at the endTarget
# with no bend. The rig_knee, as pole vector target, serves as a "pull point" and defines the direction
# the knee will bend in when the endTarget is less than the length of the two bones.
sfm.IKConstraint( "rig_foot", "bip_hipR", "bipFootR", pvTarget="rig_knee", mo=True )

Move

Move( x, y, z, [dagNode1], [dagNode2], ... [dagNodeN], [relative=boolean], [space=string], [refObject=object], [offsetMode=boolean] )

Description: The move command moves the selected objects in the specified space. Movement may be absolute, which sets the position without respect to the original position of the object or relative that moves the object a number of units from its original position.

Note:Object space is subtly different from local space. When you apply the Move() depends on whether you're accounting for the rotation of the object when you apply the translation. In local space, it won't matter what the rotation on the object is; if you say translate it 5 units in x, it's always the same thing even if the object rotation has changed. That's because local space is determined by the parent and has nothing to do with the orientation of the object itself. Object space though changes with orientation changes of the object. In object space, the results of a movement of 5 units in X will depend on the current orientation of the object. If there's no rotation on the object, though, then the two are equivalent.

• Selection may be specified after the coordinate arguments; if no selection is specified, the current selection will be used.

Parameters:

• relative (boolean) [default=False]: This parameter determines if the movement is absolute (False) or relative (True). If not specified the movement will be absolute.
• space (string) [default="World"]: This parameter specifies the space in which the movement will occur. Valid values are:

"World" : Movement occurs in world space

"Parent" : Movement occurs in the space of its current parent

"Object" : Movement occurs in the space of the object

"RefObject" : Movement occurs in the space of the specified reference object

• refObject (string) : This parameter specifies the reference object whose space is to be used in moving the selected objects. This parameter is only used if the space parameter is "RefObject".
• offsetMode (boolean) [default=False]: If True, apply the move as an offset over the time selection. If False, apply as an absolute value.

Examples:

sfm.Move( 0, 0, 0 )
sfm.Move( 10, 0, 0, relative=True )
sfm.Move( 0, 10, 0, "bip_head", relative=True, space="Object" )
sfm.Move( 0, 0, -20, "rig_lookAt", space="RefObject", refObject="bip_head" )

NextSelectedDag

NextSelectedDag()

Description: Command to get the next DAG node in the currently active selection list. Returns DmeDag if success, returns None if error or if none are left.

Examples:

tmpDag = sfm.NextSelectedDag()

OrientConstraint

OrientConstraint( targetDag1, [targetDag2], [targetDagN], slaveDag, [name=string], [group=string], [mo=boolean], [w=float], [controls=boolean] )

Description: Create an orientation constraint that constrains the orientation of the slaveDag to the orientation of the target. The command may either operate on the current selection or create a new temporary selection in line. The slaveDag is always the final Dag argument. Returns DmeConstraintTarget if success, None if error.

Multiple targets may be specified with weights so that the orientation that the slaveDag is constrained to is a weighted average of the target orientations. If the sum total of all OrientConstraint weights is less than 1.0, then it will blend with the existing animation. If over 1.0 it's the same as 1.0 unless there are multiple targets, and in that case, they are all normalized to 1.0 and their weights treated proportionately.

You can only have one orient constraint per slaveDag. Calling OrientConstraint will create a new orient constraint if none are present; otherwise, on repeat calls, it will add a new source target to the list of targets of that constraint with its weight. In the examples below, the weights are split evenly if multiple targets are in a selection. Multiple calls are needed if weights should be different between targets.

If weight control and channel are not created, you won't be able to change the weights outside the Element Viewer. Set control to False if you're creating a constraint where there's only one target so the weight isn't important and you're not interested in animating the weights. If no control or channel, when OrientConstraint is evaluating, there's nothing that will be able to change the weight.

Arguments:

• targetDag1: Name of the DAG node to which the position of the slaveDag is to be constrained. Multiple targets may be specified.
• slaveDag: Name of the DAG node of which the position is to be constrained to final target position.

Parameters:

• name (string): Name to assign to the new constraint and if call creates controls, name is part of what shows up in UI.
• group (string): Name of the control group to which the constraint is to be assigned.
• mo (boolean) [ default=False ]: Maintain offset, if True the slaveDag will maintain its current orientation relative to the current orientation of the target. If False, it will be constrained to the target exactly with no offset.
• w (float) [ default=1.0 ]: Weight to be applied to all of the targets specified. If different weights are required separate commands may be used to add multiple targets with different weights to the same constraint.
• control (boolean) [ default=True ]: If True, create weight controls and channel. If False, weight control and channel not created.

Examples:

# Orient constrain the bip_pelvis to the rig_pelvis, but maintain the current offset
# between the bip_pelvis and the rig pelvis
sfm.OrientConstraint( "rig_pelvis", "bip_pelvis", mo=True )

# Create a handsCenter rig handle and orient constrain it equally between both hands
sfm.CreateRigHandle( "handsCenter" )
sfm.OrientConstraint( "bip_handR", "bip_handL", "handsCenter", mo=False )

# Orient constrain bip_spine_1 to both rig_spine_0 and rig_spine_1, but with more weight on rig_spine_0
sfm.OrientConstraint( "rig_spine_0", "bip_spine_1", mo=True, w="0.75" )
sfm.OrientConstraint( "rig_spine_3", "bip_spine_1", mo=True, w="0.25" )

Parent

Parent( [childDag1], [childDag2], ... [childDagN], [parentDag], [world=boolean], [relative=boolean], [updateLogs=boolean] )

Description: Make the primary selection the parent of all other selected DAG nodes. The command may operate on the current selection or may create a new temporary selection. The last item in the selection is the primary selection that the other DAG nodes will be made children of.

Parameters:

• world (boolean) [default=False]: If specified as True, all of the nodes will be parented to the world instead of to the primary selection.
• relative (boolean) [default=False]: If True, the local space position of the child will be maintained such that it is in the sample location relative to its new parent as it was relative to its previous parent. If False (default), the local space position of the DAG node will be modified so that it will maintain its location in world space.
• updateLogs (boolean) [default=True]: If True, updates logs; if False, doesn't.

Examples:

sfm.Parent( "childNode1", "parentNode" );
sfm.Parent( "childNode1", "childNode2", "parentNode", relative=True );
sfm.Parent( "childNode1", "childNode2", world=True );

ParentConstraint

ParentConstraint( targetDag1, [targetDag2], [targetDagN], slaveDag, [name=string], [group=string], [mo=boolean], [w=float], [controls=boolean] )

Description: Create a parent constraint that makes the slaveDag behave as if it were a child of the target DAG. The slaveDag is always the final Dag argument. Returns DmeConstraintTarget if success, None if error.

The command may either operate on the current selection or create a new temporary selection in line. Multiple targets may be specified with weights to create a virtual parent target whose position and orientation are a weighted average of all of the targets. If the sum total of all ParentConstraint weights is less than 1.0, then it will blend with the existing animation. If over 1.0 it's the same as 1.0 unless there are multiple targets and in that case, they are all normalized to 1.0 and their weights treated proportionately.

You can only have one parent constraint per slaveDag. When calling ParentConstraint, it will create a new parent constraint if none present otherwise on repeat calls it will add a new source target to the list of targets of that constraint with its weight.

If weight control and channel are not created, you won't be able to change the weights outside the Element Viewer. Set control to False if you're creating a constraint where there's only one target so the weight isn't important and you're not interested in animating the weights. If no control or channel, when ParentConstraint is evaluating, there's nothing that will be able to change the weight.

Arguments:

• targetDag1: Name of the DAG node to which the slaveDag is to be constrained. Multiple targets may be specified.
• slaveDag: Name of the DAG node of which to be constrained.

Parameters:

• name (string): Name to assign to the new constraint and if call creates controls, name is part of what shows up in UI.
• group (string): Name of the control group to which the constraint is to be assigned.
• mo (boolean) [ default=False ]: Maintain offset, if True the slaveDag will maintain its current position and orientation relative to the current location of the target. If False, it will be constrained to the target exactly with no offset.
• w (float) [ default=1.0 ]: Weight to be applied to all of the targets specified. If different weights are required, separate commands may be used to add multiple targets with different weights to the same constraint.
• control (boolean) [ default=True ]: If True, create weight controls and channel. If False, weight control and channel are not created.

Examples:

# Create a rig hat handle and make it a child of the rig_root, but parent constrain it to the head
sfm.CreateRigHandle( "rig_hat" )
sfm.Parent( "rig_hat", "rig_root" )
sfm.ParentConstraint( "rig_head", "rig_hat" )

PointConstraint

PointConstraint( targetDag1, [targetDag2], [targetDagN], slaveDag, [name=string], [group=string], [mo=boolean], [w=float], [controls=boolean] )

Description: Create a point constraint that constrains the position of the slaveDag to the position of the target. The command may either operate on the current selection or create a new temporary selection in line. The slaveDag is always the final DAG argument. Returns DmeConstraintTarget if success, None if error.

Multiple targets may be specified with weights so that the position the slaveDag is constrained to is a weighted average of the target locations. If the sum total of all PointConstraint weights is less than 1.0, then it will blend with the existing animation. If over 1.0 it's the same as 1.0 unless there are multiple targets, and in that case, they are all normalized to 1.0 and their weights treated proportionately.

You can only have one point constraint per slaveDag. When calling PointConstraint, it will create a new point constraint if none are present; otherwise, on repeat calls, it will add a new source target to the list of targets of that constraint with its weight. In the examples below, the weights are split evenly if multiple targets are in a selection. Multiple calls are needed if weights should be different between targets.

If weight control and channel are not created, you won't be able to change the weights outside the Element Viewer. Set control to False if you're creating a constraint where there's only one target so the weight isn't important and you're not interested in animating the weights. If no control or channel, when PointConstraint is evaluating, there's nothing that will be able to change the weight.

Arguments:

• targetDag1: Name of the DAG node to which the position of the slaveDag is to be constrained. Multiple targets may be specified.
• slaveDag: Name of the DAG node of which the position is to be constrained to final target position.

Parameters:

• name (string): Name to assign to the new constraint, and if the call creates controls, name is part of what shows up in UI.
• group (string): Name of the control group to which the constraint is to be assigned.
• mo (boolean) [ default=False ]: Maintain offset; if True, the slaveDag will maintain its current position relative to the current location of the target. If False, it will be constrained to the target exactly with no offset.
• w (float) [ default=1.0 ]: Weight to be applied to all of the targets specified. If different weights are required separate commands may be used to add multiple targets with different weights to the same constraint.
• control (boolean) [ default=True ]: If True, create weight controls and channel. If False, weight control and channel are not created.

Examples:

# Point constrain the bip_pelvis to the rig_pelvis, but maintain the current offset
# between the bip_pelvis and the rig pelvis
sfm.PointConstraint( "rig_pelvis", "bip_pelvis", mo=True )

# Create a handsCenter rig handle and constrain it half way between each hand
sfm.CreateRigHandle( "handsCenter" )
sfm.PointConstraint( "bip_handR", "bip_handL", "handsCenter", mo=False )

# Point constrain bip_spine_1 part way between rig_spine_0 and rig_spine_1, but closer to 0 than 1
sfm.PointConstraint( "rig_spine_0", "bip_spine_1", mo=False, w="0.75" )
sfm.PointConstraint( "rig_spine_3", "bip_spine_1", mo=False, w="0.25" )

PopSelection

PopSelection()

Description: Pop the current selection off of the stack and restore the previously pushed selection.

PushSelection

PushSelection()

Description: Push the current selection on to the stack so that it may be restored later. Use PushSelection() if you want to do an operation that requires a selection yet you need to preserve your original selection. This can come up if you are running script that makes use of the selection made by the animator in the UI but you need to do interim operations that require different selection and you do not want to lose the original UI selection.

Examples:

sfm.PushSelection()
sfm.Select( "rig_root", "rig_pelvis", "rig_spine_0", "rig_spine_3" )
sfm.RemoveConstraints()
sfm.PopSelection()

PrintDagOperators

PrintDagOperators( [dagNode1], [dagNode2] ... [dagNodeN], [local=boolean] )

Description: Prints an ordered list of operators that are needed to evaluate a selected DAG, in the order that they are going to be evaluated. The command may either operate on the current selection or create a new temporary selection in line. This is a debugging routine useful when writing new operators.

Parameters:

• local (boolean) [default=False]: If True, print locals only.

RemoveConstraints

RemoveConstraints( [dagNode1], [dagNode2] ... [dagNodeN] )

Description: Remove all constraints from the selected DAG nodes. The command may either operate on the current selection or create a new temporary selection in line.

Examples:

sfm.ClearSelection()
sfm.Select( "rig_root", "rig_pelvis", "rig_spine_0", "rig_spine_3" )
sfm.RemoveConstraints()

sfm.RemoveConstraints( "rig_root", "rig_pelvis", "rig_spine_0", "rig_spine_3" )

Rotate

Rotate( x, y, z, [dagNode1], [dagNode2], ... [dagNodeN], [relative=boolean], [space=string], [refObject=object] )

[refObject=object], [offsetMode=boolean] )

Description: The rotate command rotates the selected DAG nodes in the specified space. Rotation may be absolute, which sets the rotation of the DAG nodes without respect to the initial rotation, or relative that will rotate the DAG nodes the specified amount from their current rotation.

• Selection may be specified after the coordinate arguments, if no selection is specified the current selection will be used.

Parameters:

• relative (boolean) [default=False]: This parameter determines if the rotation is absolute (False) or relative (True).
• space (string) [default="World"]: This parameter specifies the space in which the movement will occur. Valid values are:

"World" : Rotation occurs in world space

"Parent" : Rotation occurs in the space of its current parent

"Object" : Rotation occurs in the space of the object

"RefObject" : Rotation occurs in the space of the specified reference object

• refObject (string) : This parameter specifies the reference object whose space is to be used in moving the selected objects. This parameter is only used if the space parameter is "RefObject"
• offsetMode (boolean) [default=False]: If True, apply the move as an offset over the time selection. If False, apply as an absolute value.

Examples:

sfm.Rotate( 0, 0, 0 )
sfm.Rotate( 90, 0, 0, relative=True )
sfm.Rotate( 0, 180, 0, "bip_head", relative=True, space="Object" )

Select

Select( selectionGroup1, [selectionGroup2], ... [selectionGroupN], [remove=boolean], [toggle=boolean], [error=boolean] )

Description: The select command is used to select DAG nodes. This can be done in a number of ways. SelectionGroup can be the name of an animationSet, ControlGroup or individual control to be selected and Select() adds the specific DAG node or all DAG nodes that are members of the animationSet or ControlGroup to the selection.

• At least one SelectionGroup must be specified. Names of selection groups are simply the name of the group shown in the animation set editor. If a selection outside the current animation set is required the name of the animation set may be prefixed to the selection group name using the format: AnimationSet:SelectionGroup.
• The name of an animation set may also be specified, resulting in selecting all of the controls and DAG nodes within that animation set.
• Select() looks for its arguments in the control group hierarchy of the animationSet.
• There might be some confusion in that "controls", such as "bip_pelvis" in the control group hierarchy are themselves control groups like "Body". Select() will know that a control group in the control group hierarchy is associated with a DAG if, in its list of controls, it has a TransformControl that references a Transform that is owned by a DAG and it will know it can select that DAG. It's possible to see this distinction between control groups in the Element Viewer by walking thru the DAG hierarchy.

Parameters:

• remove (boolean) [default=False] : If True, remove all the DAGsDAGs from the selection otherwise add to selection.
• toggle (boolean) [default=False] : Toggle ignored if remove is True. If toggle is True then remove DAGs from selection if present; otherwise, add if not in selection. Not a common usage.
• error (boolean) [default=True] : If True, generate a ScriptError if the DAGsDAGs named do not exist. If False, ignore even if the specified names do not exist.

Examples:

sfm.Select( "rig_root" )
sfm.Select( "Body", "Legs", "Arms", "Root", "Fingers", "Other" )
sfm.Select( "w_shotgun:rootTransform" )

SelectAll

SelectAll( [ animationsetName ] )

Description: Select all of the DAG nodes in the currently active animation set if no animation set specified. If an animation set is specified, then select all the DAG nodes of that animation set.

Examples:

sfm.SelectAll()
sfm.SelectAll( "scout" )

SetCurrentFrame

SetCurrentFrame( frameNumber )

Description: Set the current time (i.e., playhead position) for script operation to the specified frame relative to the start of the shot. 0 will always be the first frame of the shot, regardless of the starting frame of the shot in the sequence. Unclear what happens if frame number is negative or after shot.

Examples:

sfm.SetCurrentFrame( 35 )

SelectDag

SelectDag( DmeDag )

Description: Adds the specified DAG node to the current selection. Selection is just a list of DAGs. SelectDag doesn't really care what specific type of DAG it is.

This function is used in conjunction with other functions that operate on the selection. Many other commands operate on the selection; for example, constraints take the first thing in the selection and constrain the other N things in the selection. Similar to Select(), which takes the dagName and does the find and add for you. SelectDag() just provides another entry to use if you have a DAG rather than a DAG name.

Examples:

sfm.SelectDag( child )

SetDefault

SetDefault( dagNode, [dagNode1], [dagNodeN], [pos=boolean], [rot=boolean] )

Description: Set the default position and orientation of the currently selected DAG nodes to the current position and rotation. The command may either use the existing selection or create a temporary selection in line. The default position and rotations are the values that are used in the reference pose, so this command may be used to initialize or modify the reference pose. Note, however, that any transforms that correspond to a bone in a model will have their default position updated from the model when using the reference pose so it can't be overridden. Used mainly to set the default position and orientation for newly created DagNodes that aren't a part of the model, e.g., rig handles especially.

Parameters:

• pos (boolean) [default=True] : If True the default position will be updated, if False the default position will not be changed.
• rot (boolean) [default=True] : If True the default rotation will be updated, if False the default rotation will not be changed.

Examples:

sfm.SetDefault ( "rig_root", "rig_pelvis", "rig_spine_0", "rig_spine_3" )

SetOperationMode

SetOperationMode( operationMode )

Description: Sets the current channel operation mode. The channel operation mode corresponds to the channel mode buttons in the SFM interface. The modes are play, record, and pass through. The channel mode controls how data in moved from the channel source to the channel target. Error if an invalid operation mode is passed in.

Arguments:

• operationMode (string): Name specifying the operation mode to which all of the channels in the currently selected animation set group are to be set.

"Play" : The channel target is driven by the values stored in the channel logs. Play mode is used when the values of the logs need to be evaluated at a given time.

"Record" : The values in the channel source will be recorded into the channel log and applied to the channel target. Record mode should be used when the results of operations such as move and rotate should persist after the script has completed.

"Pass" : The values in the channel source will be applied to the channel target without being recorded in the log. This is the default mode. Pass through mode should be used when the results of move and rotate should only be temporary and should not be saved after the script completes.

"Off" : No data will be transferred between the channel source and target, behaves as if the channel does not exist. The off mode is rarely used.

Examples:

sfm.SetOperationMode( "Pass" )
sfm.SetOperationMode( "Record" )
sfm.SetOperationMode( "Play" )

SetReferencePose

SetReferencePose( [dagNode1], [dagNode2] ... [dagNodeN] )

Description: Return the currently selected DAG nodes to their reference pose position. The command may either operate on the current selection or create a new temporary selection in line.

Examples:

sfm.ClearSelection()
sfm.Select( "bip_pelvis", "bip_spine_0", "bip_spine_1", "bip_spine_2", "bip_spine_3" )
sfm.SetReferencePose()

sfm.SetReferencePose( "bip_pelvis", "bip_spine_0", "bip_spine_1", "bip_spine_2", "bip_spine_3" )

TimeSelectFrames

Warning:This method is deprecated and no longer presented in the latest version of SFM

TimeSelectFrames( leftFalloffFrame, leftHoldFrame, rightHoldFrame, rightFalloffTime, [interpIn=string], [interpOut=string] )

Description: Specify a new time selection with frame numbers relative to the shot. All time arguments required. Changes time selection if success. While a frame is always a fixed amount of time, it depends on the frame rate of the system that could change.

Parameters:

• interpIn (string) [default="linear"]: Specifies the in (left) falloff region interpolation type of the time selection.
• interpOut (string) [default="linear"]: Specifies the out (right) falloff region interpolation type of the time selection.

"Linear" : Linear interpolation mode, values are interpolated without any special weighting

"EaseIn" : Values are interpolated such that the transition at the in point is smooth

"EaseOut" : Values are interpolated such that the transition at the out point is smooth

"EaseInOut" : Values are interpolated such that both the in and out transitions are smooth

Examples:

sfm.TimeSelectFrames( 0, 10, 20, 30 )
sfm.TimeSelectFrames( 0, 10, 20, 30, interpIn="EaseIn", interpOut="EaseOut" )

TimeSelectShot

Warning:This method is deprecated and no longer presented in the latest version of SFM

TimeSelectShot( leftFalloffTime, leftHoldTime, rightHoldTime, rightFalloffTime, [interpIn=string], [interpOut=string] )

Description: Specify a new time selection relative to the active shot and changes the time selection if successful.

Note:Time selection is only within the context of the script; time selection reverts after script is finished. Times are all specified as percentages of the way through the shot on a scale of 0.0-1.0. 0 is used as default time if a time argument isn't supplied. If all parameters are 0, then select all time.

The percentages are relative to the length of the current shot that may or may not have a lot of channel information before and after it. When you're recording a shot, there are always a few seconds before and after and there could be more or less with shot editing. The code doesn't appear to check if "times" are outside these bounds.

Parameters:

• interpIn (string) [default="linear"]: Specifies the in (left) falloff region interpolation type of the time selection.
• interpOut (string) [default="linear"]: Specifies the out (right) falloff region interpolation type of the time selection.

"Linear" : Linear interpolation mode, values are interpolated without any special weighting

"EaseIn" : Values are interpolated such that the transition at the in point is smooth

"EaseOut" : Values are interpolated such that the transition at the out point is smooth

"EaseInOut" : Values are interpolated such that both the in and out transitions are smooth

Examples:

sfm.TimeSelectShot( 0.5, 0.6, 0.7, 0.8 )
sfm.TimeSelectShot( 0.5, 0.6, 0.7, 0.8, interpIn="Linear", interpOut="EaseInOut" )
# Select all of time
sfm.TimeSelectShot()

UsingAnimationSet

UsingAnimationSet( animationSetName )

Description: Make the specified animation set the active animation set. The active animation set is the animation set that all selection operations will assume as the base animation set if an animation set is not explicitly specified.

• The name of the animation set is specified as it is shown in the Animation Set Editor.
• This command isn't really used right now. Currently returns None always.

Examples:

sfm.UsingAnimationSet( "w_shotgun" )

sfmUtils.py summary

In addition, there are a number of script routines provided by sfmUtils.py set up to support scripting. Look at the code for documentation on parameters and function.

You can find sfmUtils.py here:

SourceFilmmaker\game\sdktools\python\global\lib\site-packages\sfm

See also

• Making custom rigs