Wiki Documentation Site

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Automating Work Flow With Directory Watchers in The GUI =====
In this tutorial we will walk you through the steps of setting up Sift to automatically process your data when it is loaded. You will learn how to create a directory watcher and point it to a folder your data will be dropped in, then set it to execute all your Visual3D and Sift processing automatically.

===== The Task =====
Before automating a workflow, we need a clear research question. In this example, we want to look at the right and left ankle movement from a treadmill-running trial for atypical stride cycles.

===The Workflow===

  - Visual3D to calculate the right and left ankle joint angles
  - Right heel strike to right heel strike for right stride cycles
  - Left heel strike to left heel strike for left stride cycles
  - Sift PCA to summarize the major differences in curve shape
  - Group-level Local Outlier Factor (LOF) to flag ankle cycles that are different from the other cycles on the same side

To begin, download and unzip this folder {{ :sift:tutorials:directory_watcher_tutorial.zip |'Directory_Watcher_Tutorial.'}}  The C3D file remains outside the watched **Data** directory until you are ready to start the workflow.

===== Setting Up =====

==== Visual3D Pipeline ====

Before creating the watchers, open ''V3D_Pipeline.v3s'' in a text editor.

The script performs four steps:

  - Opens the treadmill-running C3D 
  - Calculates right and left ankle joint angles
  - Creates the heel-strike events used to define stride cycles
  - Saves a CMZ into the ''CMZs'' folder


For a lower-body model, an ankle joint angle is calculated using the foot as the segment and the shank as the reference segment. The X component represents flexion and extension for the segment coordinate systems used in this example. See [[visual3d:tutorials:kinematics_and_kinetics:model_based_computations|Model Based Computations]] for more information about joint-angle definitions.

Before running, replace every occurrence of **REPLACE** with the full path to the unzipped ''Directory_Watcher_Tutorial'' folder.

For example:

<code>
C:\Users\maya\Desktop\Directory_Watcher_Tutorial\Data
</code>

Only the ''File_Open'' and ''File_Save_As'' commands require this path update.

<code>
File_Open
/FILE_NAME=DE3_1_pose_0.c3d
/FILE_PATH=[[REPLACE]]\Data
! /SEARCH_SUBFOLDERS=FALSE
! /SUFFIX=
! /SET_PROMPT=File_Open
! /ON_FILE_NOT_FOUND=PROMPT
! /FILE_TYPES_ON_PROMPT=
;

Compute_Model_Based_Data
/RESULT_NAME=RAnkleAngle
/SUBJECT_TAG=ALL_SUBJECTS
/FUNCTION=JOINT_ANGLE
/SEGMENT=RFT
/REFERENCE_SEGMENT=RSK
/RESOLUTION_COORDINATE_SYSTEM=
! /USE_CARDAN_SEQUENCE=FALSE
! /NORMALIZATION=FALSE
! /NORMALIZATION_METHOD=
! /NORMALIZATION_METRIC=
/NEGATEX=FALSE
/NEGATEY=FALSE
/NEGATEZ=FALSE
! /AXIS1=X
! /AXIS2=Y
! /AXIS3=Z
! /TREADMILL_DATA=FALSE
! /TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
! /TREADMILL_SPEED=0.0
;

Compute_Model_Based_Data
/RESULT_NAME=LAnkleAngle
/SUBJECT_TAG=ALL_SUBJECTS
/FUNCTION=JOINT_ANGLE
/SEGMENT=LFT
/REFERENCE_SEGMENT=LSK
/RESOLUTION_COORDINATE_SYSTEM=
! /USE_CARDAN_SEQUENCE=FALSE
! /NORMALIZATION=FALSE
! /NORMALIZATION_METHOD=
! /NORMALIZATION_METRIC=
! /NEGATEX=FALSE
! /NEGATEY=FALSE
! /NEGATEZ=FALSE
! /AXIS1=X
! /AXIS2=Y
! /AXIS3=Z
! /TREADMILL_DATA=FALSE
! /TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
! /TREADMILL_SPEED=0.0
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=50
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=350
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=505
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=650
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=810
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=950
! /TIME=
;

Event_Explicit
/EVENT_NAME=RHS
/FRAME=1110
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=120
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=260
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=425
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=580
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=730
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=880
! /TIME=
;

Event_Explicit
/EVENT_NAME=LHS
/FRAME=1030
! /TIME=
;

File_Save_As
/FILE_NAME=DE3_Ankle_Angles.cmz
/FOLDER=[[REPLACE]]\CMZs
! /SET_PROMPT=Save CMZ file as
! /SAVE_EMBEDDED_GRAPHICS=FALSE
! /CREATE_FOLDER_PATH=FALSE
;

</code>

==== Sift Query ====

The Sift Query q3d file contains two signal groups:
  * ''RAnkleAngleX'', normalized from right heel strike to the next right heel strike
  * ''LAnkleAngleX'', normalized from left heel strike to the next left heel strike

<code>
<queries>
	<query name="RAnkleAngleX">
		<Definition condition="Right Ankle" query="RAnkleAngleX" global="FALSE" subject_tag="NO_SUBJECT" type="LINK_MODEL_BASED" folder="ORIGINAL" name="RAnkleAngle" component="X" max_elements="0" negate_result="FALSE" events="RHS,RHS" exclude_events="" has_tag_ref="No" tag_logic="OR" tag="" workspace_name_req="" normalize_info="101,0" query_type="0" data_type="1"/>
	</query>
	<query name="LAnkleAngleX">
		<Definition condition="Left Ankle" query="LAnkleAngleX" global="FALSE" subject_tag="NO_SUBJECT" type="LINK_MODEL_BASED" folder="ORIGINAL" name="LAnkleAngle" component="X" max_elements="0" negate_result="FALSE" events="LHS,LHS" exclude_events="" has_tag_ref="No" tag_logic="OR" tag="" workspace_name_req="" normalize_info="101,0" query_type="0" data_type="1"/>
	</query>
</queries>
</code>

==== Sift Batch Script ====

The BATCH script does not need to be updated, the script gets a reference to its location itself (the %~dp0 you see in the script). 

There are a couple things to note about the script, the first line is ::SIFT, a .bat file will only be executed if this line is present, this prevents a unintended script from being executed by accident, you will also notice that the entire sift command is on one line. This is because they all need to be passed at once via a command line call and new line characters will execute everything preceding it and treat everything remaining as a brand new command to make this easier to manage you can enable wordwrap on your text editor of choice.

<code>
::SIFT
"%ProgramFiles%\Sift\Sift.exe" -LoadLib "%~dp0\CMZs" -LoadQuery "%~dp0\Sift_Query.q3d" -SelectSignals -RunPCA "AnkleStridePCA" -RunLOF grouping "group" autoExclude -ExportPCA file "%~dp0\Exports\Ankle Stride - LOF Outliers.txt" lof lofThreshold exportFormat "transposed" -SaveProject "%~dp0\Exports\Ankle Stride Screening.i3d" -Exit
</code>

The script performs the following:

  - Loads the CMZ library
  - Loads and calculates the ankle-angle queries
  - Selects both ankle signal groups
  - Creates a PCA named ''AnkleStridePCA''
  - Runs LOF separately within each signal group
  - Automatically excludes the cycles identified as outliers
  - Exports the LOF values and threshold
  - Saves the completed Sift project

===== Opening the Directory Watchers Dialog =====

Launch Sift normally.

From the main page, select the Directory Watcher icon {{.:pasted:20260716-142143.png}}.

The table on the left lists all configured watchers and whether each watcher is active. The right side displays the settings for the selected watcher.
==== Creating the Visual3D Watcher ====

Select ''Add'' above the watcher table.

In the name dialog, enter:

<code>
V3D Ankle Angle Watcher
</code>

{{.:pasted:20260717-192613.png}}

When prompted to add the directory, browse to ''Directory_WatcherTutorial\Data'' and select the folder. When prompted for the script, browse to ''Directory_WatcherTutorial\V3D_Pipeline.v3s'' and select the pipeline. 
With the new watcher created, configure the following settings on the right side of the dialog. 

^ Setting ^ Value ^
| Name | V3D Ankle Angle Watcher |
| Active | Enabled |
| Recursive | Disabled |
| Trigger on delete | Disabled |
| Delay | 1000 ms |

The delay gives Windows time to finish copying the C3D before Visual3D attempts to open it. A longer delay may be needed for larger files or network directories.

The first watcher should look like this.
 
{{.:pasted:20260717-192652.png}}

When the C3D is copied into **Data**, the watcher will launch the Visual3D pipeline. 

==== Creating the Sift Watcher ====

Select ''Add'' again.

Name the second watcher:

<code>
Sift Ankle Outlier Watcher
</code>

When prompted to add the directory browse to ''Directory_WatcherTutorial\CMZs'' and select the folder. When prompted for the script, browse to ''Directory_WatcherTutorial\Sift_Script.bat'' and select. 
With the new watcher created, configure the following settings on the right side of the dialog. 

^ Setting ^ Value ^
| Name | Sift Ankle Outlier Watcher |
| Active | Enabled |
| Recursive | Disabled |
| Trigger on delete | Disabled |
| Delay | 1000 ms |

{{.:pasted:20260717-192738.png}}

The completed watcher should monitor ''CMZs'' and contain the Sift batch script.

Now both watchers should be activated. 

A watcher can be deactivated without deleting its settings if needed. ''Deactivate All'' stops every watcher at once. 

==== Launching the Background Instance ====

Directory watchers respond while the Sift background instance is running.

In the ''Tray Options'' section, select ''Launch background instance of Sift in the system tray'' and check ''Launch minimized to system tray''. This will ensure Sift starts in the tray by default. 

{{.:pasted:20260717-192904.png}}

A Sift icon should appear in the Windows system tray.

The background instance **MUST** continue running while the directory watchers are in use, or else they will not work. 


==== Using the Watchers ====

Open the following folders in separate File Explorer windows:

  * ''Data''
  * ''CMZs''
  * ''Exports''

The sample C3D, ''DE3_1_pose_0.c3d'', should still be in the root ''Directory_Watcher_Tutorial'' folder.

Copy or drag the C3D into:

<code>
Directory_Watcher_Tutorial\Data
</code>

After the watcher delay, the ''V3D Ankle Angle Watcher'' will launch ''V3D_Pipeline.v3s''.

The pipeline will calculate:

  * ''RAnkleAngle''
  * ''LAnkleAngle''
  * right heel-strike events
  * left heel-strike events

It will then save:

<code>
CMZs\DE3_Ankle_Angles.cmz
</code>

The new CMZ will trigger the Sift Script and sift will load the ankle strides, run PCA and LOF analysis and create two more files. 

<code>
Exports\Ankle Stride - LOF Outliers.txt
Exports\Ankle Stride Screening.i3d
</code>

=====Reviewing the Results=====

Open ''Ankle Stride - LOF Outliers.txt'' to review the LOF score for each right and left ankle stride and the threshold used to classify outliers.

Load ''Ankle Stride Screening.i3d'' in Sift to view the analysis visually. You can view the graphs on the **Explore** page. 

{{.:pasted:20260716-150531.png}}

On the **Analyse** page, look at the workspace scores and LOF results. 

==== Editing an Existing Watcher ====

To edit an existing watcher open the dialog {{.:pasted:20260716-142143.png}} in Sift again and select a watcher in the table to edit its configuration. 

You can:

  - Change its name
  - Activate or deactivate it
  - Enable or disable recursive directory monitoring
  - Enable or disable delete events
  - Change the delay
  - Add or remove directories
  - Add or remove scripts

Any changes made to the selected watcher are used the next time a relevant directory event occurs.

==== Removing a Watcher ====

Select the watcher and use ''Delete'' to remove it permanently.

Deleting a watcher does not delete its directories, scripts, CMZs, or exports.

===== Conclusion =====

The Directory Watchers dialog allows a complete automated workflow to be created and managed without entering watcher commands manually.

In this example, adding one C3D to the ''Data'' folder automatically:

  - Calculated ankle joint angles in Visual3D
  - Divided the signals into right and left stride cycles
  - Ran PCA in Sift
  - Looked into each side for different ankle cycles using LOF
  - Exported the outlier results
  - Saved a Sift project

The same approach can be used to automate other workflows.