From BlenderWiki

Jump to: navigation, search

Motion Capture Tools add-on

Technical Infomation and Overview

Files Structure

The addon contains 4 python files:
Contains the RNA Property declarations, UI Panel Coding, Operator declaration, and registers/imports itself and the other modules.
Contains the main retargeting functions, which are called by the operators.
Contains functions (including property update functions) for the Post Retarget Fixes
Contains functions for the various extra tools

Property Declarations in

New PropertyGroup Types

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)
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)
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
Stores the hierarchy mapping. Used by the End User bones.
  • name: Name of the mapped bone on the Performer Rig.

New RNA Properties

CollectionProperty using MocapConstraint GroupProperty, stores the Post Retarget Fixes
PointerProperty using AnimationStitchSettings GroupProperty, stores the animation stitch settings for the operators
StringProperty that defines the currently active retarget. Update function NLASystemInitialize in retarget module that switches the NLA tracks accordingly
CollectionProperty using MocapNLATracks GroupProperty, stores the retargeted animations and their NLA Tracks on the armature
Boolean which stores if we are using Advanced Retargeting
Int which indicates step size for retargeting. Useful for faster retargeting and previewing.
String which stores the hierarchy mapping from Performer to End User
Collection property which stores the hierarchy mapping from End User to Performer
Boolean which indicates if this bone is a "foot" bone and should not skate.
Boolean which indicates if the group that this bone is deforming needs to be fixed for twisting
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.

  • 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 set for the performer bones. Maybe also enduser's armature advancedRetarget and step properties.

  • 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
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.