skeleton

Tool tools/formats/skeleton.py (program, Formats). Find skeletons and poses in a model or animation file: arrays of parent indices, and runs of unit quaternions.

Run it with ./gameframe run skeleton ARGS or python3 tools/formats/skeleton.py. Source on GitHub.

Its own help

This is the help text in the tool itself, as ./gameframe tool skeleton prints it.

Find skeletons and poses in a model or animation file: arrays of parent indices, and runs of
unit quaternions.

Usage: skeleton.py FILE [--min N]          parent arrays and quaternion runs, at least N joints (8)
       skeleton.py FILE --at 0xOFFSET --width 1|2|4 [--count N]    print one parent array as a tree

A skeleton is usually stored as a list of joints in which each joint names its parent by
index, and every parent comes before its children. The root has no parent, written as -1 (all
bits set). This tool looks for that shape: a run that starts at -1 and in which every later
entry is smaller than its own position. It tries 8-bit, 16-bit and 32-bit entries in both
byte orders. A run of zeros also has the shape, so a run needs at least three different parents
to count. A run must also look like a skeleton: at most two roots, a depth of at least three,
and no joint with more than sixteen children. Other data with the same shape (indices, flags)
rarely passes all three.

Many formats keep each joint as a record: a name, the parent index, then the pose. The parent
indices are then spread through the file, often at varying spacing when the names differ in
length. The tool also looks for these: a 32-bit parent index followed directly by a unit
quaternion, repeated in file order with every parent before its child. The printable text just
before each record is shown as the joint's name.

Joint rotations are quaternions: four floats whose squares add up to one. A bind pose, or one
sample of an animation, is a run of them at a fixed spacing, alone (16 bytes apart) or with a
translation and a scale (28 to 64 bytes apart). The tool reports runs of such quaternions with
the spacing. Compressed animation does not show here: quantised rotations are 16-bit integers
or packed into 48 or 64 bits. Read the decoder for those.

The joint names are often near the skeleton, in the same order. Strings such as Bip01, Bone,
pelvis, spine or head are listed with their offsets. Standard library only.

Named by

Skills: re-format.

Agents: re-decoder.