BVH Tools for Unity

BVH Tools for Unity let you record and export motion data from avatars or skeletons to BVH files so they can be edited with Blender or other programs. The included animation loading component makes it possible import BVH files into Unity at runtime.

Setup

The BVHRecorder component should usually run last, so that it can capture any modifications to bone rotations made by other scripts. To achieve this, after importing the scripts, add the BVHRecorder component at the end of the script execution order list. You can find this list under Edit, Project Settings, Script Execution Order. Press the + button and select the BVHRecorder. It should appear at the end of the list. Finally click Apply.

Recording

The most simple way to get started is to attach the "BVH Recorder" component to an avatar. Set the "Target Avatar" field to refer to the avatar, and set a filename and path for the BVH file. Then play the scene and check the "Capturing" box. You can uncheck and check it as you like. Captured motion data will be added at the end. Once you are happy with your motion data, press the save button in the inspector panel.

All fields have tooltips, so if you want to delve deeper, please take a look at them. The component also provides a simple API. Looking at the corresponding Editor script should give something of an overview.

Rest pose

If the bones of the model being recorded do not have rotations of zero in the rest pose, the rest pose in the resulting BVH file can look very odd. As a workaround, exporting the model to VRM format using UniVRM and importing it back into unity will produce a model with zero rotation bones. A short guide about the process can be found here.

Editing

If you want to edit your file in Blender, please enable the "Blender" checkbox for both recording and loading and use the following settings during import into Blender:

Forward: Y Forward
Up: Z Up

When importing files into Blender that were recorded with Blender mode disabled, please use the following settings instead:

Forward: -Z Forward
Up: Y Up

When loading files that were exported from Blender, the Blender checkbox always has to be enabled.

Loading

To load the file back into Unity, attach the "BVH Animation Loader" component to your avatar, set it as the "Target Avatar" and enter the filename. Also check the "Auto Start" box and then play the scene. Your animation should play.

Video

You can watch a quick introduction video on the usage of these Unity components here.

License

This software is distributed under the terms of the MIT license.

About

BVH Tools for Unity was made by Emiliana for Virtual YouTuber purposes, but it can also be used for games or other applications.

API

If you want to control the import and export functionality from your own scripts, you will find all the necessary information in this section.

BVHRecorder

This component can be used to record BVH data and save it to a file.

Animator targetAvatar (required)

This is the only required field. Set the target avatar here.

Transform rootBone

This is usually the hips or pelvis bone. It is the root bone of the skeleton. If not set, it will be automatically detected. However, setting it can be useful to only capture motion for a part of a skeleton.

List<Transform> bones

This list contains the bones for which motion data will be recorded. It can be filled automatically using the getBones() function.

float frameRate

This the how often bone rotations will be recorded every second, when the capturing flag is set to true. The frame duration written to the BVH file is also derived from this.

string directory

This is the directory into which BVH files are written. If left empty, it will be initialized to the standard Unity persistant data path, unless the filename field contains a slash or a backslash, in which case this field will be ignored completely instead.

string filename

This field is used by the saveBVH() function and specifies the filename of the BVH file it will create. If no filename is given, a new one will be generated based on a timestamp. If the file already exists, a number will be appended.

bool overwrite

When this flag is set to true, files will be overwritten. No numbers will be appended to filenames.

bool scripted

Setting this flag will prevent the automatic initialization of this component at startup.

bool capturing

When this flag is set, motion will be captured at the interval given by frameRate. It is possible to pause and resume capturing by setting this flag at any time.

bool blender

This flag changes the coordinate system to match that of Blender instead of the default BVH coordinate system. It is recommended to set this when files are going to be edited in Blender and later loaded back into Unity. It is also enabled by default.

bool enforceHumanoidBones

This makes getBones() only include humanoid bones in the bone list. It is mainly useful to exclude things like hair and skirt bones from the recording, which can make the resulting file a lot bigger.

bool renameBones

Enabling this option will rename humanoid bones to their standard Unity names in the generated file.

bool catchUp

Setting this to true will allow capturing with the capturing flag to speed up after if the frame rate drops, to keep the duration of the captured animation correct. Disabling this flag will ensure that at least as many milliseconds pass after every captured frame, as one frame should require, according to the given frameRate.

int frameNumber (read-only)

This field shows how many frames are currently captured. Clearing the capture will reset this to 0.

string lastSavedFile (read-only)

This field will be set to the filename written to by the saveBVH() function.

void getBones() (usually required)

Unless the list of bones is set manually, this function has to be called to populate the list of bones that will be recorded.

void cleanupBones()

This function removes empty entries from the bones list. It is also called by other functions, so calling it manually is usually not necessary.

void buildSkeleton() (required)

This function builds a spanning tree of game objects covering all selected bones. It always has to be called before capturing and after setting the bones.

void genHierarchy() (required)

This function also has to be called before motion capture. It further prepares hierarchy information about the skeleton built by the previous function.

void captureFrame()

Call this function to record the target avatar's pose at the current frame. Setting the capturing flag to true will automatically call this every frame.

void clearCapture()

Using this function, all previously capture motion data can be discarded.

string genBVH()

Calling this function will return a string containing a BVH file for the captured motion data.

void saveBVH()

This function calls genBVH() and writes the string to the file specified by the filename field.

static Transform getRootBone (Animator avatar)

This function can be used to detect the root bone of an avatar.

static Transform getRootBone (Animator avatar, List<Transform> bones)

This function can be used to detect the root bone of an avatar, given a set of bones.

static void populateBoneMap(out Dictionary<Transform, string> boneMap, Animator targetAvatar)

This function can be used on humanoid avatars to generate a mapping from bones to standard Unity humanoid bone names.

Example

Here is a short example of how you could start the capturing process:

BVHRecorder recorder = gameObject.AddComponent<BVHRecorder>();
recorder.targetAvatar = GetComponent<Animator>();
recorder.scripted = true;
recorder.getBones();
recorder.buildSkeleton();
recorder.genHierarchy();
recorder.capturing = true;

Then, after you are done capturing your animation, you save it to a file:

recorder.capturing = false;
recorder.filename = "motion.bvh";
recorder.saveBVH();

If you want to capture another animation, just clear out the collected data. You can also skip this, if you want to add to your current animation.

recorder.clearCapture();
recorder.capturing = true;

And save it again:

recorder.capturing = false;
recorder.filename = "motion2.bvh";
recorder.saveBVH();

BVHAnimationLoader

This component allows the creation of (legacy) animation clips from BVH files. The skeleton defined in the BVH file should match that of the avatar for which it is being loaded.

Animator targetAvatar (required)

This field specifies the avatar to which the animation should be applied.

string filename

This field specifies the filename from which parseFile() will read the BVH data.

bool blender

This flag has to be enabled to correctly load BVH files exported from Blender or written by the BVHRecorder component with the blender flag set. When Blender is part of the animation workflow, it is usually best to enable this option in both BVHRecorder and BVHAnimationLoader. It is also enabled by default.

float frameRate

When the flag below is set, this frame rate will override that derived from the frame time given in the BVH file.

bool respectBVHTime

When this flag is set, the frame duration will not be overridden by the value set in frameRate.

string clipName

This name will be given to the newly created AnimationClip when loading. If this field is left empty, a name will be generated automatically.

bool standardBoneNames

When this option is enabled, standard Unity humanoid bone names will be mapped to the corresponding bones of the skeleton.

bool flexibleBoneName

When this option is disabled, bone names have to match exactly.

FakeDictionary[] boneRenamingMap

If the bone names of the avatar do not match those in the file and the file doesn't use Unity's standard bone names, but the structure matches otherwise, you can define a mapping of names in this array to rename the bones to match.

public struct FakeDictionary {
    public string bvhName;
    public string targetName;
}

bool autoPlay

If this flag is enabled, animations will start playing as soon as they are loaded.

bool autoStart

If this flag is enabled, an animation is loaded as soon as the script starts running. This also enables the autoPlay flag.

Animation anim

Once an animation has been loaded, the Animation component to which it has been added can be accessed through this field.

AnimationClip clip

This field contains the latest loaded animation clip.

void parseFile() or void parse(string bvhData) (required)

First, the BVH data has to be parsed. These functions do not call any Unity API functions and can safely be called from another thread if some of the animation loading process should be done in the background.

In the case of parseFile(), the BVH data will be loaded from the file specified through the filename field.

void loadAnimation() (required)

This function turns the parsed BVH data into a (legacy) animation clip. If the autoPlay flag is set, it will also start playing the animation right away.

The loaded animation will be added to an Animation component on the target avatar. Calling this function multiple times (e.g. with different parsed files) will add multiple animations to the Animation component, which can all played by accessing it. The name will be assigned from the clipName field or assigned automatically if it is empty.

void playAnimation()

This function plays the animation that was loaded last.

stopAnimation()

This function stops animation playing through the Animation component.

static string getPathBetween(Transform target, Transform root, bool skipFirst, bool skipLast)

This function generates a string containing the path from one game object to another. If the skipFirst flag is set, the first element of the path is discarded. If the skipLast flag is set, the last element of the path is discarded.

Example

It is possible to reuse this component to load multiple animations by calling one of the parsing functions and this function in sequence multiple times.

For example:

BVHAnimationLoader loader = gameObject.AddComponent<BVHAnimationLoader>();
loader.targetAvatar = GetComponent<Animator>();
loader.clipName = "anim1";
loader.filename = "anim1.bvh";
loader.parseFile();
loader.loadAnimation();

loader.clipName = "anim2";
loader.filename = "anim2.bvh";
loader.parseFile();
loader.loadAnimation();

loader.clipName = "anim3";
loader.filename = "anim3.bvh";
loader.parseFile();
loader.loadAnimation();

The loaded animations can then be played through the Animation component:

loader.anim.Play("anim2");