From BlenderWiki

Motion Capture Tools add-on

Technical Infomation and Overview

Files Structure

The addon contains 4 python files:

__init__.py

Contains the RNA Property declarations, UI Panel Coding, Operator declaration, and registers/imports itself and the other modules.

retarget.py

Contains the main retargeting functions, which are called by the operators.

mocap_constraints.py

Contains functions (including property update functions) for the Post Retarget Fixes

mocap_tools.py

Contains functions for the various extra tools

Property Declarations in __init__.py

New PropertyGroup Types

MocapConstraint

Contains all the properties used by the the Post-Retarget Fixes

• Name: Name given to the fix. (String)
• constrained_bone: Name of bone that is effected by the fix. (String)
• constrained_boneB: Name of secondary bone that is used by the fix. (String)
• s_frame: Frame where fix's influence begins. (Int)
• e_frame: Frame where fix's influence ends. (Int)
• smooth_in: Amount of frames to use when blending into the fix. (Int)
• smooth_out: Amount of frames to use when blending out of the fix. (Int)
• targetMesh: Name of Mesh object used by Stay Above fix. (String)
• active: Active status of fix. (Bool)
• show_expanded: Is fix fully displayed in the UI. (Bool)
• targetPoint: Target location for Maintain Position fix. (FloatVector)
• targetDist: Amount of distance to maintain for Keep Distance fix. (Float)
• targetSpace: Type of space to evaluate owner/target in. (Enum: "WORLD","LOCAL","constrained_boneB")
• type: Type of fix. (Enum: "point","freeze","floor","distance")
• real_constraint: Name of Blender constraint used to implement fix. (String)
• real_constraint_bone: Name of bone where Blender constraint is. (String)

AnimationStitchSettings

Contains settings for Animation Stitching Operator

• first_action: First action to stitch (String)
• second_action: Second action to stitch (String)
• blend_frame: Frame to blend the animation (Int)
• blend_amount: Amount of frames to use to smooth into the second animation (Int)
• second_offset: Start frame/amount of offset to use for the second animation (Int)
• stick_bone: Bone that will maintain its global position during the transition (String)

MocapNLATracks

Stores the data associated with each retarget

• name: Name given by the user for the retarget
• base_track: Name of the base motion capture action, which contains the retargeted action
• auto_fix_track: Name of the action where Post Retarget fixes are baked to
• manual_fix_track: Name of the action where Manual fixes are created by the user
• stride_action: Name of the stride_bone action that is associated with the retarget

MocapMapping

Stores the hierarchy mapping. Used by the End User bones.

• name: Name of the mapped bone on the Performer Rig.

New RNA Properties

bpy.types.Armature

mocap_constraints

CollectionProperty using MocapConstraint GroupProperty, stores the Post Retarget Fixes

stitch_settings

PointerProperty using AnimationStitchSettings GroupProperty, stores the animation stitch settings for the operators

active_mocap

StringProperty that defines the currently active retarget. Update function NLASystemInitialize in retarget module that switches the NLA tracks accordingly

mocapNLATracks

CollectionProperty using MocapNLATracks GroupProperty, stores the retargeted animations and their NLA Tracks on the armature

advancedRetarget

Boolean which stores if we are using Advanced Retargeting

frameStep

Int which indicates step size for retargeting. Useful for faster retargeting and previewing.

bpy.types.Bone

map

String which stores the hierarchy mapping from Performer to End User

reverseMap

Collection property which stores the hierarchy mapping from End User to Performer

foot

Boolean which indicates if this bone is a "foot" bone and should not skate.

twistFix

Boolean which indicates if the group that this bone is deforming needs to be fixed for twisting

bpy.types.PoseBone

IKRetarget

Boolean which indicates if this bone is in an IK chain or has an IK constraint. Has the toggleIKBone update function, which adds an IK constraint if not existent, or removes a previously created one.

Useful Functions within the Modules

Here is a number of functions, sorted by module, that you might want to use in your own scripts.

retarget.py

• totalRetarget(performer_obj, enduser_obj, scene, s_frame, e_frame)

performer_obj: Object which is in an armature, that contains the desired source animation

enduser_obj: Object which is in an armature, that will recieved the retargeted animation

scene: bpy.types.Scene object. Usually just context.scene

s_frame, e_frame: Start and End frames for retargeting range.

You will want to have Bone.map set for the performer bones. Maybe also enduser's armature advancedRetarget and step properties.

mocap_tools.py

• class NdVector

An implementation of n-dimension Vectors. Supports operation similar to mathutils.Vector such as multiplication and division by scalar, dot product, length, squared length, random access to member i, resize_2d and copy.

• crossCorrelationMatch(curvesA, curvesB, margin)

Implements the discrete Cross Correlation Algorithm Wikipedia - Cross Correlation

Useful for finding common ground/loops in 2 animations (that can be the same).

curvesA, curvesB - bpy_collection/list of fcurves to analyze. Auto-Correlation is when they are the same.

margin - When searching for the best "start" frame, how large a neighborhood of frames should we inspect (similar to epsilon in Calculus)

Returns: Recommended start and length of the crossed animation and curvesA transferred to list of NdVector's (useful if Auto-Correlation)

• autoloop_anim

Uses auto correlation (cross correlation of the same set of curves) and trims the active_object's fcurves. Except for location curves (which in mocap tend to be not cyclic, e.g. a walk cycle forward).

Transfers the fcurve data to a list of NdVector (length of list is number of fcurves), and calls the cross correlation function. Then trims the fcurve accordingly.

IN: Nothing, set the object you want as active and call. Assumes object has animation_data.action!

OUT: Trims the object's fcurves (except location curves).

• denoise_median

Implementation of non-linear median filter, with variable kernel size

Double pass - one marks spikes, the other smooths them

Expects sampled keyframes on everyframe

IN: None. Performs the operations on the active_object's fcurves. Expects animation_data.action to exist!

OUT: None. Fixes the fcurves "in-place".

• rotate_fix_armature(arm_data)

Recieves bpy.types.Armature, and rotates all bones by 90 degrees along the X axis

This fixes the common axis issue BVH files have when importing.

IN: Armature (bpy.types.Armature)

• fcurves_simplify(context, obj, sel_opt="all", error=0.002, group_mode=True)

Main function of simplification, which called by Operator

IN:

sel_opt- either "sel" (selected) or "all" for which curves to effect

error- maximum error allowed, in fraction (20% = 0.0020, which is the default) i.e. divide by 10000 from percentage wanted.

group_mode- boolean, to analyze each curve seperately or in groups, where a group is all curves that effect the same property/RNA path

OUT: Converts the samples to Bezier curves in the fcurves.