CharacterizeFromDictionary.py

'''
CharacterizeFromDictionary.py

Defines a Characterize function that attempts to perform characterization
based on a dictionary mapping from HumanIK node names to joint names when
provided with the skeleton under which those joints can be found.

http://tech-artists.org/forum/showthread.php?3201
Alex Forsythe, October 8th, 2012
'''

from pyfbsdk import *

def Characterize(character, rootJoint, mappings, useBiped = True):
    '''
    Clears all current characterization for the given character and attempts
    to characterize it using the skeleton whose joints are contained beneath
    rootJoint. mappings should be a dict with HumanIK node names (sans 'Link',
    e.g. 'LeftHandExtraFinger2') as keys and joint short names as values. The
    optional useBiped parameter can be set false to use quadruped
    characterization instead of the default biped. Returns success.
    '''
    # Ensure that we start with a blank slate
    ClearCharacterization(character)

    # Iterate over the list of mappings
    for nodeName in mappings:

        # Get the property object for the requested node
        propertyName = '%sLink' % nodeName
        nodeProperty = character.PropertyList.Find(propertyName)
        assert nodeProperty is not None, '%s is not a valid node name.' % nodeName

        # Find the joint within the skeleton
        jointName = mappings[nodeName]
        jointModel = FindDescendantModel(rootJoint, jointName)
        assert jointModel is not None, 'No joint with short name %s was found beneath %s.' % (jointName, rootJoint.LongName)

        # Associate the joint with the character node
        nodeProperty.append(jointModel)

    # Finally, attempt characterization, complaining to the user if unsuccessful
    if not character.SetCharacterizeOn(useBiped):
        errorMessage = character.GetCharacterizeError()
        FBMessageBox('Characterization Error!', errorMessage, 'OK')
        return False

    # If nothing went wrong, inform the user of our success
    return True

def ClearCharacterization(character):
    '''
    Disables and resets characterization for the given character, removing all
    model mappings.
    '''
    character.SetCharacterizeOff()
    for prop in character.PropertyList:
        if prop.Name.endswith('Link') and isinstance(prop, FBPropertyListObject):
            prop.removeAll()

def FindDescendantModel(topModel, searchModelName):
    '''
    Recursively searches the given branch for a model with the specified short
    name, returning that model if found. Otherwise, returns None.
    '''
    if topModel.Name == searchModelName:
        return topModel

    for childModel in topModel.Children:
        foundModel = FindDescendantModel(childModel, searchModelName)
        if foundModel:
            return foundModel