A typical SmartBody simulation involves the following steps:

1. Importing assets
2. Configuring the scene
3. Running the simulation

The following is an overview of setting up a SmartBody scene with a few examples of a typical setup.

By default, SmartBody imports the packaged called 'SmartBody" and places an instance of SBScene called 'scene' into the Python context. In order to retrieve the scene object directly, you can call getScene():

scene = SmartBody.getScene()

The scene object contains many important functions for querying. changing, creating and deleting objects and running the simulation.

Importing Assets

SmartBody can utilize various simulation assets such as skeletons, motions, scripts, model and texture files. In order to use those assets, they must be made known to SmartBody, Skeletons and motions are loaded into memory, whereas many other assets, such as scripts and geometry are loaded as needed.

To indicate where to find the assets, run the following command:

scene.addAssetPath(type, path)

where type is one of the following types:

The path can either be an absolute path, or a relative path. Relative paths will be interpreted as extending from SmartBody's media path, which by default is the same as the working directory of the SmartBody executable (set to '.' by default).To change the media path, run:

scene.setMediaPath("/path/to/some/where/")

For example, if the following motion path was specified:

scene.addAssetPath("motion", "foo/mymotions")

and the media path was set as above, the the final path for those motions would be: /path/to/some/where/foo/mymotions

Once all the paths are set, the following will load motion and skeleton assets into memory:

scene.loadAssets()

All motion and skeleton paths Note that skeletons and motions are loaded into memory and will not change after being loaded even if they are modified on disk after the simulation has been started. Scripts can be changed at any time, and are read from the filesystem every time a command to use them is performed.

To load assets from specific directories or folders, or a single asset from a particular file without changing the asset paths, run:

scene.loadAssetsFromPath("/path/goes/here")

This would allow partial loading of assets when needed, rather than all at once.

Configuring the Scene

A SmartBody scene can be populated with pawns (generally rigid objects or structures) and characters. In addition, scene configuration includes any non-default settings that SmartBody uses, including responding to events, adding Python scripts that are run during the simulation, turning on the physical simulation, setting up the locomotion/steering options and so forth.

Configuring Pawns

To add pawns to the scene, use:

mypawn = scene.createPawn(pawnName)

where 'pawnName' is a name unique to both pawns and characters. A pawn can then be positioned in the world by using:

pos = SrVec(x, y, z)
mypawn.setPosition(pos)

where 'x', 'y', and 'z' are positions in world space. In addition, the orientation of the pawn can be set using:

orientation = SrVec(h, p, r)
mypawn.setHPR(orientation)

where 'h', 'p', and 'r' are the heading, pitch and roll in degrees of the pawn. A geometry or mesh can also be associated with a pawn, by setting the 'mesh' attribute:

mypawn.setStringAttribute("mesh", meshfile)

where meshfile is a file or partial path indicating the location of the geometry or mesh file in COLLADA, .obj, or FBX format (if the FBX libraries have been built with SmartBody). To change the size of the mesh, set the meshScale attribute:

mypawn.setDoubleAttribute("meshScale", scale)

where 'scale' is the scaling factor of the mesh. Note that some SmartBody renderers might choose not to display this mesh in the scene.

Configuring Characters

SmartBody characters have an enormous number of configuration options, as detailed in the following section Configuring Characters. Briefly, you can create a character by using:

mycharacter = scene.createCharacter(characterName)

where 'characterName' is a name unique to all other characters and pawns in the scene. Characters by default are initialized with a skeleton that has a single joint. To attach a more complex joint hierarchy, create the skeleton and attach it to the character:

myskeleton = scene.createSkeleton(skeletonfile)
mycharacter.setSkeleton(myskeleton)

where 'skeletonfile' is the name of the file containing a description of the joint hierarchy. The file can be in any of the following formats: .bvh, .asf, COLLADA (.dae or .xml), .fbx, or .sk (SmartBody's proprietary format).

By default, characters do not contain any controllers that allow it to perform complex actions such as lip synching, locomotion, gesturing or head nodding. To add the default set of controllers that allow the character to respond to BML and other commands, do the following:

mycharacter.createStandardControllers()

Note that additional configuration is also needed to activate some controllers (such as a set of locomotion animations or reaching animations). In addition, many controllers have default settings that can be changed by modifying various parameters on the Character. Please see the section on Configuring Characters for more details.

Character positions and orientations can be set in the same way as for pawns:

pos = SrVec(x, y, z)
mypawn.setPosition(pos)
orientation = SrVec(h, p, r)
mypawn.setHPR(orientation)

Characters can be attached to geometry using smooth binding/skinning by specifying the directory that contains the skinning mesh and textures then setting the deformableMesh attribute:

mycharacter.setStringAttribute("deformableMesh", path)

where 'path' is the top level directory under one of the mesh directories that contains a COLLADA (.dae or .xml), FBX or .obj files. Note that the COLLADA file must contain the vertex-joint mappings, and can optionally contain the mesh and locations of textures. If the mesh isn't present in the COLLADA file, then the directory will be searched for .obj files that specify the mesh. The FBX file must contain both the mesh as well as the vertex-joint mappings. Note that some SmartBody renderers may choose not to display the deformable mesh. If the mesh needs to be unifromly scaled, for example to convert a mesh stored in centimeters into meters, the 'deformableMeshScale' attribute can be set to a non-1.0 value:

mycharacter.setDoubleAttribute("deformableMeshScale", scaleFactor)

where 'scaleFactor' is a multiplier by which all vertices will be multiplied, and '1' is the default.

Running the Simulation

The scene contains a simulation manager called 'sim' (instance of SBSimulationManager) that gets placed into the scene automatically by SmartBody. This can be automatically retrieved from the scene automatically by calling:

sim = scene.getSimulationManager()

The simulation can be started by calling the start() function:

sim.start()

and paused, resumed or stepped one frame using the following:

sim.pause()
sim.resume()
sim.step(num)

where 'num' is the number of steps to run. Note that by default, SmartBody runs using a real-time clock. In order to control the time of the simulation explicitly, you can call the setTime() function using the current time in seconds:

sim.setTime(currentTime)

Alternatively, SmartBody can be run using simulated time instead of the real-time clock by specifying a simulation stepping rate:

sim.setSimFps(fps)

where fps is the number of simulation frames per second (i.e. 60 = 60 frames per second). Setting this value to zero will set SmartBody back into real-time clock mode.

Scene and Simulation Options

There are several options that can be modified in a scene. The following is a list of attributes that can be changed to modify the general behavior of the simulation: