Alex Forsythe

Key Points

• When you need to get a reference to a scene object based on name, namespace, or selection state, you can use the free (i.e., global) functions defined in the pyfbsdk module. Failing that, you can access lists of all components of a particular type via the FBScene class.
• FBFindModelByLabelName returns a single model given its exact long name. FBFindObjectByFullName returns a single component given its full name.
• FBFindObjectsByNamespace and FBFindObjectsByName search for multiple components based on name. They return their results by populating an FBComponentList.
• FBGetSelectedModels populates an FBModelList with all of the models that are currently selected.
• The FBScene class (accessible globally via FBSystem().Scene) can be used to iterate over all components of a certain type.
• FBScene.Components is a list of every component in the scene.
• FBScene also has a number of lists for various component subclasses, including Cameras, Actors, ControlSets (control rigs), Groups, and so on.
• Models, unlike other types of components, are hierarchical (i.e., they have children). FBScene.RootModel is the single topmost model in the scene. FBModel.Children allows us to iterate through models, and we typically use recursive functions to operate on entire branches.

Code

print FBFindModelByLabelName('ENV:Root')
print FBFindObjectByFullName('Model::ENV:Root') # <-- equivalent

import pyfbsdk

for attr in dir(pyfbsdk):

    if attr.endswith('_TypeInfo'):
        continue

    attrType = type(eval('pyfbsdk.%s' % attr))
    if str(attrType).find('Boost.Python.function') >= 0:
        print attr

foundComponents = FBComponentList()

includeNamespace = True
modelsOnly = False
FBFindObjectsByName('ENV:GEO:*', foundComponents, includeNamespace, modelsOnly)

for comp in foundComponents:
    print comp, comp.LongName

selectedModels = FBModelList()

topModel = None # Search all models, not just a particular branch
selectionState = True # Return models that are selected, not deselected
sortBySelectOrder = True # The last model in the list was selected most recently
FBGetSelectedModels(selectedModels, topModel, selectionState, sortBySelectOrder)

for model in selectedModels:
    print model, model.LongName

def GetLastSelectedModel():
    '''
    Returns the most recently selected model in the scene, or
    None if no models are selected.
    '''
    selectedModels = FBModelList()
    FBGetSelectedModels(selectedModels, None, True, True)
    return selectedModels[-1] if selectedModels else None

for comp in FBSystem().Scene.Components:
    comp.Selected = False

for camera in FBSystem().Scene.Cameras:
    print camera.LongName, camera.SystemCamera

for model in FBSystem().Scene.RootModel.Children:
    print '%s <%s>' % (model.LongName, model.__class__.__name__)
    assert model.Parent == None # Top-level models have no Parent

def SelectBranch(topModel):
    '''
    Selects the given model and all of its descendants. Note that this
    function does not clear the current selection -- that's the caller's
    responsibility, if desired.
    '''
    for childModel in topModel.Children:
        SelectBranch(childModel)

    topModel.Selected = True

def DeleteBranch(topModel):
    '''
    Deletes the given model and all of its descendants.
    '''
    while len(topModel.Children) > 0:
        DeleteBranch(topModel.Children[-1])

    topModel.FBDelete()

Notes & Errata

Deprecated Functions

You may have noticed that I failed to mention the FBFindModelByName function, which searches for models by short name only. This function is deprecated as of MotionBuilder 2012. You should use FBFindModelByLabelName instead, as it's faster and it avoids ambiguity.

Additionally, FBFindObjectsByNamespace is deprecated in MotionBuilder 2013. It's best to use FBFindObjectsByName instead, as its functions more-or-less identically with the proper arguments.

Group Names

You won't typically need to use FBFindObjectByFullName, which is the only public function that requires you to deal directly with group names. Still, the set of group names doesn't appear to be publicly documented, so here's an incomplete list:

Component Idiosyncrasies

A few types of components have some quirks that you should watch out for. Some of these are minor points that relate to nomenclature or inheritance. For example:

• As noted previously, Actors and Characters (and, as it happens, story tracks) are specific subclasses of FBConstraint.
• Control rigs, as they're called in the UI, are referred to in the SDK as control sets. The list in FBScene is ControlSets, and it contains FBControlSet objects.
• Texture images are technically videos: that is, they subclass FBVideoClip. When you import an image file into the scene, you end up with two identically named components: an FBVideoClipImage that contains the image data, and an FBTexture that maps the image onto a material.

More dangerously, some of the lists in FBScene contain special values alongside ordinary components. Some of these objects can crash MotionBuilder if you try to delete them, or they're simply undeletable, which might get you trapped in a while loop if you try to delete them all. To give a few examples:

• There's an invisible default material (called DefaultMaterial) that lives at FBSystem().Scene.Materials[0]. It can't be deleted.
• The Default Shader can't be deleted, though unlike the default material, it is visible in the navigator.
• The default cameras (Producer Perspective, Producer Front, etc.) are in the Cameras list, and they are actual FBCamera objects. However they don't exist in the scene as models, and deleting them crashes MotionBuilder. FBCamera.SystemCamera is set to True for these cameras.
• Your computer's audio and video input devices show up under Audio and Videos in the navigator. However, they're not actually part of the respective lists in FBScene.
• Similarly, the Global Light isn't an FBLight at all. It's actually a singleton which you can access by calling FBGlobalLight().
• Control rig reference models (e.g. Character_Ctrl:Reference) are undeletable while their corresponding FBControlSet objects still exist, and calling FBDelete on them can cause trouble. Don't bother trying: instead, delete the FBControlSet, and the reference model will automatically be deleted along with it.

These objects should have their deletable flag unset, if you feel like checking it. Here's how you might use it:

# The default material can't be deleted, so we'll be stuck
# in an infinite loop and crash if we try to delete everything.
while len(FBSystem().Scene.Materials) > 0:
    FBSystem().Scene.Materials[0].FBDelete()

# Here's a quick fix that works in the case of materials.
while len(FBSystem().Scene.Materials) > 1:
    FBSystem().Scene.Materials[1].FBDelete()

# But more generally, we could check the each object's flags.
i = 0
while i < len(FBSystem().Scene.Materials):
    
    material = FBSystem().Scene.Materials[i]
    
    if material.GetObjectFlags() & FBObjectFlag.kFBFlagDeletable:
        material.FBDelete()
    else:
        i += 1

Corrections?

If you see any errors that you'd like to point out, feel free to email me at awforsythe@gmail.com.