BVH Main Panel

 

• Load And Retarget: Load a BVH file and retarget the animation to the active armature. This is the main entry point for the add-on.
• Load BVH File: Load a BVH file. This can be done even if no armature is selected.
• Rename Selected From Active: Rename and rescale the bones of the selected (source) armature to match the active (target) armature.
• Load And Rename BVH File: Load a BVH file and rename the bones to match the active armature.
• Retarget Selected To Active: Retarget the animation of the selected (source) armature to the active (target) armature.

Normally it is sufficient to use the first button. The other four are normally only used for trouble-shooting problems.

Load And Retarget

Select the armature and press Load And Retarget.

A file selector appears. Select the BVH file that you want to retarget and press Load And Retarget.

 After a while the animation is loaded and the character moves. Note the keyframes in the timeline.

Tip: Loading an animation to a high-poly character can take quite a long time, because the viewport is updated after each frame that is loaded. You can speed up the loading considerably (typically by a factor of ten or more) if you put all meshes in a separate collection which is excluded from the scene when the animation is loaded. In this case, the meshes don't belong to the scene at load time and don't have to be updated. The DAZ importer automatically creates a separate collection for the meshes to make it easy to exclude them from the scene, cf. https://diffeomorphic.blogspot.com/2020/01/posing-performance.html.

The import options

Start Frame

First frame in the BVH file to be used. Frames before this are ignored.

Last Frame

Last frame in the BVH file to be used. Frames after this are ignored. If the length of the BVH animation is shorter that this, the animation is not truncated.

Source Rig Orientation 

(X,Y,Z) are the Euler angles for rotating the rest pose of the armature in the BVH file to the Blender default (+Z up and -Y forward). The armatures must be oriented in the Blender way for retargeting to work. The default values work if the source rig orientation is +Y up and +Z forward.

Armatures in rest pose from two different bvh files, imported with Source Rig Orientation = (0, 0, 0). The left armature has +Y up and +Z forward, the right has +Y up and +X forward.

The same armatures imported with Source Rig Orientation = (90, 0, 0) and (90, 0, 90), respectively. Both armatures are oriented with the Blender convention, +Z up and -Y forward.

The pictures above show two armatures imported from different BVH files with the appropriate values of Source Rig Orientation.

Subsample

Only import every n:th frame, where n is the Subsample Factor. This can be used for quickly previewing an animation. If Use Default Subsample is enabled, the subsample factor is chosen to match the frame rate in Blender with the BVH file .

Source Rig

Select the type of rig in the BVH file, in order to find the correspondence between bones in the source and target armatures. If Auto Source is enabled, the add-on will attempt to identify the armature based on bone names.

If Auto Source is disabled, two drop-down lists appear which allow you to choose the source armature type and the source T-pose. If the Source Armature is set to Automatic, the add-on attempts to identify the bones based on the bone hierarchy and bone locations in the reference T-pose.

If the armature in the bvh file has a reasonable rest pose, the T-pose should be set to Default. This is the case for most bvh files. However, in some cases, e.g. the male bvh files from ACCAD and bvh files exported from Endorphin, the rest pose is very strange. In that case we must specify the rest pose manually.

Target Rig

Select the type of the active, in order to find the correspondence between bones in the source and target armatures. If Auto Target is enabled, the add-on will attempt to identify the bones based on the bone hierarchy and bone names.

If Auto Target is disabled, two drop-down lists appear which allow you to choose the source armature type and the source T-pose. If the Target Armature is set to Automatic, the add-on attempts to identify the bones based on the bone hierarchy and bone locations in the reference T-pose.

If the target armature has a reasonable rest pose, the target T-pose should be set to Default. However, if we for some reason want to retarget the animation to an armature with a strange rest pose, we could specify that T-pose here. In that case the target rig could be set to Automatic, because bone identification takes place when the armature is in the reference T-pose.

Scale

Animation of translations depend on the scale of the character and the units used. The Scale value scales location f-curves. If Auto Scale is enabled, the Scale value is determined by matching the lengths of the left thigh bones. The reason for this choice is that the thigh can be readily identified (unlike e.g. the spine bones), and that it gives a reasonable scale for walk-cycles.

If an animation has been imported with the wrong scale factor, it can easily be fixed afterwards in the graph editor; just scale the location f-curves in the y direction.

Bend Positive

Mocap data can be flawed and retargeting is imperfect, especially when the proportions of the target character differs significantly fom the character in the bvh file. In particular, elbows and knees may bend backwards, which looks very strange. If Bend Positive is enabled, the bending angles for elbows and knees are constrained to be positive.

Time Scale

Scale the animation in time with the Time-Scale Factor, i.e. scale all f-curves in the x direction. Can be used together with the Subsample factor to create an animation with fewer keyframes but with the same timing.

Time-scaling the animation when it is loaded has a major advantage compared to simply scaling the f-curves in the graph editor: additional keyframes are added when needed. In the picture below the hip bone's y quaternion value jumps from +1 to -1 between frames 10 and 11. However, this does not reflect a jump in the real rotation, but is merely the way quaternions work; the same rotation can be represented by two different quaternions.

If we time scale all f-curves by a factor two, frames 20 and 22 have the two different quaternion representations for the same rotation. However, in the intermediate frame 21 the y component is 0 (halfway between +1 and -1), which corresponds to a completely different rotation. If we instead import the animation with Time Scale = 2, an extra keyframe is added at frame 21 to make the animation smooth.

Simplify F-Curves

If this option is enabled, unnecessary keys are removed from the f-curves. A key is deemed unnecessary if removing it changes the frame by Max Loc Error (for location f-curves) or Max Rot Error (for rotation f-curves).

• Only Visible F-Curves: Simplification only affects visible f-curves.
• Only Selected Bones: Simplfication only affects f-curves for selected bones.
• Only Between Markers: Simplifcation only affects frames between two selected markers on the time-line.
• Max Loc Error: Maximal error for location f-curves.
• Max Rot Error: Maximal error for rotation f-curves, in degrees (for Euler angles). If the rotation is described by quaternions, the error is divided by 180.

Load BVH File

This button loads a BVH file and creates a new armature with the animation. It is the only button that can be used even if no armature is selected. When the button is pressed, a file selector appears. The import options is a subset of the Load And Retarget options.

An armature with the specified animation is created. The bone names are those in the bvh file.

Rename Selected From Active

This and the following buttons are for trouble-shooting retargeting problems.

 

Select the target armature (the armature to which we want to retarget the animation, and make sure that source armature is also selected (the armature with the BVH animation, loaded with the Load BVH File button). Press Rename Selected From Active.

The options in the pop-up menu have the same meaning as in the Load And Retarget button.

All bones of the source armature have been renamed to standard names and the armature has been scaled to the size of the target armature.

Load And Rename BVH File

This button combines the two previous buttons.

With the final target armature selected, press Load And Rename BVH File (.bvh).

Choose the bvh file in the file selector. The options are the same as for Load And Retarget.

The animation is now imported at the right size and with standard bone names.

Retarget Selected To Active

The source armature is the rescaled and renamed armature with the bvh animation, and the target armature is the armature with meshes that will receive the animation.

With the source armature selected and the target armature active, press Retarget Selected To Active.

A pop-up appears.

The target armature now conforms with the source armature as far as the different body statures allow.

The final four buttons are mainly for trouble-shooting problems, by dividing the retargeting process into separate steps.

Load And Retarget = Load And Rename BVH File + Retarget Selected To Active

and

Load And Rename BVH File = Load BVH File + Rename Selected From Active.