FBModel - Transformation Data and the Scene Graph

What is an FBModel?

Scene elements such as cameras (FBCamera), lights (FBLight), geometric objects (FBModelCube, FBModelPlane), control points (FBModelMarker), optical markers (FBModelOptical), skeleton joints (FBModelRoot, FBModelSkeleton), nulls (FBModelNull), and path points (FBModelPath3D) all inherit from the FBModel class.

The FBModel class is used to define a scene element's transformation data (FBModel.Translation, FBModel.Rotation, FBModel.Scaling). The scene graph is created by arranging the scene elements in a parent/child hierarchy via FBModel.Parent or FBModel.Children. For more information, consult The Scene Graph section below.

Model Names and Namespaces

The FBModel class inherits from the base entity class: FBComponent. As such, each instance of FBModel can be uniquely identified by a combination of its name and namespace. This naming scheme allows you to search for a model using FBFindModelByLabelName(). Models can also be searched according to their type via FBFindModelsOfType(). For more information on searching and naming, see FBComponent - The Base Entity Class (Names and Namespaces).

Model Properties

In addition to transformation data, the FBModel class also defines a wide variety of properties, a number of which are described below. For a full list of the FBModel properties, consult the FBModel class documentation.

Property	Description
FBModel.Geometry	A geometric object to be rendered at the model's position in the scene, for example: a mesh (FBMesh) or a surface (FBNurbs, FBPatch).
FBModel.Materials	A list of materials (FBMaterial) to be applied to the model's geometry.
FBModel.Textures	A list of textures (FBTexture) to be applied to the model's geometry.
FBModel.Shaders	A list of shaders (FBShader) to be applied to the model's geometry. NoteShaders behave differently in comparison to materials and textures. Consult the code sample in FBScene - The Scene Class for more details.
FBModel.ShadingMode	An enumeration value (FBModelShadingMode) used to control the model's shading mode. This data and other enumeration properties are available in the fbmodel.h C++ header file. The possible shading mode values are: FBModelShadingMode.kFBModelShadingDefault FBModelShadingMode.kFBModelShadingWire FBModelShadingMode.kFBModelShadingFlat FBModelShadingMode.kFBModelShadingLight FBModelShadingMode.kFBModelShadingHard FBModelShadingMode.kFBModelShadingTexture FBModelShadingMode.kFBModelShadingAll
FBModel.LookAt	An FBModel object to look at in the scene. Useful for pointing cameras and spotlights.
FBModel.UpVector	An FBModel object indicating the up vector of the current model. Useful for orienting a camera.
FBModel.Show	A boolean value (True, False) indicating whether or not the viewer should show the object according to its visibility value (FBModel.Visibility).
FBModel.Pickable	A boolean value (True, False) indicating whether or not the model can be picked in the viewer.
FBModel.RotationOrder	An enumeration value (FBModelRotationOrder) used to specify the rotation order of the model. The possible rotation order values are: FBModelRotationOrder.kFBEulerXYZ FBModelRotationOrder.kFBEulerXZY FBModelRotationOrder.kFBEulerYZX FBModelRotationOrder.kFBEulerYXZ FBModelRotationOrder.kFBEulerZXY FBModelRotationOrder.kFBEulerZYX FBModelRotationOrder.kFBSphericXYZ

NoteUse the Python .append() function when you want to add an element to a list property, as illustrated in the following code sample:

cube = FBModelCube('myCube')
cube.Show = True

material = FBMaterial('myMaterial')
material.Diffuse = FBColor(0.17, 0.47, 0.8)
cube.Materials.append(material)

The Scene Graph

The root model of the scene (FBScene.RootModel) is the entry point into the scene graph. It is analogous to the scene's origin (0, 0, 0). When an instance of FBModel is created, it is automatically added as a child to the root model. Observe that a model's local translation, rotation, and scaling vectors are applied relative to the parent's frame of reference.

# Create a cube, and position it in space.
cube = FBModelCube('myCube')
cube.Translation = FBVector3d(0, 60, 0)
cube.Scaling = FBVector3d(10, 10, 10)
cube.Show = True

The models you create can be assigned as children or parents to other models. This parent/child hierarchy is referred to as the scene graph. An FBModel can only have one parent, but can have multiple children. The script provided in FBPlug - Object Connection Management (Inspecting an FBModel's Connections) allows you inspect a selected model's connections.

In the code sample below, a torus model is created, and parented to the cube created above. Any subsequent geometric transformations applied to the cube will also be applied to the torus.

# Create a torus, and position it in space. 
torus = FBCreateObject( 'Browsing/Templates/Elements/Primitives', 'Torus', 'Torus' )
torus.Scaling = FBVector3d(5, 5, 5)
# Set the torus' parent as the cube. Any local transformations
# applied to the torus will now be in relation to the cube's frame
# of reference.
torus.Parent = cube
# Translate the torus by 5 units above the cube.
torus.Translation = FBVector3d(0, 5, 0)
torus.Show = True

# Rotate the cube by -45 degrees along its parent's x axis,
# and by 45 degrees along its parent's y axis. 
# This will now also rotate the torus accordingly.
cube.Rotation = FBVector3d(-45, 45, 0)

NoteWhen you are a creating primitive element such as a torus or a sphere, the FBCreateObject() function requires that the third parameter be identical to the second parameter. The second parameter must also match the name of the primitive you wish to create from the asset browser (e.g. 'Torus').

Example: Basic Model Organization

Sample Viewport Output:

Program Summary: The program below creates a cube and a torus, and assigns the torus as a child to the cube. The printSceneGraph() helper function recursively traverses and prints the scene graph.

from pyfbsdk import *


###############################################################
# Helper Function(s).                                         #
###############################################################

# Recursively print the model's children.
def printSceneGraph(pModel, pLevel):
    tabs = ''
    for i in range(0, pLevel):
        tabs += '\t'
    print tabs + pModel.Name + ' - ' + pModel.ClassName()

    for child in pModel.Children:
        printSceneGraph(child, pLevel + 1)



###############################################################
# Main.                                                       #
###############################################################

# Clear the scene.
FBApplication().FileNew()
scene = FBSystem().Scene

# Create a cube, and position it in space.
cube = FBModelCube('myCube')
cube.Translation = FBVector3d(0, 60, 0)
cube.Scaling = FBVector3d(10, 10, 10)
cube.Show = True

# Create a torus, and position it in space. 
torus = FBCreateObject( 'Browsing/Templates/Elements/Primitives', 'Torus', 'Torus' )
torus.Scaling = FBVector3d(5, 5, 5)
# Set the torus' parent as the cube. Any local transformations
# applied to the torus will now be in relation to the cube's frame
# of reference.
torus.Parent = cube
torus.Translation = FBVector3d(0, 5, 0)
torus.Show = True

# Rotate the cube by -45 degrees along its parent's x axis,
# and by 45 degrees along its parent's y axis. 
# This will now also rotate the torus accordingly.
cube.Rotation = FBVector3d(-45, 45, 0)

# Print the scene graph.
printSceneGraph(scene.RootModel, 0)



###############################################################
# Output.                                                     #
###############################################################
#>>>
#Scene - FBModel
#    myCube - FBModelCube
#        Torus - FBModel
#>>>