## FindPeriods

### Introduced

v1.5

### Description

Finds the periods of animated parameters. If the first algorithm is chosen, one period is computed for the overall orientation of the input objects. This period corresponds to the minimal time offset to apply to the input objects so as to get the same overall orientation as that of the start time. In this case, the input objects must be animated in rotation for FindPeriods to work.
If the second algorithm is chosen, one period is computed for each input object. These periods correspond to the minimal time offsets to apply to each input objects so they take the same value as that at the start time. In this case the input objects must be animated parameters for FindPeriods to work.
To use this command, you must select the objects/animated parameters for which you want to find periods. The animation of these objects will then be analyzed between the Start and End Frame to compute the periods.

### Scripting Syntax

    oReturn = FindPeriods( InputObjs, [Algorithm], StartFrame, EndFrame, Minimum Period Length );

### Return Value

Returns the periods of animated parameters. If no period is found in the range defined by both the minimum length and the animation length (End Frame - Start Frame), FindPeriods returns 0.

### Parameters

Parameter | Type | Description
--- | --- | ---
InputObjs | String | Objects to use to find a cyle. Default Value: Current selected objects
Algorithm | Long | Algorithm to choose from Default Value: 1
Possible Values: | Description:
0 | Works for rotations only.
1 | Works for any animated parameter.
StartFrame | Double | Frame at which the periods suposedly starts. Default Value: 0
EndFrame | Double | Upper frame boundary where to look for a period. Default Value: 0
Minimum Period Length | Long | Minimum length of the periods looked for (common estimate). Default Value: 1

### Examples

#### VBScript Example

    ' This example creates a simple skeleton and demonstrates using FindPeriods to
    ' detect cycles in its animation.  In the first case, we have a simple rotation
    ' animation.  In the second, we show cycle detection on an arbitrary parameter
    ' (we chose bone length).
    NewScene , False
    ' Create an object for us to use for this example.
    Create2DSkeleton 0, 0, 0, 0, 0, 3, 0, 1, 0, 0, oBone
    '
    ' 1) Create an animation in which a cycle occurs for the rotation of a bone.
    '
    SaveKey oBone & "/kine.local.rotx,kine.local.roty,kine.local.rotz", 1
    Rotate oBone, 0, 0, 145, siRelative, siLocal, siObj, siXYZ
    SaveKey oBone & "/kine.local.rotx,kine.local.roty,kine.local.rotz", 10
    Rotate oBone, 0, 0, 215, siRelative, siLocal, siObj, siXYZ
    SaveKey oBone & "/kine.local.rotx,kine.local.roty,kine.local.rotz", 23
    Rotate oBone, 0, 0, 50, siRelative, siLocal, siObj, siXYZ
    SaveKey oBone & "/kine.local.rotx,kine.local.roty,kine.local.rotz", 30
    ' Store the animation as an action and instantiate a clip in the mixer.
    set oAction = StoreAction( , oBone & "/kine.local.rotx,kine.local.roty,kine.local.rotz", _
                                    2, "BoneRot", True, 1, 30)
    set oClip = AddClip( "Scene_Root", oAction, , , 30 )
    ' Find the period of bone rotation (algorithm 0) from start of clip.
    clipStart = GetValue( oClip & ".actionclip.timectrl.resin" )
    clipEnd = GetValue( oClip & ".actionclip.timectrl.resout" )
    Periods = FindPeriods( oBone, 0, clipStart, clipEnd, 1 )
    LogMessage "Period for bone rotation: " & Periods(0) & " frames"
    '
    ' 2) Animate the bone length to be periodic.
    '
    SaveKey oBone & ".bone.length",  1, 3
    SaveKey oBone & ".bone.length",  5, 4
    SaveKey oBone & ".bone.length",  9, 3
    SaveKey oBone & ".bone.length", 13, 4
    SaveKey oBone & ".bone.length", 17, 3
    SaveKey oBone & ".bone.length", 21, 4
    SaveKey oBone & ".bone.length", 25, 3
    ' Store the animation as an action and instantiate a clip in the mixer.
    set oAction = StoreAction( , oBone & ".bone.length", 2, "BoneLength", True, 1, 24)
    set oClip = AddClip( "Scene_Root", oAction, , , 1 )
    ' Find the period of bone length (algorithm 1) from start of clip.
    clipStart = GetValue( oClip & ".actionclip.timectrl.resin" )
    clipEnd = GetValue( oClip & ".actionclip.timectrl.resout" )
    Periods = FindPeriods("bone.bone.length", 1, clipStart, clipEnd, 1)
    LogMessage "Period for bone length: " & Periods(0) & " frames"
    ' Compute the number of cycles of the animation.
    NumPeriods = ((clipEnd - clipStart) / Periods(0))
    LogMessage "Number of cycles: " & NumPeriods
    ' Running this script should log the following:
    ' ---------------------------------------------
    'INFO : "Period for bone rotation: 22 frames"
    ' <bunch of logged commands, and then:>
    'INFO : "Period for bone length: 8 frames"
    'INFO : "Number of cycles: 3"