BonesPro Export File Format

Conventions Used

The structure file and animation file exported by BonesPro are both in text (ASCII) format and have the TXT extension. They can be viewed using a text viewer or editor. The next 2 sections of this document will provide the detailed description of the contents of structure and animation file. The following font and color conventions will be used:

Black Bold - integer, floating point or string values encountered in the file

Italics - C-style logical expressions (like for and if) that are not part of the file, but are used to explain the data format

Regular - misc comments and explanations that are not part of the file

The exported text files may contain comments denoted by double slash, like in C++. The double slash means that the rest of current line should be ignored

Structure File

The bones’ and vertices’ data in the Structure File describe the initial configuration of the mesh-skeleton system. These data can be considered as the “snapshot” of skeleton and mesh taken at the moment when the mesh was being attached to the skeleton.

To create this file, click the Export button (in the Parameters rollout of the BonesPro modifier dialog), then choose Structure from the pop-up menu.

Begin structure file

Nb number of bones in the skeleton

Nv number of vertices in the attached mesh

for ( int b = 0; b < Nb; b++ ) {

<bone_name> bone name, in < >

p

p is the number (in the order as they are written in this file of bone’s parent. The asterisk * means that this bone has no parents, or its parent is not a bone from this list.

Ax Ay Az

Each bone is defined not only by its position/orientation, but also by the size of its imaginary bounding box. Ax, Ay and Az define the size of this box for the given bone

R00 R01 R02 bone transform

R10 R11 R12

R20 R21 R22

Tx Ty Tz

The R matrix defines the rotational component of bone’s transform. The T vector is the translation component. This is the bone matrix used for the calculation of mesh deformation.

R00 R01 R02 nodes transform

R10 R11 R12

R20 R21 R22

Tx Ty Tz

The transform matrix of the bone’s node does not necessary coincide with the bone matrix used for the calculation of mesh deformation.

}

for ( int v = 0; v < Nv ; v++ ) {

Vx Vy Vz

The [absolute world] coordinates of the vertex #v

Nbv

The number of bones that affect this vertex

for ( i = 0; i < Nbv ; i++ ) {

b W

The number of bone and the [floating point] weight. The weight defines that share of influence that the bone #b has upon the vertex #v

}

}

End structure file

Animation File

The Animation file stores the bone and/or vertex data for the specified animation interval.

To create this file, click the Export button (in the Parameters rollout of the BonesPro modifier dialog), then choose Animation from the pop-up menu.

The format of this file depends on the specified Export Mode. There are three Export modes available: Bones, Mesh (absolute) and Mesh (bones coordinate system).

Begin animation file

Nb number of bones in the skeleton

Nv number of vertices in the attached mesh

Nf number of frames in the interval

ExportMode

The export mode can take one of three values: “Bones”, “Mesh (absolute)” or “Mesh (bones c.s)”.

TransformSystem

The Transform System can take one of two values: “Absolute” or “Relative to parent”

TransformRepesentation

The Transform Representation can take one of two values: “Matrix” or “Euler Angles”

EulerOrder

The Euler Angle Order define the type of euler angles calculation. The possible values are: “XYZ”, “XZY”, “YZX”, “YXZ”, “ZXY”, “ZYX”, “XYX”, “YZY”, “ZXZ”

AngleUnits

Defines the units for the Euler angles.The possible values are: “Degrees” or “Radians”

FirstFrame

LastFrame

Step The last three vales define the exported animation interval

for ( int f = 0; f < Nf ; f++ ) {

switch ( ExportMode ) {

case “Bones”:

for ( int b = 0; b < Nb; b++ ) {

Ax Ay Az

Each bone is defined not only by its position/orientation, but also by the size of its imaginary bounding box. Ax, Ay and Az define the size of this box for bone #b at frame # f

switch ( Transform Representation ) {

case “Matrix”:

R00 R01 R02 bone transform

R10 R11 R12

R20 R21 R22

Tx Ty Tz

R00 R01 R02 bone transform

R10 R11 R12

R20 R21 R22

Tx Ty Tz

break;

case “Euler Angles”:

E0 E1 E2 bone transform

Tx Ty Tz

E0 E1 E2 bone transform

Tx Ty Tz

break;

}

The rotational component of the transform is given either by the R matrix, or by the set E of euler angles. The T vector is the translation component.

If TransformSystem = “Absolute”, then the bone and node transforms are given in the absolute world coordinate system.

If TransformSystem = “Relative to parent”, then the bone and node transforms are given in the coordinate systems of the parent bone or node, respectively (or, if there is no parent, in the absolute world system).

The Euler angles are given in degrees or in radians, depending on the AngleUnits setting. The order of Euler angles is defined by the EulerOrder setting.

The bone transform is the one used for calculation of mesh deformation.The node transform is given only for reference.

}

break;

case “Mesh (absolute)”:

for ( int v = 0; v < Nv; v++ ) {

Vx Vy Vz

The [absolute world] coordinates of the vertex #v

}

break;

case “Mesh (bones c.s)”:

for ( int b = 0; b < Nb; b++ ) {

b Nvb

The bone index and the number of vertices affected by this bone

for ( int i = 0; i < Nv:sub:`b`; i++ ) {

v Vx Vy Vz

The vertex index and the coordinates of this vertex in the coordinate system of bone #b

}

}

break;

}

}

End animation file