Alex Forsythe

Key Points

• Keys can be added to an FCurve at any local time by calling FBFCurve.KeyAdd(FBTime, float).
• KeyAdd returns an integer index which can be used to access FBFCurveKey objects in the Keys list.
• Keys can be deleted either by time range, using KeyDeleteByTimeRange, or directly via index with KeyDeleteByIndexRange, which will crash if an invalid range is supplied.
• Adding, deleting, or moving keys displaces all the keys to the right of the change, invalidating any previously stored indices.
• The area between two keys is defined first and foremost by the interpolation mode (FBFCurveKey.Interpolation):
• Linear uses simple linear interpolation (a straight line).
• Constant holds on the value of either the current key or the next one (depending on the value of ConstantMode).
• Cubic uses Bezier tangents, whose values are defined principally by LeftDerivative|RightDerivative and LeftTangentWeight|RightTangentWeight.
• A key's right tangent may or may not be relevant based on that key's interpolation mode. A key's left tangent may or may not be relevant based on the previous key's interpolation mode. In other words, interpolation mode affects the right side of the key.
• There are four tangent modes (FBFCurve.TangentMode): TCB, Auto, User, and Break. Regardless of which is enabled, the combination of Derivative and Weight is sufficient to describe any tangent.
• To reconstruct a curve (or some segment thereof), it's best to first add the keys at the appropriate times and values, setting their interpolation mode, tangent mode, and constant mode along the way. Then, in a second pass, the derivative and weight values can be safely set.

Code

# Create a camera and look through it in the viewport
camera = FBCamera('Camera')
camera.Show = True
FBSystem().Renderer.CurrentCamera = camera
camera.Selected = True

# Animate the Roll property, thereby creating an FCurve
camera.Roll.SetAnimated(True)

# Keep a local reference to the roll FCurve
node = camera.Roll.GetAnimationNode()
fcurve = node.FCurve

fcurve.KeyAdd(FBTime(0, 0, 0, 0), 0.0)
fcurve.KeyAdd(FBTime(0, 0, 0, 100), 100.0)
fcurve.KeyAdd(FBTime(0, 0, 0, 50), 25.0)
fcurve.KeyAdd(FBTime(0, 0, 0, 50), 10.0)
# At this point, we have three new keys:
# 0.0 at frame 0, 10.0 at frame 50, and 100.0 at frame 100

index = fcurve.KeyAdd(FBTime(0, 0, 0, 75), 50.0)
key = fcurve.Keys[index]
print key # <FBFCurveKey object>

for i in range(0, len(fcurve.Keys)):
    key = fcurve.Keys[i]
    print '[%d] Frame %3d: %.2f' % (
        i,
        key.Time.GetFrame(True),
        key.Value
    )
# "for key in fcurve.Keys" works equally well if you don't need the index

import math

for i in range(0, 150):
    fcurve.KeyAdd(FBTime(0, 0, 0, i), math.sin(i * 0.1) * 10)

# Specify a range. To delete a single key, use the same index for both values.
start = 50
stop = 100

# MotionBuilder will crash if the index range is out of bounds!
assert start >= 0 and start < len(fcurve.Keys)
assert stop >= 0 and stop < len(fcurve.Keys)

fcurve.KeyDeleteByIndexRange(start, stop)

# Bad! Untouched keys have their indices shifted around as we iterate forward.
for i in range(0, len(fcurve.Keys), 2):
    fcurve.KeyDeleteByIndexRange(i, i)

# Works as intended!
for i in reversed(range(0, len(fcurve.Keys), 2)):
    fcurve.KeyDeleteByIndexRange(i, i)

# Delete all keys between 2 seconds and the end of time.
# Since pInclusive is False, the key at the 2-second mark will be left intact.
fcurve.KeyDeleteByTimeRange(FBTime(0, 0, 2), FBTime.Infinity, False)

fcurve.EditClear()
# Effectively equivalent to:
# fcurve.KeyDeleteByTimeRange(FBTime.MinusInfinity, FBTime.Infinity)

def SerializeCurve(fcurve):
    '''
    Returns a list of dictionaries representing each of the keys in the given
    FCurve.
    '''
    keyDataList = []

    for key in fcurve.Keys:

        keyData = {
            'time': key.Time.Get(),
            'value': key.Value,
            'interpolation': int(key.Interpolation),
            'tangent-mode': int(key.TangentMode),
            'constant-mode': int(key.TangentConstantMode),
            'left-derivative': key.LeftDerivative,
            'right-derivative': key.RightDerivative,
            'left-weight': key.LeftTangentWeight,
            'right-weight': key.RightTangentWeight
        }

        keyDataList.append(keyData)

    return keyDataList

def TangentWeightIsDefault(tangentWeight):
    '''
    Returns whether the given tangent weight is equal to the default value of
    1/3, taking floating-point precision into account.
    '''
    return tangentWeight > 0.3333 and tangentWeight < 0.3334

def DeserializeCurve(fcurve, keyDataList):
    '''
    Populates the given FCurve based on keyframe data listed in serialized
    form. Expects key data to be ordered by time. Any existing keys will be
    removed from the curve.
    '''
    # Ensure a blank slate
    fcurve.EditClear()

    # Loop 1: Add keys and set non-numeric properties
    for keyData in keyDataList:

        keyIndex = fcurve.KeyAdd(FBTime(keyData['time']), keyData['value'])
        key = fcurve.Keys[keyIndex]

        key.Interpolation = FBInterpolation.values[keyData['interpolation']]
        key.TangentMode = FBTangentMode.values[keyData['tangent-mode']]
        if key.TangentMode == FBTangentMode.kFBTangentModeTCB:
            key.TangentMode = FBTangentMode.kFBTangentModeBreak
        key.TangentConstantMode = \
          FBTangentConstantMode.values[keyData['constant-mode']]

    # Loop 2: With all keys in place, set tangent properties
    for i in range(0, len(keyDataList)):

        keyData = keyDataList[i]
        key = fcurve.Keys[i]

        key.LeftDerivative = keyData['left-derivative']
        key.RightDerivative = keyData['right-derivative']

        if not TangentWeightIsDefault(keyData['left-weight']):
            key.LeftTangentWeight = keyData['left-weight']
        if not TangentWeightIsDefault(keyData['right-weight']):
            key.RightTangentWeight = keyData['right-weight']

Notes & Errata

Additional Tangent Properties

There are a few less-important properties of FBFCurveKey that I didn't explicitly mention. In brief:

• TangentClampMode is an obscure enumeration that can either be None or Clamped. This is a setting that affects keys with Auto interpolation, but only when the Auto tangent type is set to Spline or Smooth. With the default Auto tangent type of Progressive Clamp, TangentClampMode doesn't have any effect, and its button is hidden in the FCurve editor UI. (For more information on auto tangent settings, see the MotionBuilder User Guide.)
• TangentBreak is a boolean that represents whether the tangent is in break mode. Quite simply, if TangentMode is kFBTangentModeBreak, then TangentBreak is True. If not, TangentBreak is False.
• LeftBezierTangent and RightBezierTangent are similar to Derivative, but their values are also dependent on the positions of adjacent keys. Updating the derivative updates the tangent property (and vice versa), so if you're using one, you don't need the other.

Tangent Weight

In the FCurve editor UI, there's a little button which enables custom tangent weight values for the selected key:

With the Wt button disabled, the tangent weights stay at their default value of 0.3333. With Wt enabled, the user can input a different value (between 0.0 and 1.0). Regardless of the value, the editor displays the tangents differently depending on whether the Wt button is enabled. When the user drags the tangent with custom weighting enabled, he's modifying the weight as well as the angle.

Unfortunately, there's no way to access this setting from Python. Initially, it's disabled, and as soon as either TangentWeight property is changed via the API, it's irrevocably enabled. That's the rationale for including that final step in the DeserializeCurve function: we don't modify the tangent weight if it was at the default value in the first place. Otherwise, the user would find that every single tangent handle affected the weight value as well as the angle.

Serializing Enumeration Values

You'll notice that when I save the values of each key's enumeration properties, I convert them to raw integers first. By using the values dictionary of each enumeration type, I can map those integers back into the correct value.

print FBInterpolation.values
# { 0: kFBInterpolationConstant,
#   1: kFBInterpolationLinear,
#   2: kFBInterpolationCubic }

# Convert from FBInterpolation to integer and back again
intValue = int(FBInterpolation.kFBInterpolationLinear)
interpolation = FBInterpolation.values[intValue]

print intValue, interpolation
# 1, kFBInterpolationLinear

Instead of using integers, you could just as well store the enumeration value names as strings. This would protect your data in case enumerations were added or shifted around in subsequent versions, and it would make the values a bit easier to deal with if you intended to use the data outside of MotionBuilder. It'd only take a bit more work:

# Convert from FBInterpolation to string and back again
strValue = str(FBInterpolation.kFBInterpolationLinear)
interpolation = getattr(FBInterpolation, strValue)

Similarly, I store the time of each keyframe as the internal FBTime value — that really big integer that only MotionBuilder knows how to interpret. To make things a bit more agnostic, you could use the floating-point GetSecondDouble() value instead. Using Get() just keeps things simple and avoids precision issues.

Serialization and File Formats

Around 6:53, I briefly demonstrate how to use the json module to write the serialized data for a curve to an ASCII file. Converting between simple objects and JSON files is quite painless:

import json
filepath = 'C:\\fcurve.json'

# Write a curve to a JSON file
with open(filepath, 'w') as fp:
    keyDataList = SerializeCurve(fcurve)
    fp.write(json.dumps(keyDataList, indent = 4))

# Read a curve from a JSON file
with open(filepath, 'r') as fp:
    keyDataList  = json.loads(fp.read())
    DeserializeCurve(fcurve, keyDataList)

JSON is a convenient format to use since it maps so cleanly to Python lists and dictionaries, but of course you could use any format you like. Another equally convenient option from the Python Standard Library is the pickle module:

import cPickle as pickle
filepath = 'C:\\fcurve_file'

# Pickle a curve to disk in binary format
with open(filepath, 'wb') as fp:
    keyDataList = SerializeCurve(fcurve)
    pickle.dump(keyDataList, fp, 2)

# Unpickle binary data back to the curve
with open(filepath, 'rb') as fp:
    keyDataList  = pickle.load(fp)
    DeserializeCurve(fcurve, keyDataList)

Corrections?

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