Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:pipeline:event_commands:automatic_gait_events [2025/02/19 16:08] – [Notes] wikisysop
+++ visual3d:documentation:pipeline:event_commands:automatic_gait_events [2025/03/03 19:27] (current) – [Command Parameters] wikisysop
@@ Line 4: / Line 4: @@
 Gait events describe key moments in the walking or running cycle - such as heel-strikes and toe-offs. If [[Visual3D:Documentation:Kinematics_and_Kinetics:External_Forces:Force_Assignment|Force Platform assignments]] exist for a motion trial, the **Automatic_Gait_Events** command __automatically detects these gait events and places an **event label** at the frames where the subject steps ON and OFF the surface of the platform.__
-Before running this command, the model must have segments created so that the program can recognize which is left and right. These segments are not limited to feet, they simply describe the part of body which makes contact with the force platform.
+Before running this command, the model must have segments created so that the program can recognize the left from the right. These segments are not limited to feet, they simply describe the part of body which makes contact with the force platform.
-Contact with the floor for which there are //no force platforms// can be determined using **Temporal Proximity Rule (TPR)**, this will be seen in the dialog box for this command. No signals need to be provided for the TPR because Visual3D uses the kinematics of the segment making contact with the force platform.
+Contact with the floor for which there are //no force platforms// can be determined using **TPR**, this will be seen in the dialog box for this command. No signals need to be provided for the TPR because Visual3D uses the kinematics of the segment making contact with the force platform.
 ==== Pipeline Command ====
@@ Line 31: / Line 31: @@
 The following table shows the command parameters for **Version 5+**.
-|**Automatic_Gait_Events**|**Parameter Description**|
+|**Parameter**|**Parameter Description**|
 |**! /FRAME_WINDOW = 8**|The frame window used for pattern recognition (default = 8)|
-|**! /USE_TPR=TRUE**|Enables TPR Algorithm is used to find the heelstrike (HS) and toeoff (TO).|
+|**! /USE_TPR=TRUE**|Enables TPR Algorithm to be used to find the heelstrike (HS) and toeoff (TO).|
-| **! /TPR_EVENT_INSTANCE=1**  |Instance used of detected event.|
+| **! /TPR_EVENT_INSTANCE=1**  |Instances used to detect events using TPR.|
 ==== Dialog ====
@@ Line 43: / Line 43: @@
   * **Use Pattern Recognition to Create (L/R)HS and (L/R)TO Labels**: applies pattern recognition to identify gait cycle events.
   * **Frame Window for Pattern Recognition**: Number of frames used for pattern recognition
-  * **Instance of ON/OFF to use for TPR**: Determines which instance of an ON/OFF transition is used for event detection with TPR.
+  * **Instance of ON/OFF to use for TPR**: Determines how many instances of an ON/OFF transition is used for event detection with TPR.
 ==== Examples ====
-The following examples will show different methods in which Automatic_Gait_Events can be used alongside other commands for user applications.
+The following examples will show different methods in which Automatic_Gait_Events can be used alongside other.
 === Example 1 ===
@@ Line 62: / Line 62: @@
 </code>
-After executing the pipeline, you will notice a new folder in your Signals and Events tab called **EVENT_LABEL**, within it is all of the gait events which the program automatically detected and set.
+After executing the pipeline, you will notice a new folder in your Signals and Events tab called **EVENT_LABEL**, with all the gait events the program automatically detected.
 {{:visual3d:documentation:pipeline:event_commands:event_label_data_tree_new_folder.png?300|}}
@@ Line 68: / Line 68: @@
 === Example 2 ===
-In the next example, the **Automatic_Gait_Events** command will be used alongside others in a pipeline which allows the user to do the following starting from an empty project workspace:
+In the next example, the **Automatic_Gait_Events** command will be used with other commands to allow a user to go from starting with empty workspace to finding and highlighting events.
   * Open the user-selected workspace file. ([[visual3d:documentation:pipeline:file_commands:file_open|File_Open]])
   * **Automatically detect gait events.**
-  * Iterate through and highlight LHS, LTO, and BTWN event labels. ([[visual3d:documentation:pipeline:pipeline_commands:for_each_and_end_for_each|For_Each]]) -> ([[visual3d:documentation:pipeline:other_commands:highlight_event_label|Highlight_Event_Label]])
+  * Iterate through and highlight all gait events. ([[visual3d:documentation:pipeline:pipeline_commands:for_each_and_end_for_each|For_Each]]) -> ([[visual3d:documentation:pipeline:other_commands:highlight_event_label|Highlight_Event_Label]])
   * Switch to Signals and Events tab, and graph X-component of Force Platform signal (events will be shown on this graph). ([[visual3d:documentation:pipeline:other_commands:switch_between_tabs|Switch_Between_Tabs]]) -> ([[visual3d:documentation:pipeline:report_commands:interactive_graph_signals|Interactive_Graph_Signals]])
@@ Line 127: / Line 128: @@
 </code>
-After having simply run this pipeline, the program is able to display the following graph:
+After having run this pipeline, the program is able to display the following graph:
 \\
 {{:visual3d:documentation:pipeline:event_commands:samplegraph.png?500|}}
+==== Notes ====
+=== Gait Event Acronyms ===
+Definitions of gait event acronyms used in Visual3D are shown below.
+The automatic gait events command, many of the events created in the tutorials, and events used in the example files have a 3 (or 4) character label that have been used consistently throughout history. The labels are divided into two categories:
+. Kinematic Events:
+<code>
+**RHS**= Right Heel Strike
+**RTO**= Right Toe Off
+**LHS**= Left Heel Strike
+**LTO**= Left Toe Off
+</code>
+. Kinetic Events:
+<code>
+**RON**= Right On
+**ROFF**= Right Off
+**LON**= Left On
+**LOFF**= Left Off
+</code>
+All RON events are also RHS events, but RON events are only created when contact is made with a force platform.
+This provides a means to declare a range of data for reporting only when in contact with the force platform. This is because Joint Moments and Joint Powers, for example, do not have meaningful data when the foot is in contact with ground but no ground reaction forces are measured.
+=== Outline ===
+The following is an overall outline of the use of this command. As a reminder:
+  * The **Automatic_Gait_Events** pipeline command can be used to create gait events __if__ force platforms exist in a dynamic trial.
+  * ON/OFF events indicate kinetic cycles and HS/TO indicate kinematic cycles.
+  - A static trial must be loaded into the workspace and a minimum of two segments must be created (for standard gait trials, this means a left/right foot segment must be created).\\
+  - If a force platform assignment exists in a dynamic trial, ON/OFF events will be created when [[Visual3D:Documentation:Kinematics_and_Kinetics:External_Forces:Force_Assignment|Force Assignments]] exist. A Force Assignment exists IF:\\
+    - A segment’s center of mass (ANY segment) falls within the specified [[Visual3D:Documentation:Modeling:Segments:Segment_to_COFP_Distance|distance between center of force pressure to segment]].\\
+    - The force signal goes above the specified [[Visual3D:Documentation:Kinematics_and_Kinetics:External_Forces:Force_Platforms#Minimum_Force|minimum force platform value]].\\
+  - If “Use Pattern Recognition to Create (L/R)HS and (L/R)TO labels” is checked, and if an ON/OFF event was created in a trial, a HS/TO event will be created in the trial based on the position of the foot segment: (See [[#Event_TPR_Signal|Event_TPR_Signal]] section for more information on this)\\
+    - HS events will be created based on the Axial and AP position of the proximal end of the foot\\
+    - TO events will be created based on the Axial and AP position of the distal end of the foot\\
+=== Equivalent Pipeline Commands ===
+To show the simplicity of this command, an example pipeline will be shown below to mimic the same functionality using other existing commands, however, it will not necessarily produce the precise TPR created events.
+  * Creating events from kinematic data is accurate to approximately plus/minus 2 frames.
+  * In this example, the subject is walking in the +Y direction of the laboratory. The Automatic_Gait_Events command allows Visual3D to determine the direction of walking from the data.
+<code>
+For_Each
+/Iteration_Parameter_Name=FOOT
+/Items=LFT+RFT
+;
+Conditional_Statement
+/ITERATION_PARAMETER_NAME=LEFT
+! /EXPRESSION=::FOOT == "LFT"
+! /AS_INTEGER=TRUE
+;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=ON_EVENT
+    /VALUE=LON
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=OFF_EVENT
+    /VALUE=LOFF
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=HS_EVENT
+    /VALUE=LHS
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=TO_EVENT
+    /VALUE=LTO
+    ;
+Conditional_Statement_End
+/ITERATION_PARAMETER_NAME=LEFT
+;
+Conditional_Statement
+/ITERATION_PARAMETER_NAME=RIGHT
+! /EXPRESSION=::FOOT != "LFT"
+! /AS_INTEGER=TRUE
+;
+    ! Right foot events
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=ON_EVENT
+    /VALUE=RON
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=OFF_EVENT
+    /VALUE=ROFF
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=HS_EVENT
+    /VALUE=RHS
+    ;
+    Set_Pipeline_Parameter
+    /PIPELINE_PARAMETER_NAME=TO_EVENT
+    /VALUE=RTO
+    ;
+Conditional_Statement_End
+/ITERATION_PARAMETER_NAME=RIGHT
+;
+Event_Threshold
+/RESULT_EVENT_NAME=&::ON_EVENT
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=::FOOT
+/SIGNAL_NAMES=FORCE_1
+/SIGNAL_COMPONENTS=Z
+/THRESHOLD=10
+/ON_ASCENT=TRUE
+/ON_DESCENT=FALSE
+/ENSURE_FRAMES_AFTER=TRUE
+;
+Event_Threshold
+/RESULT_EVENT_NAME=&::OFF_EVENT
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=::FOOT
+/SIGNAL_NAMES=FORCE_1
+/SIGNAL_COMPONENTS=Z
+/FRAME_OFFSET=-1
+/THRESHOLD=10
+/ON_ASCENT=FALSE
+/ON_DESCENT=TRUE
+/ENSURE_FRAMES_AFTER=TRUE
+;
+Event_TPR_Signal
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=::FOOT
+/SIGNAL_NAMES=ProxEndPos
+/PATTERN_FILE=Rotate Through Active Files
+/PATTERN_TYPE=KINETIC_KINEMATIC
+/PATTERN_FOLDER=::FOOT
+/PATTERN_SIGNAL=ProxEndPos
+/PATTERN_EVENT_NAME=&::ON_EVENT
+/SELECT_X=TRUE
+/SELECT_Z=TRUE
+/TPR_WINDOW=8
+/EVENT_NAME=&::HS_EVENT
+;
+Event_TPR_Signal
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=::FOOT
+/SIGNAL_NAMES=ProxEndPos
+/PATTERN_FILE=Rotate Through Active Files
+/PATTERN_TYPE=KINETIC_KINEMATIC
+/PATTERN_FOLDER=::FOOT
+/PATTERN_SIGNAL=ProxEndPos
+/PATTERN_EVENT_NAME=&::OFF_EVENT
+/SELECT_X=TRUE
+/SELECT_Z=TRUE
+/TPR_WINDOW=8
+/EVENT_NAME=&::TO_EVENT
+;
+End_For_Each
+/Iteration_Parameter_Name=FOOT
+;
+</code>
+=== Event_TPR_Signal ===
+A description of the use of [[Visual3D:Documentation:Pipeline:Event_Commands:Event_TPR_Signal|Event_TPR_Signal]] for determining gait events when a force platform signal is present is presented in the following article:
+  * **Stanhope SJ, Kepple TM, McGuire DA, Roman NL.**(1990) "A Kinematic-Based Technique for Event Time Determination During Gait." Medical and Biological Engineering and Computing 28:355-360.
+[[Visual3D:Documentation:Pipeline:Event_Commands:Event_TPR_Signal|Event_TPR_Signal]] for the Automatic Gait algorithm uses the Axial and AP trajectory of the proximal end of the foot segment for detecting **Heel Strike**, while using the distal end of the foot segment for detecting **Toe Off**.
+  * **Heel Strike**: uses the signal KINETIC_KINEMATIC::RFT::ProxEndPos and KINETIC_KINEMATIC::LFT::ProxEndPos
+  * **Toe Off**: uses the signal KINETIC_KINEMATIC::RFT::DistEndPos and KINETIC_KINEMATIC::LFT::DistEndPos
+The HS and TO pattern recognition algorithms are not a generic one size fits all gait recognition algorithm, but rather it looks at the first ON and OFF events and matches the subject's specific pattern at the heel and toe to find other instances of the subject/trial specific pattern within a trial. The algorithm works very well, but if the pattern changes within a trial then the different HS or TO may not be identified.
+=== Visual3D Versions supporting Subject Prefixes ===
+When defining events for subjects that use a prefix to define the data belonging to that subject, event labels will also have the prefix of the subject the events belong to.
+**NOTE**: When using events in a command, the commands will iterate across subjects contained in the current workspace. As such, events and sequences listed as command parameters should NOT contain a prefix. As each subject is processed, the event range/sequence specified will automatically use the specific events prefixed for each subject as they are processed.