Alex Forsythe

Key Points

• The Python Editor in MotionBuilder (accessible from the Window menu) allows Python code to be written and evaluated interactively.
• Unlike Maya, results of highlighted and executed calls are not automatically printed. Explicit print statements are required in all cases.
• Importing everything from pyfbsdk gives us access to the MotionBuilder API.
• Like any other Python module, pyfbsdk is located in the path, allowing us to import it.
• Many scene objects are created simply by calling their constructor and passing in a name: e.g. FBModelCube('myCube')
• Models created through the API are initially hidden. Set their Show property to True to make them visible.
• Vector properties (e.g. Translation, Rotation, Scaling) can be edited by constructing and assigning a new FBVector3d(x, y, z) value.
• Most objects are deleted from the scene with a simple call to their FBDelete method.
• FBFindModelByLabelName can be used to get a reference to an existing model given its name (including namespace).
• Decomposing scripts into discrete functions is one hell of a good idea.
• It's common to use a main function to trigger "on execution" behavior, but only when the value of __name__ is __main__ or __builtin__.
• Saving scripts into a directory which is included in the Asset Browser allows them to be run again later.

Code

from pyfbsdk import *

import random

def CreateCube(xPos, yPos, scaleFactor):
    '''
    Creates a test cube at the given position on the XY plane, scaling it
    uniformly by the given scale factor. The name of the cube will be
    based on its initial position. Returns the new cube.
    '''
    name = 'testCube_%d_%d' % (xPos, yPos)
    cube = FBModelCube(name)
    cube.Show = True

    cube.Translation = FBVector3d(xPos, yPos, 0.0)
    cube.Scaling = FBVector3d(scaleFactor, scaleFactor, scaleFactor)

    return cube

def main():
    ''' Creates a wall of cubes. '''
    GAP_INTERVAL = 50
    for xPos in range(-500, 500, GAP_INTERVAL):
        for yPos in range(0, 1000, GAP_INTERVAL):
            CreateCube(xPos, yPos, random.random() * 5.0 + 5.0)

if __name__ in ('__main__', '__builtin__'):
    main()

Notes & Errata

The Asterisk Import

Around 2:15, I explain the effects of blanket-importing everything from pyfbsdk with the asterisk syntax, and I mention that using this sort of import is ordinarily bad practice.

Python is very keen to organize code into namespaces, and one of the great benefits of this practice is that you don't have to worry about name clashes and other inane problems. For example, I can have a local variable called path, and at the same time I can search through a list of module directories called sys.path and use functions in another module called os.path. I don't have to worry about any of these things overwriting the other, so long as I don't do something stupid like this:

path = 'C:\\foo.txt'          # path is now a string
from sys import *             # path is now a list
from os import *              # path is now a module
path = path.normpath(path[0]) # what you talkin bout, willis?

Namespaces aren't as strictly used in C++, and things like named symbols and relationships between source files don't matter after compile time. A common mechanism for avoiding clashes in C++ libraries is to give everything a prefix, hence the redundant-seeming FB prepended to every class in pyfbsdk. It would seem kind of pointless to do something like this:

import pyfbsdk as fb
cube = fb.FBFindModelByLabelName('Cube')
null = fb.FBModelNull('Null')

Because this more primitive method protects us from name clashes, and because MotionBuilder ordinarily has all of these classes imported already, it's not a huge deal for us to use an asterisk import here. I just wanted to point out this peculiarity so you know that it's still totally not cool to import other Python modules this way.

Argument Error Message

At 2:50, I call the constructor of FBModelCube with no arguments to demonstrate an error message. If you get a Boost.Python.ArgumentError, you haven't provided the correct number of arguments or the correct types of arguments.

Boost.Python is the library that generates the Python bindings for the C++ API, and this error is its way of complaining that it couldn't find a sensible way to translate from the Python arguments it's been given to one of the function prototypes expected in the underlying C++ code. There can be many (overloaded) prototypes, but in this case it's just one:

__init__(struct object * __ptr64, char * __ptr64)

The message lists the name of the function that Boost.Python is trying to call (__init__), followed by its arguments, which are both unhelpfully named __ptr64 (64-bit pointer). The important details here are the number of arguments and their types.

The first argument is of type struct object * — this just means it's a pointer to a Python object. In all method calls, this first argument is the object on which we're calling the method (i.e., self or this). We can see from the "Python argument types" line that this object is being passed in automatically on our behalf: Python just happens to know more specifically that it's an FBModelCube.

The second argument in the C++ signature is of type char * (character pointer), which is C-speak for "string." So that's how we know, from deciphering the error message, that we need to pass in a string.

Corrections?

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