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
