Samples\CycleAnalysis\CycleCreator.py

# Copyright 2015 Autodesk, Inc.  All rights reserved.
# Use of this software is subject to the terms of the Autodesk license agreement 
# provided at the time of installation or download, or which otherwise accompanies
# this software in either electronic or hard copy form.
#
# Script description:
# Advanced script showing how to use cycle creator via script.  
# 
# You will find here:
#    - What is cycle creator?  
#    - What can user specified?
#    - What is the exposed API?
#    - What is the pre-condition if using the API?  
#   - What is the difference between using API and UI?
#    - Is it recommended to add zero key?
#   - How to use the API?
#
# Topic: FBCycleCreator
#
 
'''
- What is cycle creator?  
 
    Cycle creator is a tool to automate the progress that an animator creates a 
    character animation cycle, which including below steps:
    1) cut assigned time scope of character animation and copy to new take;
    2) align copied animation to start from time ZERO (optional);
    3) create a new layer;
    4) add key in the start frame; 
    5) copy the character pose of start frame and paste it to the end frame;
    6) add key in the end frame;
    7) find the frame with most different pose from the pose in start frame, 
       and add zero key on that frame (optional).
    
- What can user specified?
 
    1) in step#1 
        - the time scope 
        - the name of the new take
    2) in step#2 
        - whether to align to time ZERO;
    3) in step#5
        - how to match the referenced joint according to T x y z R?
        - which referenced joint (limited to IK) is chosen?
    4) in step#7
        - whether want to add zero key?
        
- What is the exposed API?
    
    /** Create animation cycle for current character if pChar is
    *   NULL, else for the character assigned by pChar; during 
    *   the time scope between pStartTime and pEndTime.
    *   \param pStartTime Start time of the cycle
    *   \param pEndTime End time of the cycle
    *   \param pChar Target character, if it is NULL, try to use current character
    *   \param pMoveStartToZero Whether move start time to zero time
    *   \param pAddZeroKey Whether add zero key
    *   \param pNewTakeName The name used to create the new take.
    *   \param pReferencedIK The IK that used as referenced object in pose pasting.
    *   \param pPasteTx Whether consider Translation X on referenced IK when doing pose pasting
    *   \param pPasteTy Whether consider Translation Y on referenced IK when doing pose pasting
    *   \param pPasteTz Whether consider Translation Z on referenced IK when doing pose pasting
    *   \param pPasteR Whether consider Rotation on referenced IK when doing pose pasting
    *   \param pPasteG Whether respect Gravity when doing pose pasting (Translation = Global XZ / Rotation = Global Y).  Note: if G is true then Ty will be forced changed to false.
    *   \return true if successful.
    */
    bool FBCycleCreator::CreateCycle(   FBTime pStartTime, 
                                        FBTime pEndTime,
                                        FBCharacter* pChar = NULL, 
                                        bool pMoveStartToZero = false,
                                        bool pAddZeroKey = true, 
                                        const char* pNewTakeName = "", 
                                        FBModel* pReferencedIK = NULL, 
                                        bool pPasteTx = true, 
                                        bool pPasteTy = false,
                                        bool pPasteTz = true, 
                                        bool pPasteR = true,
                                        bool pPasteG = true );
 
- What is the pre-condition if using the API?  And what is the difference from using UI?
 
    From the UI, there are 4 preconditions:
 
    1) Current character is not None;
    2) Current character is driven by control rig;
    3) the control rig has animatioin.
    4) the local marks has been selected.
 
    From the script,
    
    If don't assign character, then there must be a valid current character fitting 
    above top 3 preconditions; else assigned character must fit top 3 preconditions.
 
    The 4th condition is replaced by the pStartTime and pEndTime parameters. As
    long as pStartTime and pEndTime are assigned, it knows where to cut the animation. 
 
- Is it recommended to add zero key?
 
    Cycle Creator only adds one zero key considering the difference of pose, if 
    that fit your requirement, then the answer is yes.    Else, you can skip it
    and add the zero keys by yourself.
 
'''
 
from pyfbsdk import *
import os, inspect, sys
 
cycle = FBCycleCreator()
start = FBTime(0)
end = FBTime(0)
end.SetFrame(15)
 
# Note: Make sure there is at least one character in scene
# Senarior#1.  Assgin start time and end time (minimum parameters)
#cyc.CreateCycle(start, end)
 
# Senarior#2.  Assgin start time, end time and a character
#scene = FBSystem().Scene
#if len(scene.Characters):
#    char = scene.Characters[0]
#    print char.Name
#cyc.CreateCycle(start, end, char)
 
# Senarior#3.  Assgin all parameters
scene = FBSystem().Scene
if len(scene.Characters):               
    char = scene.Characters[0]
    print(char.Name)
model = FBFindModelByLabelName( 'Mia_Ctrl:RightAnkleEffector' ) 
success = cycle.CreateCycle(start, end, char, True, False, "new take name", model, True, False, True, True, True)
print(success)