Coordinate spaces and transforms

This page gives an overview of the coordinate systems used by SMF.

World

Note SMF uses a right-handed coordinate system, as shown in the image below.

Note In the image we see that the colors of the x, y and z axes in the SMF Model Tool are g, b, r respectively.

Good-to-know The rig is stored in the SMF file using the world-space DQs of each node.

Local

The local space is the bone space. Its origin is located at the parent node.

This image shows that the bone axis is oriented along the local x axis.

If we output the offsets and location rotations using show_debug_message, we get the following output:

NodeInfo - Node: 0 - World: { { 0,0.00,0 },  } - Local: { { 0,0,0 },  } - LocalRot: 0
NodeInfo - Node: 1 - World: { { -0.00,0.00,8.00 },  } - Local: { { -0.00,-0.00,8.00 },  } - LocalRot: 270
NodeInfo - Node: 2 - World: { { 4.00,0.00,8.00 },  } - Local: { { 0.00,0.00,-4.00 },  } - LocalRot: 90.00
NodeInfo - Node: 3 - World: { { 0.00,0.00,12.00 },  } - Local: { { 4.00,-0.00,0.00 },  } - LocalRot: 0
NodeInfo - Node: 4 - World: { { 4,0.00,-0.00 },  } - Local: { { 4,0.00,-0.00 },  } - LocalRot: 360

Let's take a look at bone 2. Its world coordinates are (4, 0, 8). That's easy to see.
The local coordinates are a bit harder to interpret. To interpret those correctly we need to look at the parent node's axes. In this case, the parent node is node 1.
Node 1's x axis is oriented along the world z axis and its z axis is oriented along the world's negative x axis.
Because of this node 2 is on the negative side of the local z axis; it has local coordinates (0, 0, -4). Node 3 is oriented along the z axis in world space which corresponds to its parent node's (node 1) local x axis.
Therefore node 3 has local coordinates (4, 0, 0).

Animations

Animations are stored in a delta local DQ that is the difference between the final node transform and the rig node (or bind pose) transform.
The formula is:

keyframe_DQ = delta_local_DQ * bind_DQ;

Important The delta local dual quaternion contains both a rotation and a translation!

Good-to-know It is the final DQ in local space that's stored in the SMF file.

Untransformed Bone

The untransformed bone coincides with the bone in its bind position. The delta local dual quaternion is therefore the identity DQ.

angle: 0 - translation:{ { 0,0,0 },  }

Transformed Bone

The transformed bone can be anywhere in local space. The following image shows bone3/node3 rotated by the local (and in this case also global) y axis. The translation is (-4, 0 4). This is the change in location of the node in local space.

angle: 89.69 - translation:{ { -3.98,-0.00,4.00 },  }