Crate bvh_anim

About this library

A small library for loading and manipulating BioVision motion files.

The bvh file format

The Bvh file format is comprised of two main sections: the 'Heirarchy' section, which defines the joints of the skeleton, and the 'Motion' section, which defines the motion values for each channel.

This project contains some samples in the data directory.

Heierarchy

The 'Heirarchy' section defines the skeleton as a tree of joints, where there is a single root joint, and a chain of child joints extending out from each joint, terminated by an 'End Site' section.

Each joint has:

• A list of channels, which are the degrees of freedom in which the joint may move. Channels are listed in the order in which the transformation should be applied to the global transform for the root.
• An offset, which is the vector distance from the parent joint.
• An optional end site, which is used to cap off a chain of joints. This is only used to calculate the length of the final bone in the chain.

HEIRARCHY
ROOT <Root-name>
{
    OFFSET <Root-offset-x> <Root-offset-y> <Root-offset-z>
    CHANNELS <Num-root-joint-channels> Xposition Yposition <other-root-channels ...>
    JOINT <Joint-1-name>
    {
        OFFSET <Joint-1-offset-x> <Joint-1-offset-y> <Joint-1-offset-z>
        CHANNELS <Num-joint-1-channels> <Joint-1-channels ...>
        JOINT <Joint-2-name>
        {
            OFFSET <Joint-2-offset-x> <Joint-2-offset-y> <Joint-2-offset-z>
            CHANNELS <Num-joint-2-channels> <Joint-2-channels ...>
            JOINT <Joint-with-end-site>
            {
                OFFSET ...
                CHANNELS ...
                End Site
                {
                     OFFSET <end-site-offset-x> <end-site-offset-y> <end-site-offset-z>
                }
            }
            ... More child joints
        }
        JOINT <Joint-3-name>
        {
            OFFSET <Joint-3-offset-x> <Joint-3-offset-y> <Joint-3-offset-z>
            CHANNELS <Num-joint-3-channels> <Joint-3-channels ...>
            ... More child joints
        }
        ... More child joints
    }
    ... More child joints
}

Note that the bvh data is defined in terms of a right-handed coordinate system, where the positive y-axis is the up vector.

Motion

The MOTION section of the bvh file records the number of frames, the frame time, and defines the full range of motions for each channel, frame by frame.

MOTION
Frames: <num-frames>
Frame Time: <frame-time>
<frame-0-channel-0-value> <frame-0-channel-1-value> <frame-0-channel-2-value> ...
<frame-1-channel-0-value> <frame-1-channel-1-value> <frame-1-channel-2-value> ...
<frame-2-channel-0-value> <frame-2-channel-1-value> <frame-2-channel-2-value> ...
⋮

The frame time is recorded in seconds, and tells the animation system how long each frame of the animation should last for. This value is usually around 0.033333333, which is close to 30 frames per second.

The list of motion values is a matrix, where each row represents a frame. Each column of the row represents a transformation around the channel axis - for example a motion value of 130.0 for an Xposition channel would correspond to a rotation of 130.0 degrees around the x-axis.

Note that rotations are conventionally in degrees, although it will be up to your application how to interpret each motion's value.

Using this library.

Creating a Bvh struct:

There are a few ways to create a Bvh struct:

• You can use the from_reader function, which will parse a BufRead as a bvh file. The from_bytes function is a convenient wrapper function to parse an in-memory slice of bytes as a bvh file. Note that the file does not need to be strictly UTF-8, although it should be an ascii-compatible encoding. These functions are also available as associated methods on the Bvh type directly as Bvh::from_reader Bvh::from_reader and Bvh::from_bytes

• You can use the bvh! macro to construct a Bvh instance in your source files using the same syntax as you would use for a standard bvh file.

• You can use the builder module to dynamically construct a bvh. This is useful for converting data from other formats into a Bvh struct.

• You can create an empty Bvh using the Bvh::new or Default::default Default::default methods.

Other operations:

Once you have a valid Bvh struct, there are a number of ways you can inspect and manipulate it:

• The Bvh::joints method can be used to iterate through each Joint of the Bvh. Each Joint can be inspected through its JointData JointData, which can be obtained with the Joint::data method.

• The Bvh::frames method returns a Frames iterator over each frame of the animation. A Frame can only be indexed by a Channel belonging to an associated Joint of the Bvh, although you can convert it into an &[f32] using the Frame::as_slice method.

• You can serialise the Bvh into a Write type using the Bvh::write_to Bvh::write_to method. There is also the Bvh::to_bstring method, which converts the Bvh into a BString. Various aspects of the formatting can be customised using the WriteOptions type, such as the line termination style, indentation method, and floating point accuracy.

Examples

This library comes with some example applications, which can be viewed on Github.

Other resources

• More information on this file format can be found here.
• A large library of bvh files is freely available from CMU's motion capture database CMU's motion capture database.

Modules

builder	Defines a Builder struct used to build a Bvh dynamically.
errors	Errors which may occur when manipulating Bvh files.
ffi	The ffi interface to the bvh_anim crate. You must enable the ffi feature to access this module.
write	Contains options for bvh file formatting.

Macros

bvh	Create a new Bvh object using a macro literal. Useful for testing.

Structs

Bvh	A complete bvh file.
Channel	A Channel composed of a ChannelType and an index into the corresponding motion data.
Frame	A wrapper for a slice of motion values, so that they can be indexed by Channel.
Frames	An iterator over the frames of a Bvh.
FramesMut	A mutable iterator over the frames of a Bvh.
Joint	A view of a joint which provides access to various relevant data.
JointMut	A view of a joint which provides mutable access.
JointName	Wrapper struct for the Joint name type.
Joints	An iterator over the Joints of a Bvh skeleton.
JointsMut	A mutable iterator over the Joints of a Bvh skeleton.

Enums

Axis	An enum which represents an axis along a direction in 3D space.
ChannelType	The available degrees of freedom along which a Joint may be manipulated.
JointData	Internal representation of a joint.

Functions

from_bytes	Parse a sequence of bytes as if it were an in-memory Bvh file.
from_reader	Loads the Bvh from the reader.
from_str	Parse a str as if it were an in-memory Bvh file.