AM Tools 1.05
Functions | Variables
Package amTools.unity.rigs.expressions

Add custom attributes to an object in the scene to describe the scene's animation expressions as C# for the Unity APIs. More...

Functions

def exportExpressions
 Add user properties for the expression contents.
def findAttributeHolder
 Return an object in the scene to hold user properties.
def findExpressionReferences
 Find all references connected to expression nodes.
def getReferenceDataTypeDict
 Return a dictionary whose keys are extant reference names and values are data types.
def getReferenceConflictDict
 Return a dictionary whose keys are extant reference names and values are conflict-resolved names.
def addReferenceFieldUserProperties
 Add user properties for each of the references.
def addReferenceDeclarationUserProperties
 Add user properties for each reference field declaration.
def addJointOrientDeclarationUserProperties
 Add user properties for each jointOrient variable declaration, and return a dictionary mapping each joint to its prerotation variable.
def addMethodBodyUserProperty
 Add a user property for each method body.
def expressionAsCSharpFunction
 Return the expression node's contents as C# for Unity.
def getReferenceFieldDict
 Collect all references and get their types.
def getVariableTypeDict
 Collect all variable types and their types into a dictionary of varName:varType pairs.
def convertMathCommands
 Convert on-demand math commands inside of backticks into corresponding Unity API calls.
def correctAssignments
 Correct assignments to integer and Vector3 variables and fields.
def correctReferenceFieldSyntax
 Correct reference fields to match their corresponding Unity field name.
def divToMult
 Return copy of expression with division specified in MatchObject converted to multiplication.
def consolidateLiteralBlocks
 Conlidate blocks of literal expressions.
def correctFloatLiteralSyntax
 Correct float literal syntax for C# by appending f suffix.

Variables

list kReservedKeywords
 a non-exhaustive list of reserved keywords to prevent variable and reference naming conflicts
list kSupportedReferenceTypes
 a list of reference types that are supported in expressions
list kSupportedVariableTypes = [u'float', u'int', u'string']
 a list of MEL variable types that are supported
string kCmdArgRE = '\s+[$\w\d.]+'
 a search pattern for a command argument
dictionary kMathCommandRegExps
 a dictionary to match a regular expression to a particular command
dictionary kMathCommandToUnity
 a dictionary to map a supported on-demand command to a Unity API method
dictionary kMathCommandArgOrder
 a dictionary to reorder arguments in a command for the corresponding Unity API method
dictionary kTransformAttributeAsUnityMember
 a dictionary to map Maya attributes to corresponding fields on Unity Transform objects
dictionary kExposeTransformAttributeAsUnityMember
 a dictionary to map Maya attributes to corresponding fields on Unity ExposeTransform objects
dictionary kConstraintAttributeAsUnityMember
 a dictionary to map Maya attributes to corresponding fields on Unity MayaConstraint objects
dictionary kAttributeDictionaries
 a dictionary mapping reference type to its attribute dictionary
dictionary kRotateOrderMapping
 a dictionary of possible rotation order values for EulerRotationOrder in Unity QuaternionHelpers

Detailed Description

Add custom attributes to an object in the scene to describe the scene's animation expressions as C# for the Unity APIs.

These user properties are stored in a way that they are to be parsed by Unity's AssetPostprocessor in order to transport a rig into Unity for evaluation at run-time.

Requirements: Unity Pro with ImportMayaRigs.cs editor script and all its dependencies.

Known Limitations:
  • All comments are stripped
  • The list of reserved keywords is not exhaustive
  • Only some node types are supported; see kSupportedReferenceTypes
  • Only basic math commands are supported on-demand inside of back-tics (see kMathCommandToUnity); all attribute values must be stored in variables first in order to work with math commands e.g.: $ty = object.translateY; $sqrtTy = `sqrt $ty`;
  • No syntax correction for bad ternary expressions such as e.g.: $foo=6.0+false?1.0:2.0; // this screws up in Maya anyway
  • No support for objects controlled by both an expression and an animation curve: e.g., pairBlend nodes connected to an expression
  • No support yet for changing Euler rotation order on the fly
  • BlendShape weights must have an alias (e.g., bs.target, not bs.weight[n])
  • Euler angles can be set to any value, but only decompose in the range [-180,180] in Unity; this process is not cheap, so consider instead using a more efficient alternative such as am_exposeTransform.angle to get angles
  • While jointOrient is supported, other pretransformations (as when freezing translation channels on a transform node) are not supported
  • No concerted effort has been made to ensure proper execution order of multiple expression nodes
  • No support for namespaces or references; your source model (which will have expressions on it in Unity) should not use them
  • No support yet for building code from a node network
  • No support yet for arrays and loops

Creation Info:

Donations: http://adammechtley.com/donations/

License: The MIT License

Copyright (c) 2011 Adam Mechtley (http://adammechtley.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Function Documentation

def amTools.unity.rigs.expressions.addJointOrientDeclarationUserProperties (   attributeHolder,
  refTypeDict,
  conflictDict 
)

Add user properties for each jointOrient variable declaration, and return a dictionary mapping each joint to its prerotation variable.

Parameters:
attributeHolderthe object in the scene that will store all custom attributes for expressions
refTypeDicta dictionary storing the Unity type for each reference in the list
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
def amTools.unity.rigs.expressions.addMethodBodyUserProperty (   attributeHolder,
  expressionNode,
  conflictDict,
  refTypeDict,
  jointOrientVars 
)

Add a user property for each method body.

Parameters:
attributeHolderthe object in the scene that will store all custom attributes for expressions
expressionNodethe expression node to translate into C#
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
refTypeDicta dictionary storing the Unity type for each reference in the list
jointOrientVarsa dictionary mapping joint names to their prerotation Quaternion variables
def amTools.unity.rigs.expressions.addReferenceDeclarationUserProperties (   attributeHolder,
  refTypeDict,
  conflictDict 
)

Add user properties for each reference field declaration.

Parameters:
attributeHolderthe object in the scene that will store all custom attributes for expressions
refTypeDicta dictionary storing the Unity type for each reference in the list
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
def amTools.unity.rigs.expressions.addReferenceFieldUserProperties (   attributeHolder,
  conflictDict 
)

Add user properties for each of the references.

Parameters:
attributeHolderthe object in the scene that will store all custom attributes for expressions
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
def amTools.unity.rigs.expressions.consolidateLiteralBlocks (   expression,
  conflictDict,
  referenceFieldDict,
  variableTypeDict 
)

Conlidate blocks of literal expressions.

Parameters:
expressionthe contents of the expression node at this point in the translation process
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
referenceFieldDicta dictionary mapping Maya attributes names to C# field types
variableTypeDicta dictionary mapping variable names to their types
def amTools.unity.rigs.expressions.convertMathCommands (   expression)

Convert on-demand math commands inside of backticks into corresponding Unity API calls.

Parameters:
expressionthe contents of the expression node at this point in the translation process
def amTools.unity.rigs.expressions.correctAssignments (   expression,
  conflictDict,
  refTypeDict,
  referenceFieldDict,
  variableTypeDict,
  jointOrientVars 
)

Correct assignments to integer and Vector3 variables and fields.

Parameters:
expressionthe contents of the expression node at this point in the translation process
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
refTypeDicta dictionary storing the Unity type for each reference in the list
referenceFieldDicta dictionary mapping Maya attributes names to C# field types
variableTypeDicta dictionary mapping variable names to their types
jointOrientVarsa dictionary mapping joint names to their prerotation Quaternion variables
def amTools.unity.rigs.expressions.correctFloatLiteralSyntax (   expression)

Correct float literal syntax for C# by appending f suffix.

Parameters:
expressionthe contents of the expression node at this point in the translation process
def amTools.unity.rigs.expressions.correctReferenceFieldSyntax (   expression,
  conflictDict,
  referenceTypeDict 
)

Correct reference fields to match their corresponding Unity field name.

Parameters:
expressionthe contents of the expression node at this point in the translation process
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
referenceTypeDicta dictionary storing the Unity type for each reference in the list
def amTools.unity.rigs.expressions.divToMult (   division,
  expression 
)

Return copy of expression with division specified in MatchObject converted to multiplication.

Parameters:
divisiona MatchObject corresponding to a division operation in expression
expressionthe contents of the expression node at this point in the translation process
def amTools.unity.rigs.expressions.exportExpressions ( )

Add user properties for the expression contents.

def amTools.unity.rigs.expressions.expressionAsCSharpFunction (   expressionNode,
  conflictDict,
  refTypeDict,
  jointOrientVars 
)

Return the expression node's contents as C# for Unity.

Parameters:
expressionNodethe expression node to translate into C#
conflictDicta dictionary mapping Maya reference names to conflict-resolved alternatives
refTypeDicta dictionary storing the Unity type for each reference in the list
jointOrientVarsa dictionary mapping joint names to their prerotation Quaternion variables
def amTools.unity.rigs.expressions.findAttributeHolder ( )

Return an object in the scene to hold user properties.

def amTools.unity.rigs.expressions.findExpressionReferences ( )

Find all references connected to expression nodes.

def amTools.unity.rigs.expressions.getReferenceConflictDict (   referenceList,
  refTypeDict 
)

Return a dictionary whose keys are extant reference names and values are conflict-resolved names.

Parameters:
referenceLista list of all objects connected to expression nodes
refTypeDicta dictionary storing the Unity type for each reference in the list
def amTools.unity.rigs.expressions.getReferenceDataTypeDict (   referenceList)

Return a dictionary whose keys are extant reference names and values are data types.

Parameters:
referenceLista list of all objects connected to expression nodes
def amTools.unity.rigs.expressions.getReferenceFieldDict (   expressionNode)

Collect all references and get their types.

Parameters:
expressionNodethe expression node to translate into C#
def amTools.unity.rigs.expressions.getVariableTypeDict (   expression,
  referenceFieldDict 
)

Collect all variable types and their types into a dictionary of varName:varType pairs.

Parameters:
expressionthe contents of the expression node at this point in the translation process
referenceFieldDicta dictionary mapping Maya attributes names to C# field types

Variable Documentation

Initial value:
00001 {
00002         'ExposeTransform':kExposeTransformAttributeAsUnityMember,
00003         'AimConstraint':kConstraintAttributeAsUnityMember,
00004         'OrientConstraint':kConstraintAttributeAsUnityMember,
00005         'PointConstraint':kConstraintAttributeAsUnityMember,
00006         'Transform':kTransformAttributeAsUnityMember
00007         }

a dictionary mapping reference type to its attribute dictionary

a search pattern for a command argument

Initial value:
00001 {
00002         u'offsetX':u'offset.x',
00003         u'offsetY':u'offset.y',
00004         u'offsetZ':u'offset.z'
00005         }

a dictionary to map Maya attributes to corresponding fields on Unity MayaConstraint objects

Initial value:
00001 {
00002         u'eulerOutputRotateOrder' : u'rotateOrder',
00003         u'rotateOrder' : u'rotateOrder',
00004         u'nomalizeAxes': u'nomalizeAxes',
00005         u'nomalize': u'nomalizeAxes',
00006         u'objectAxis': u'objectAxis',
00007         u'axis': u'objectAxis',
00008         u'referenceAxis': u'referenceAxis',
00009         u'refAxis': u'referenceAxis',
00010         u'position0': u'position.x',
00011         u'position1': u'position.y',
00012         u'position2': u'position.z',
00013         u'distance': u'distance',
00014         u'eulerRotation0': u'rotation.x',
00015         u'eulerRotation1': u'rotation.y',
00016         u'eulerRotation2': u'rotation.z',
00017         u'dotProduct': u'dot',
00018         u'dot': u'dot',
00019         u'angle': u'angle',
00020         u'dotToTarget': u'dotToTarget',
00021         u'dotTo': u'dotToTarget',
00022         u'angleToTarget': u'angleToTarget',
00023         u'angleTo': u'angleToTarget'
00024         }

a dictionary to map Maya attributes to corresponding fields on Unity ExposeTransform objects

Initial value:
00001 {
00002         'abs':[0],
00003         'ceil':[0],
00004         'clamp':[2,0,1], # clamp min max value : Mathf.Clamp(value, min, max)
00005         'cos':[0], 'acos':[0], 'cosd':[0], 'acosd':[0],
00006         'deg_to_rad':[0],
00007         'equivalent':[0,1],
00008         'equivalentTol':[0,1,2],
00009         'exp':[0],
00010         'floor':[0],
00011         'hypot':[0,1],
00012         'linstep':[0,1,2,1,0],  # linstep min max val : Mathf.Lerp(min, max, val/(max-min)) 
00013         'log':[0],
00014         'log1p':[0],
00015         'log10':[0],
00016         'max':[0,1],
00017         'min':[0,1],
00018         'pow':[0,1],
00019         'rad_to_deg':[0],
00020         'rand':[0,1],
00021         'sign':[0],
00022         'sin':[0], 'asin':[0], 'sind':[0], 'asind':[0],
00023         'smoothstep':[0,1,2,1,0], # smoothstep min max val : Mathf.SmoothStep(min, max, val/(max-min))
00024         'sqrt':[0],
00025         'tan':[0], 'atan':[0], 'atan2':[0], 'tand':[0], 'atand':[0], 'atan2d':[0],
00026         'trunc':[0]
00027         }

a dictionary to reorder arguments in a command for the corresponding Unity API method

Initial value:
00001 {
00002         'abs%s'%kCmdArgRE:'abs',
00003         'ceil%s'%kCmdArgRE:'ceil',
00004         'clamp%s%s%s'%(kCmdArgRE,kCmdArgRE,kCmdArgRE):'clamp',
00005         'cos%s'%kCmdArgRE:'cos', 'acos%s'%kCmdArgRE:'acos', 'cosd%s'%kCmdArgRE:'cosd', 'acosd%s'%kCmdArgRE:'acosd',
00006         'deg_to_rad%s'%kCmdArgRE:'deg_to_rad',
00007         'equivalent%s%s'%(kCmdArgRE,kCmdArgRE):'equivalent',
00008         'equivalentTol%s%s%s'%(kCmdArgRE,kCmdArgRE,kCmdArgRE):'equivalentTol',
00009         'exp%s'%kCmdArgRE:'exp',
00010         'floor%s'%kCmdArgRE:'floor',
00011         'hypot%s%s'%(kCmdArgRE,kCmdArgRE):'hypot',
00012         'linstep%s%s%s'%(kCmdArgRE,kCmdArgRE,kCmdArgRE):'linstep',
00013         'log%s'%kCmdArgRE:'log',
00014         'log1p%s'%kCmdArgRE:'log1p',
00015         'log10%s'%kCmdArgRE:'log10',
00016         'max%s%s'%(kCmdArgRE,kCmdArgRE):'max',
00017         'min%s%s'%(kCmdArgRE,kCmdArgRE):'min',
00018         'pow%s%s'%(kCmdArgRE,kCmdArgRE):'pow',
00019         'rad_to_deg%s'%kCmdArgRE:'rad_to_deg',
00020         'rand%s%s'%(kCmdArgRE,kCmdArgRE):'rand',
00021         'sign%s'%kCmdArgRE:'sign',
00022         'sin%s'%kCmdArgRE:'sin', 'asin%s'%kCmdArgRE:'asin', 'sind%s'%kCmdArgRE:'sind', 'asind%s'%kCmdArgRE:'asind',
00023         'smoothstep%s%s%s'%(kCmdArgRE,kCmdArgRE,kCmdArgRE):'smoothstep',
00024         'sqrt%s'%kCmdArgRE:'sqrt',
00025         'tan%s'%kCmdArgRE:'tan', 'atan2%s'%kCmdArgRE:'atan2', 'tand%s'%kCmdArgRE:'tand', 'atand%s'%kCmdArgRE:'atand', 'atan2d%s'%kCmdArgRE:'atan2d',
00026         'trunc%s'%kCmdArgRE:'trunc'
00027         }

a dictionary to match a regular expression to a particular command

Initial value:
00001 {
00002         'abs':'Mathf.Abs(%s)',
00003         'ceil':'Mathf.Ceil(%s)',
00004         'clamp':'Mathf.Clamp(%s, %s, %s)',
00005         'cos':'Mathf.Cos(%s)', 'acos':'Mathf.Acos(%s)', 'cosd':'Mathf.Cos(Mathf.Deg2Rad*%s)', 'acosd':'Mathf.Rad2Deg*Mathf.Acos(%s)',
00006         'deg_to_rad':'Mathf.Deg2Rad*%s',
00007         'equivalent':'Mathf.Approximately(%s, %s)',
00008         'equivalentTol':'(%s-%s < %s)',
00009         'exp':'Mathf.Exp(%s)',
00010         'floor':'Mathf.Floor(%s)',
00011         'hypot':'new Vector2(%s,%s).magnitude',
00012         'linstep':'Mathf.Lerp(%s,%s,%s/(%s-%s))',
00013         'log':'Mathf.Log(%s)',
00014         'log1p':'Mathf.Log(1f+%s)',
00015         'log10':'Mathf.Log10(%s)',
00016         'max':'Mathf.Max(%s,%s)',
00017         'min':'Mathf.Min(%s,%s)',
00018         'pow':'Mathf.Pow(%s,%s)',
00019         'rad_to_deg':'Mathf.Rad2Deg*%s',
00020         'rand':'Random.Range(%s,%s)',
00021         'sign':'Mathf.Sign(%s)',
00022         'sin':'Mathf.Sin(%s)', 'asin':'Mathf.Asin(%s)', 'sind':'Mathf.Sin(Mathf.Deg2Rad*%s)', 'asind':'Mathf.Rad2Deg*Mathf.Asin(%s)',
00023         'smoothstep':'Mathf.SmoothStep(%s,%s,%s/(%s-%s))',
00024         'sqrt':'Mathf.Sqrt(%s)',
00025         'tan':'Mathf.Tan(%s)', 'atan2':'Mathf.Atan2(%s)', 'tand':'Mathf.Tan(Mathf.Deg2Rad*%s)', 'atand':'Mathf.Rad2Deg*Mathf.Atan(%s)', 'atan2d':'Mathf.Rad2Deg*Mathf.Atan2(%s)',
00026         'trunc':'(float)((int)(%s))'
00027         }

a dictionary to map a supported on-demand command to a Unity API method

Initial value:
00001 [
00002         u'bool', u'float', u'int', u'string', u'short', u'long', u'double', u'char'
00003         u'Quaternion', u'Transform', u'Vector2', u'Vector3', u'Vector4',
00004         u'UnityEngine', u'UnityEditor', u'System', u'Mathf', u'Debug',
00005         u'CharacterController', u'Collider', u'BoxCollider', u'CapsuleCollider', u'SphereCollider', u'Rigidbody',
00006         u'FloatMatrix', u'QuaternionHelpers', u'VectorHelpers', u'EulerRotationOrder',
00007         u'BlendShape',
00008         u'MayaNode',
00009         u'AimConstraint', u'OrientConstraint', u'PointConstraint',
00010         u'ExposeTransform', u'ShoulderConstraint', u'HipConstraint',
00011         u'useGUILayout', u'enabled', u'transform', u'rigidbody', u'camera', u'light', u'animation', u'constantForce', u'renderer', u'audio', u'guiText', u'networkView', u'guiTexture', u'collider', u'hingeJoint', u'particleEmitter', u'gameObject', u'tag', u'name', u'hideFlags',
00012         u'importScale', u'oneOverImportScale', u'isInvokedExternally', u'upstreamDependencies', u'localPosition', u'localEulerAngles', u'localScale']

a non-exhaustive list of reserved keywords to prevent variable and reference naming conflicts

Initial value:
00001 {
00002         0:'XYZ', 
00003         1:'YZX', 
00004         2:'ZXY', 
00005         3:'XZY', 
00006         4:'YXZ', 
00007         5:'ZYX'
00008 }

a dictionary of possible rotation order values for EulerRotationOrder in Unity QuaternionHelpers

Initial value:
00001 [
00002         u'BlendShape',
00003         u'ExposeTransform',
00004         u'AimConstraint',
00005         u'OrientConstraint',
00006         u'PointConstraint',
00007         u'Transform']

a list of reference types that are supported in expressions

list amTools::unity::rigs::expressions.kSupportedVariableTypes = [u'float', u'int', u'string']

a list of MEL variable types that are supported

Initial value:
00001 {
00002         u'translateX':u'localPosition.x',
00003         u'translateY':u'localPosition.y',
00004         u'translateZ':u'localPosition.z',
00005         u'rotateX':u'localEulerAngles.x',
00006         u'rotateY':u'localEulerAngles.y',
00007         u'rotateZ':u'localEulerAngles.z',
00008         u'scaleX':u'localScale.x',
00009         u'scaleY':u'localScale.y',
00010         u'scaleZ':u'localScale.z'
00011         }

a dictionary to map Maya attributes to corresponding fields on Unity Transform objects

 All Classes Namespaces Files Functions Variables