Creating and Editing Structure Files

 
 
 

MOTOR uses ASCII files to determine the basic structure that is used when tagging rigs. The structure file defines a simple hierarchy that allows MOTOR to work with motion data from any source, ignoring the complexities of each unique rig.

Structure files come in two parts: a base file and a structure file. Typically, the base file contains most of the definition of the simple skeleton, and the structure file contains only extra body parts. This allows for different structure files to share a similar base file.

The structure and base files determine the layout of the Tagging property page (when you choose Tools MOTOR Tag Rig from the Animate toolbar). The contents of the base file are used to define the layout of the main tab of the Tag property page, and the contents of the structure file are used to define the contents of the Extra Parts tab of the Tag property page.

Opening a Structure File

The structure and base files are ASCII text files that are stored in the Addons folder in your Softimage installation path:

\Addons\MotionTransformation\Data\Structures\

You must define a new structure file to be able to have another option in the Structures list box; however, it is optional to define another base file.

To open a structure file

  • In the Tag property editor, click the Edit button beside the Structure File text box. This opens a script editor in which you can edit the file.

    or

  • Open the structure file in any text editor, such as Windows Notepad, Wordpad, or the Softimage script editor.

Structure and Base File Contents

A line in the structure file that starts with a # is a comment and will be ignored by MOTOR. These lines usually contain useful information indicating the purpose of the following lines.

Structure Files

The following is the contents of the Biped.structure file that is distributed with MOTOR.

#!XSI_CDK_Structure 2.0
# the base structure
Biped
# extra elements to add to the base structure
Head
{
	chest
	neck		child		0 1 0	0 0 1	0 0 0
	head		free		0 1 0	0 0 1	0 0 0
}

RFoot
{
	rfoot	
	rheel		child		0 0 1	0 1 0	0 0 0
	rtoe		child		0 0 1	0 1 0	0 0 0
}
LFoot
{
	lfoot
	lheel		child		0 0 1	0 1 0	0 0 0
	ltoe		child		0 0 1 0 1 0	0 0 0
}
Base file listing
# the base structure
Biped

The structure files start by listing a base file. Here, the Biped.structure file has listed Biped.base as its base file. This means that when MOTOR is loading this structure file, is loads the base file into the main tab on the Tag property page, and loads the remaining contents of the structure file into the Extra Parts tab on the Tag property page.

Base Files

The contents of the base file define most of the structure of the simple rig.

#!XSI_CDK_BASE 2.0
# the minimum requirement for a Biped is a Spine, RLeg, RArm, LLeg, and LArm 
Spine
{
	world
	cog		hip		0 1 0	0 0 1	0 2.2 0
	spineroot	child		0 1 0	0 0 1	0 0 0
	chest		free 		0 1 0	0 0 1	0 1 0
}
Pelvis
{
	cog
	pelvis		child		0 1 0 	0 0 1 	0 0 0	
}
RLeg
{
	pelvis
	rthigh		anchor		0 -1 0	0 0 1	-0.4 0 0
	rshin		child		0 -1 0	0 0 1	0 -1 0
	rfoot		friction		0 0 1	0 1 0	0 -1 0 	limits: 1 1 -5	-1 -1 5
}
RArm
{
	chest
	rclavicle	child 		-1 0 0	0 1 0 	0 0 0
	rupperarm	anchor		-1 0 0	0 1 0 	-0.4 0 0
	rforearm	child		-1 0 0 	0 1 0	-0.5 0 0
	rwrist		ik		-1 0 0 	0 1 0	-0.4 0 0
	rhand		child		-1 0 0 0 1 0	0 0 0	
}
LLeg
{
	pelvis
	lthigh		anchor		0 -1 0	0 0 1	0.4 0 0
	lshin		child		0 -1 0	0 0 1	0 -1 0
	lfoot		friction		0 0 1	0 1 0	0 -1 0 	limits: 1 1 -5	-1 -1 5
}
LArm
{
	chest
	lclavicle	child 		1 0 0	0 1 0	0 0 0
	lupperarm	anchor		1 0 0	0 1 0	0.4 0 0
	lforearm	child		1 0 0 	0 1 0	0.5 0 0
	lwrist		ik 		1 0 0	0 1 0	0.4 0 0
	lhand		child		1 0 0 	0 1 0	0 0 0
}

Groups

The structure files define groups of bones. These groups start with a name that defines the name of the group, and then an open curly brace: {

The group name is used by the Tag property page to define the name of the group box that holds the group's contents.

The group is closed by a close curly brace: }

Groups cannot contain subgroups - you cannot start another group within a group.

Group Parent

The first line inside the group defines the group's parent. If the group lists world as its parent, then this group is the root of the hierarchy. Most groups list a bone as the parent to a group. The LLeg group in the example above lists pelvis ' as its parent bone, while the RArm group lists chest.

Note: The parent bone listed is a bone name rather than a group name. It is possible to define groups with the same name as bones, as you can see that the Pelvis group in the example also contains a pelvis bone.

Group Bones

All the lines that follow after the parent bone listing define bones that make up this structure.

lfoot		friction		0 0 1	0 1 0	0 -1 0 	limits: 1 1 -5	-1 -1 5

Each line contains three or four pieces of information:

  • The name of the bone

  • The type of the bone

  • The direction, roll, and translation offset of this bone

  • (Optional) Limits.

Bone Name

Each bone's name must be unique; that is, no two bones in the structure file can have the same name.

Bone Type

Bones can have a variety of types: hip, child, free, anchor, ik, and friction.

  • hip: A bone that is driven in global space with no parent.

  • child: A forward kinematic child with a fixed local translation.

  • free: A bone that can mode and rotate relative to its parent, but must stay on one side of the parent bone (chest).

  • anchor: Similar to child, but this type of bone also defines the start of a bone chain.

  • ik: The IK end effector for an arm.

  • friction: The IK end effector for a leg. This means that the limb get treated like a leg when the motion is scaled, and when stride lengths are changed in the Retarget Adjust property page.

Note: An arm end effector can still be set to behave as a leg using an option in the Adjust property page.

Direction, Roll, and Offset

The Direction, Roll, and Offset make up nine numbers: three numbers for each parameter.

  • Direction is simply a vector that defines the direction this bone should point in global coordinates. For example, 0 1 0 is for a bone that points straight up as in the COD spine and chest, etc.

    In a T-pose, the right arm points in the negative Y global axis with a vector of -1 0 0.

  • Roll defines the plane along which this bone lies. This is useful for the IKPlane solvers to determine where the Plane up-vector nodes should be.

  • Offset defines a world space direction offset for this bone. Values of 0 0 0 mean that this bone lies on top of its parent bone; values of 0 1 0 mean that it is above its parent bone in the Y axis.

Limits

The limit information is used by the C3D importer to define a range for how many of the C3D markers will be used to control this bone. In most cases, this can be left out.

Adding New Bones

It is easy to add new bones to a structure file. You simply need to either choose a group to which this bone will belong or create a new group.

  1. Determine which bone will be the parent for this new bone.

  2. Determine which roll this bone will be in by default. It is easiest if you copy the settings from a similar bone that points in roughly the same direction.

  3. Determine which direction offset this bone will be in by default.

Using the New Structure File

Once you have saved the new structure file, you can immediately open the Tagging property page and select the new file to define the layout of the Tagging property page.

Tip: One way to visualize your structure file is to create it using the C3D importer.

  1. In the structure file folder, put your new structure file into the MotionCapture folder. This allows your structure file to be seen in the C3D property page.

  2. Open up the Mocap to Rig property page, and switch to C3D.

  3. Choose your Structure from the list of available structures.

  4. Click Import C3D, and choose a C3D file (you can actually choose any file - it doesn't matter).

Your structure file is created as a Model made up of black dots connected with lines.