From BlenderWiki

Jump to: navigation, search

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.