Edit

Input animation file format — MRTK2

  • Article

Overall structure

The input animation binary file begins with a 64 bit integer magic number. The value of this number in hexadecimal notation is 0x6a8faf6e0f9e42c6 and can be used to identify valid input animation files.

The next eight bytes are two Int32 values declaring the major and minor version number of the file.

The rest of the file is taken up by animation data, which may change between version numbers.

Section Type
Magic Number Int64
Major Version Number Int32
Minor Version Number Int32
Animation Data see version section

Version 1.1

The input animation data consists of three boolean values that indicate whether the animation contains Camera, Hand, and Eye Gaze data, followed by a sequence of animation curves. The curves present depends on the values of these booleans. Each curve can have a different number of keyframes.

Section Type Notes
Has Camera Pose Boolean
Has Hand Data Boolean
Has Eye Gaze Boolean
Camera Pose Curves Only if Has Camera Pose is true
Hand Tracked Left Boolean Curve Only if Has Hand Data is true
Hand Tracked Right Boolean Curve Only if Has Hand Data is true
Hand Pinching Left Boolean Curve Only if Has Hand Data is true
Hand Pinching Right Boolean Curve Only if Has Hand Data is true
Hand Joints Left Joint Pose Curves Only if Has Hand Data is true
Hand Joints Right Joint Pose Curves Only if Has Hand Data is true
Eye Gaze Ray Curves] Only if Has Eye Gaze is true

Version 1.0

The input animation data consists of a sequence of animation curves. The number and meaning of animation curves is fixed, but each curve can have a different number of keyframes.

Section Type
Camera Pose Curves
Hand Tracked Left Boolean Curve
Hand Tracked Right Boolean Curve
Hand Pinching Left Boolean Curve
Hand Pinching Right Boolean Curve
Hand Joints Left Joint Pose Curves
Hand Joints Right Joint Pose Curves

Joint pose curves

For each hand a sequence of joint animation curves is stored. The number of joints is fixed, and a set of pose curves is stored for each joint.

Section Type
None Pose Curves
Wrist Pose Curves
Palm Pose Curves
ThumbMetacarpalJoint Pose Curves
ThumbProximalJoint Pose Curves
ThumbDistalJoint Pose Curves
ThumbTip Pose Curves
IndexMetacarpal Pose Curves
IndexKnuckle Pose Curves
IndexMiddleJoint Pose Curves
IndexDistalJoint Pose Curves
IndexTip Pose Curves
MiddleMetacarpal Pose Curves
MiddleKnuckle Pose Curves
MiddleMiddleJoint Pose Curves
MiddleDistalJoint Pose Curves
MiddleTip Pose Curves
RingMetacarpal Pose Curves
RingKnuckle Pose Curves
RingMiddleJoint Pose Curves
RingDistalJoint Pose Curves
RingTip Pose Curves
PinkyMetacarpal Pose Curves
PinkyKnuckle Pose Curves
PinkyMiddleJoint Pose Curves
PinkyDistalJoint Pose Curves
PinkyTip Pose Curves

Pose curves

Pose curves are a sequence of 3 animation curves for the position vector, followed by 4 animation curves for the rotation quaternion.

Section Type
Position X Float Curve
Position Y Float Curve
Position Z Float Curve
Rotation X Float Curve
Rotation Y Float Curve
Rotation Z Float Curve
Rotation W Float Curve

Ray curves

Ray curves are a sequence of 3 animation curves for the origin vector, followed by 3 animation curves for the direction vector.

Section Type
Origin X Float Curve
Origin Y Float Curve
Origin Z Float Curve
Direction X Float Curve
Direction Y Float Curve
Direction Z Float Curve

Float curve

Floating point curves are fully fledged Bézier curves with a variable number of keyframes. Each keyframe stores a time and a curve value, as well as tangents and weights on the left and right side of each keyframe.

Section Type
Pre-Wrap Mode Int32, Wrap Mode
Post-Wrap Mode Int32, Wrap Mode
Number of keyframes Int32
Keyframes Float Keyframe

Float keyframe

A float keyframe stores tangent and weight values alongside the basic time and value.

Section Type
Time Float32
Value Float32
InTangent Float32
OutTangent Float32
InWeight Float32
OutWeight Float32
WeightedMode Int32, Weighted Mode

Boolean curve

Boolean curves are simple sequences of on/off values. On every keyframe the value of the curve flips immediately.

Section Type
Pre-Wrap Mode Int32, Wrap Mode
Post-Wrap Mode Int32, Wrap Mode
Number of keyframes Int32
Keyframes Boolean Keyframe

Boolean keyframe

A boolean keyframe only stores a time and value.

Section Type
Time Float32
Value Float32

Wrap mode

The semantics of Pre- and Post-Wrap modes follow the Unity WrapMode definition. They are a combination of the following bits:

Value Meaning
0 Default: Reads the default repeat mode set higher up.
1 Once: When time reaches the end of the animation clip, the clip will automatically stop playing and time will be reset to beginning of the clip.
2 Loop: When time reaches the end of the animation clip, time will continue at the beginning.
4 PingPong: When time reaches the end of the animation clip, time will ping pong back between beginning and end.
8 ClampForever: Plays back the animation. When it reaches the end, it will keep playing the last frame and never stop playing.

Weighted mode

The semantics of the Weighted mode follow the Unity WeightedMode definition.

Value Meaning
0 None: Exclude both inWeight or outWeight when calculating curve segments.
1 In: Include inWeight when calculating the previous curve segment.
2 Out: Include outWeight when calculating the next curve segment.
3 Both: Include inWeight and outWeight when calculating curve segments.