====== Example: Gait Events using Kinematic Data ======

Gait events refer to meaningful moments during walking movement, particularly **Heelstrike (HS)**- when the foot makes contact with the ground, and **Toe-off (TO)**- when the foot lifts off the ground. These events are typically identified by applying thresholds on ground reaction force (GRF) signals. These signals are acquired from lab-based kinetic equipment such as force plates or instrumented treadmills that are not always available in labs. 

To address this issue, several journal articles have been published which introduce different algorithms that make use of kinematic features to identify these gait events.

===== Overview ======

This example walks through the application of these kinematic event detection methods into the Visual3D pipeline, in order to produce heelstrike and toe-off events.

It must be noted that these methods **vary in their effectiveness** on correctly identifying these events.

A research study was conducted to assess the different methods' reliability in structuring gait cycles as compared to kinetic based cycles. A tutorial was developed based off of the study and is available here: 

[[visual3d:tutorials:events:kinematic_event_detection|Supporting Tutorial: Assessing Kinematic Methods of Structuring Gait]]

===== Pipeline Scripts ======

The pipeline scripts can be downloaded [[here]]. 

===== Methods Overview =====

The following methods are implemented using the Visual3D pipelines. Each has a slightly different biomechanical rationale for estimating gait events based on kinematic features.

The first paper, presented by [[https://pubmed.ncbi.nlm.nih.gov/17723303/|Zeni et al. (2008)]], outlines 2 separate methods.

=== Method 1A: Foot Position Relative to Pelvis ===


=== Method 1B: Foot Velocity Relative to Pelvis ===

=== Method 2: Hip Kinematics ===

[[https://pubmed.ncbi.nlm.nih.gov/22704579/|DeAsha et al. (2012)]]

=== Method 3: Foot Acceleration ===

[[https://pubmed.ncbi.nlm.nih.gov/10808002/|Hreljac (2000)]]

=== Method 4: Foot Centre Vertical Velocity ===

[[https://pubmed.ncbi.nlm.nih.gov/16876414/|O'Connor et al. (2007)]]

This method analyzed the vertical velocity of the midpoint of the foot segment to detect gait events.


===== Method 1A: Foot Position Relative to Pelvis =====

The first method uses the position data of the left heel and left toe relative to the pelvis coordinate system to identify gait events.

Specifically, Heelstrike (HS) is determined by the maximum forward position of the heel and toe-off (TO) is identified by the minimum forward position of the toe.

This pipeline follows the algorithm described in the literature and includes the following key steps:

**1.** Compute position signals of left heel and toe relative to the pelvis

Use the [[visual3d:documentation:pipeline:model_based_data_commands:compute_model_based_data|Compute_Model_Based_Data]] command to create position signals which will be used to find events for this method.

<code>
! Compute Left Toe Position relative to Pelvis
!----------------------------------------------------------------------------
Compute_Model_Based_Data
/RESULT_NAME=LToe_Wrt_Pelvis
/FUNCTION=SEG_DISTAL_JOINT
/SEGMENT=LFT
/REFERENCE_SEGMENT=RPV
/RESOLUTION_COORDINATE_SYSTEM=RPV
! /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 Left Heel Position relative to Pelvis 
!----------------------------------------------------------------------------
Compute_Model_Based_Data
/RESULT_NAME=LHeel_Wrt_Pelvis
/FUNCTION=SEG_PROXIMAL_JOINT
/SEGMENT=LFT
/REFERENCE_SEGMENT=RPV
/RESOLUTION_COORDINATE_SYSTEM=RPV
! /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
;
</code>

2. Detect heelstrike events as local maxima in the x-component of the heel position using [[visual3d:documentation:pipeline:event_commands:event_maximum|Event_Maximum]]

<code>
! HEELSTRIKE (LHS) Event at MAX of Heel Signal in X Component
!----------------------------------------------------------------------------
Event_Maximum
/RESULT_EVENT_NAME=LHS Foot Position
/SIGNAL_TYPES=LINK_MODEL_BASED
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=LHEEL_WRT_PELVIS
/SIGNAL_COMPONENTS=X
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
! /FRAME_WINDOW=8
! /THRESHOLD=
</code>

3. Detect toe-off events as local minima in the x-component of the toe position using [[visual3d:documentation:pipeline:event_commands:event_minimum|Event_Minimum]]

<code>
! TOE-OFF (LTO) Event at MIN of Toe Signal in X Component
!----------------------------------------------------------------------------
Event_Minimum
/RESULT_EVENT_NAME=LTO Foot Position
/SIGNAL_TYPES=LINK_MODEL_BASED
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=LTOE_WRT_PELVIS
/SIGNAL_COMPONENTS=X
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
! /FRAME_WINDOW=8
! /THRESHOLD=
;
</code>

A snapshot of the full pipeline can be seen below in the Visual3D pipeline workshop dialog: 

{{:visual3d:documentation:pipeline:event_commands:footpositionmethod1_pipelineworkship.png?600|}}

===== Method 1B: Foot Velocity Relative to Pelvis =====

This method builds on the previous one by using the velocity of the heel and toe relative to the pelvis coordinate system rather than position. It identifies heelstrike when the heel velocity signal crosses zero on the **descent**, and toe-off when the toe velocity crosses zero on the **ascent**.

Like Method 1A, the heel and toe positions relative to the pelvis are computed using [[visual3d:documentation:pipeline:model_based_data_commands:compute_model_based_data|Compute_Model_Based_Data]] 

Then, the pipeline follows the algorithm described in the second method presented in the literature:

1. Derive the velocity signals for both heel and toe using [[visual3d:documentation:pipeline:signal_commands:first_derivative|First_Derivative]]

<code>
! ----------------------------------------------------------------------------
!  Take derivative of both heel and toe position signals in order to find Velocity 
! ----------------------------------------------------------------------------
First_Derivative
/SIGNAL_TYPES=LINK_MODEL_BASED
/SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=LHeel_Wrt_Pelvis+LToe_Wrt_Pelvis
/RESULT_TYPES=DERIVED
/RESULT_FOLDERS=VELOCITY
/RESULT_NAME=_Vel
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
</code>

2. Define Heelstrike (LHS) event when velocity signal (x-component) of the heel crosses the zero-value on descent, and toe-off (LTO) event when signal crosses on ascent using [[visual3d:documentation:pipeline:event_commands:event_threshold|Event_Threshold]]

<code>
Event_Threshold
/RESULT_EVENT_NAME=LHS Foot Velocity
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=VELOCITY
/SIGNAL_NAMES=LHeel_Wrt_Pelvis_Vel
/SIGNAL_COMPONENTS=X
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
/THRESHOLD=0
/ON_ASCENT=FALSE
/ON_DESCENT=TRUE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;

Event_Threshold
/RESULT_EVENT_NAME=LTO Foot Velocity
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=VELOCITY
/SIGNAL_NAMES=LToe_Wrt_Pelvis_Vel
/SIGNAL_COMPONENTS=X
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
/THRESHOLD=0
/ON_ASCENT=TRUE
/ON_DESCENT=FALSE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;
</code>

A snapshot of the full pipeline can be seen below in the Visual3D pipeline workshop dialog: 

{{:visual3d:documentation:pipeline:event_commands:footvelocitymethod1b_pipelineworkshop.png?600|}}


===== Method 2: Hip Kinematics =====

This method identifies only heelstrike (HS) events, based on the peak extension of the contralateral hip. When the **right hip** reaches minimum extension in the sagittal plan, a **left-side** HS event is detected.

This corresponds with the point in gait where the opposite foot (left) is most likely contacting the ground.

The pipeline uses the algorithm described in the literature and includes the following key steps:

1. Calculate the Right Hip Joint Angle to identify minimum extension moments in this signal.

<code>
Compute_Model_Based_Data
/RESULT_NAME=RHip_Angle
/FUNCTION=JOINT_ANGLE
/SEGMENT=RTH
/REFERENCE_SEGMENT=RPV
/RESOLUTION_COORDINATE_SYSTEM=
! /USE_CARDAN_SEQUENCE=FALSE
! /NORMALIZATION=FALSE
/NORMALIZATION_METHOD=TRUE
! /NORMALIZATION_METRIC=
! /NEGATEX=FALSE
! /NEGATEY=FALSE
! /NEGATEZ=FALSE
! /AXIS1=X
! /AXIS2=Y
! /AXIS3=Z
;
</code>

2. Use [[visual3d:documentation:pipeline:event_commands:event_minimum|Event_Minimum]] to identify LHS from contralateral extension in sagittal plane.

<code>
Event_Minimum
/RESULT_EVENT_NAME=LHS Hip Extension
/SIGNAL_TYPES=LINK_MODEL_BASED
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=RHip_Angle
/SIGNAL_COMPONENTS=Y
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
/FRAME_WINDOW=50
! /THRESHOLD=
;
</code>


A snapshot of the full pipeline can be seen below in the Visual3D pipeline workshop dialog: 

{{:visual3d:documentation:pipeline:event_commands:hipextensionmethod2_pipelineworkshop.png?600|}}


===== Method 3: Hip Kinematics =====

This method is based on the premise that certain peaks in foot acceleration correspond reliably to heelstrike and toe-off moments.

Specifically, this method uses the vertical acceleration of the Left Heel and the forward acceleration of the Left Fifth metatarsal (MT5) to identify these events.

A snapshot of the full pipeline can be seen below in the Visual3D pipeline workshop dialog: 

1. Before computing acceleration, the [[visual3d:documentation:pipeline:signal_commands:lowpass_filter|Lowpass_Filter]] command is used to filter the positional signals of the Left Heel and Left MT5 markers. This smoothing step reduces noise that would be amplified when differentiating.

<code>
Lowpass_Filter
/SIGNAL_TYPES=TARGET
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=L.Heel+L.MT5
/RESULT_FOLDER=PROCESSED
/RESULT_SUFFIX=_filt
! /FILTER_CLASS=BUTTERWORTH
! /FREQUENCY_CUTOFF=6.0
! /NUM_REFLECTED=6
! /NUM_EXTRAPOLATED=0
! /TOTAL_BUFFER_SIZE=6
! /NUM_BIDIRECTIONAL_PASSES=1
;
</code>

2. The [[visual3d:documentation:pipeline:signal_commands:second_derivative|Second_Derivative]] command outputs the acceleration signals. The outputs are saved in the DERIVED folder with the suffix _accel.

<code>
Second_Derivative
/SIGNAL_TYPES=TARGET
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=L.Heel_filt+L.MT5_filt
/RESULT_TYPES= DERIVED
/RESULT_FOLDERS=ACCELERATION
/RESULT_NAME=_accel
/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
;
</code>

3. The heelstrike events are identified as local maxima in the y-component (vertical) of the Left Heel's acceleration signal. This peak corresponds to the abrupt deceleration of the heel when it makes contact with the ground. 

<code>
Event_Maximum
/RESULT_EVENT_NAME=LHS Foot Acceleration
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=ACCELERATION
/SIGNAL_NAMES=L.Heel_filt_accel
/SIGNAL_COMPONENTS=Y
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
/FRAME_WINDOW=80
! /THRESHOLD=
;
</code>

4. The toe-off events are similarly identified as local maxima in the x-component of the Left MT5's acceleration signal. This reflects the propulsion phase, where the forefoot pushes of and leaves the ground.

<code>
Event_Maximum
/RESULT_EVENT_NAME=LTO Foot Acceleration
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=ACCELERATION
/SIGNAL_NAMES=L.MT5_filt_accel
/SIGNAL_COMPONENTS=X
! /FRAME_OFFSET=0
! /TIME_OFFSET=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_SEQUENCE_INSTANCE=0
! /EVENT_SUBSEQUENCE=
! /SUBSEQUENCE_EXCLUDE_EVENTS=
! /EVENT_SUBSEQUENCE_INSTANCE=0
! /EVENT_INSTANCE=0
/FRAME_WINDOW=80
! /THRESHOLD=
;
</code>

A snapshot of the full pipeline can be seen below in the Visual3D pipeline workshop dialog:

{{:visual3d:documentation:pipeline:event_commands:footaccelerationmethod3_pipelineworkshop.png?600|}}

===== Method 4: Foot Centre Vertical Velocity =====