Motion Capture Tools add-on
Technical Infomation and Overview
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 __init__.py
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 Bone.map 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)
- 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).
- 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".
- 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.