Differences

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

--- visual3d:documentation:pipeline:event_commands:event_threshold [2024/07/17 15:10] – sgranger
+++ visual3d:documentation:pipeline:event_commands:event_threshold [2025/04/29 13:39] (current) – [Dialog] wikisysop
@@ Line 1: / Line 1: @@
-====== Event_Threshold ======
+====== Event Threshold ======
-\\
+===== Overview =====
-**Place an event label at the frame where a signal crosses a specified value. The event is created at the frame satisfying the criteria.**
+The **Event_Threshold** command is used to detect threshold crossings (when signal crosses a specified value) in a signals and label events accordingly. This command provides extensive control over event placement by allowing users to define frame or time offsets, include or exclude sequences, and refine detections using component selection and event constraints.
-**This is a complicated command because there are so many options.**
+This command is particularly useful for defining critical events based on signal thresholds, such as peak force occurrences, velocity changes, or acceleration-based triggers.
-\\
+**Note**: The threshold parameter specified can be a number, a PROCESSED METRIC, or an expression.
+===== Pipeline Command =====
+The command below is as seen on the Visual3D application, it has many parameters as there are many options to manipulate this command.
-==== Command Syntax ====
+<code>
+Event_Threshold
+/RESULT_EVENT_NAME=
+! /SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+! /SIGNAL_COMPONENTS=
+! /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=
+! /ON_ASCENT=
+! /ON_DESCENT=
+! /FRAME_WINDOW=8
+! /ENSURE_FRAMES_BEFORE=FALSE
+! /ENSURE_FRAMES_AFTER=FALSE
+;
+</code>
-|<code>\\ Event_Threshold\\ /RESULT_EVENT_NAME=  The name to be given to the threshold event\\ ! /Signal_Types= The type of signal to be evaluated\\ ! /SIGNAL_NAMES= The name of the signal to be evaluated\\ ! /Signal_Folder= The name of the signal folder\\ ! /SIGNAL_COMPONENTS= Use these components of the signal (May also be\\     modified using Select_X, Select_Y, Select_Z parameters)\\ ! /FRAME_OFFSET=  The frame offset from the threshold crossing where \\     the event label is to be placed\\ ! /TIME_OFFSET= The time offset from the threshold crossing where the\\     event label is to be placed\\ ! /EVENT_SEQUENCE= A sequence of events to perform the command within\\     (for example: RHS+RHS)\\ ! /EXCLUDE_EVENTS= An that falls within an EVENT_SEQUENCE event may be\\     specified to exclude a sequence from the calculations\\ ! /EVENT_SEQUENCE_INSTANCE= Instance of event sequence \\ ! /EVENT_SUBSEQUENCE=A subsequence of events to perform the command\\     within (for example: LTO+LHS)\\ ! /SUBSEQUENCE_EXCLUDE_EVENTS=An event that falls within an\\     EVENT_SUBSEQUENCE may be specified to exclude a subsequence from the\\     calculations\\ ! /EVENT_SUBSEQUENCE_INSTANCE= Instance of event subsequence \\ ! /EVENT_INSTANCE= There may be several instances of an event crossing\\     satisfying the criteria. A value of 0 results in all crossing being assigned a\\     label. A positive number indicates the event (in sequence) to select. A \\     negative number indicates the event starting from the last event and \\     progressing to the first event.\\ ! /SELECT_X= (True or False)Use this component of the signal\\ ! /SELECT_Y= (True or False)Use this component of the signal\\ ! /SELECT_Z= (True or False)Use this component of the signal\\ ! /SELECT_RESIDUAL= (True or False)Use this component of the signal\\ ! /START_AT_EVENT= The search begins from the start event\\ ! /END_AT_EVENT= The search ends at the end event\\ ! /THRESHOLD= The value after which the event label is to be placed\\ ! /ON_ASCENT=  (True or False) Determine the threshold when the signal\\     is passing up through the threshold\\ ! /ON_DESCENT= (True or False) Determine the threshold when the signal \\     is passing down through the threshold\\ ! /Frame_Window= The range of frames of data that must satisfy the \\     threshold crossing. Used by the "Ensure" variable\\ ! /ENSURE_FRAMES_BEFORE=  (True or False)Radius frames of data before\\     crossing must lie on the same side of the threshold\\ ! /ENSURE_FRAMES_AFTER= (True or False)Radius frames of data after\\     crossing must lie on the same side of the threshold\\ </code>  |  {{:EventThresholdDialog_v5.jpg}}|
+===== Command Parameters =====
+The following table shows the command parameters and descriptions:
-=== Version 4 ===
+|**Parameter**     |**Description**|
+|**/RESULT_EVENT_NAME=**|The name assigned to the detected threshold event.|
+|**!/SIGNAL_TYPES=**|The type of signal to evaluate (i.e. Analog, Link Model Based, etc.)|
+|**!/SIGNAL_FOLDER=ORIGINAL**|The folder containing the signal.|
+|**!/SIGNAL_NAMES=**|Specifies the signal to be analyzed.|
+|**!/SIGNAL_COMPONENTS=**|Defines which signal components should be analyzed.|
+|**!/FRAME_OFFSET=0**|Shifts the event forward or backward by a specified number of frames.|
+|**!/TIME_OFFSET=**|Shifts the event forward or backward by a specified time in seconds.|
+|**!/EVENT_SEQUENCE=**|Sequence of events within which the command is performed (i.e. RHS + RHS).|
+|**!/EXCLUDE_EVENTS=**|Events to be excluded from sequence.|
+|**!/EVENT_SEQUENCE_INSTANCE=0**|Which instance of an event sequence to use.|
+|**!/EVENT_SUBSEQUENCE=**|Subsequence of events to analyze (i.e. LTO + LHS).|
+|**!/SUBSEQUENCE_EXCLUDE_EVENTS=**|Events to exclude from the subsequence.|
+|**!/EVENT_SUBSEQUENCE_INSTANCE=0**|Instance of the event subsequence to analyze.|
+|**!/EVENT_INSTANCE=**|Determines how many event occurrences to consider (0 for all, positive for sequential selection, negative for reverse selection).|
+|**!/THRESHOLD=**|Threshold value to trigger event detection.|
+|**!/ON_ASCENT=**|Determine if the event is detected when the signal crosses the threshold in an upward direction.|
+|**!/ON_DESCENT=**|Determines if the event is detected when the signal crosses the threshold in a downward direction.|
+|**!/FRAME_WINDOW=8**|The range of frames that must satisfy the threshold crossing condition.|
+|**!/ENSURE_FRAMES_BEFORE=FALSE**| (True or False) Radius frames of data before crossing must lie on the same side of the threshold.|
+|**!/ENSURE_FRAMES_AFTER=FALSE**|(True or False) Radius frames of data after crossing must lie on the same side of the threshold.|
-{{:EventThresholdDialog.jpg}}
+===== Dialog =====
+The command can be edited in a text editor or in a dialog form. To edit in the dialog pop up form either click on the **Edit** button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below.
-|**Event_Threshold**                                                                      |                                                                                                                                                                                                                                                                                                               |
+{{:visual3d:documentation:pipeline:event_commands:event_thr_dialog.png?400|}}
-|**/[[Visual3D:Documentation:Pipeline:General_Information:Signal_Types|Signal_Types]]=**  |The type of signal to be evaluated                                                                                                                                                                                                                                                                             |
-|**/Signal_Names=**                                                                       |The name of the signal to be evaluated                                                                                                                                                                                                                                                                         |
-|**/[[Visual3D:Documentation:Pipeline:General_Information:Signal_Folder|Signal_Folder]]=**|The name of the signal folder                                                                                                                                                                                                                                                                                  |
-|**/Event_Name=**                                                                         |The name to be given to the threshold event                                                                                                                                                                                                                                                                    |
-|**/Select_X=**                                                                           |(True or False)Use this component of the signal                                                                                                                                                                                                                                                                |
-|**/Select_Y=**                                                                           |(True or False)Use this component of the signal                                                                                                                                                                                                                                                                |
-|**/Select_Z=**                                                                           |(True or False)Use this component of the signal                                                                                                                                                                                                                                                                |
-|**/Threshold=**                                                                          |The value after which the event label is to be placed                                                                                                                                                                                                                                                          |
-|**/[[Visual3D:Documentation:Pipeline:General_Information:Frame_Window|Frame_Window]]=**  |The range of frames of data that must satisfy the threshold crossing. Used by the "Ensure" variable                                                                                                                                                                                                            |
-|**/Frame_Offset=**                                                                       |The frame offset from the threshold crossing where the event label is to be placed                                                                                                                                                                                                                             |
-|**/Ascending=**                                                                          |(True or False) Determine the threshold when the signal is passing up through the threshold                                                                                                                                                                                                                    |
-|**/Descending=**                                                                         |(True or False) Determine the threshold when the signal is passing down through the threshold                                                                                                                                                                                                                  |
-|**/Ensure_Range_Frames_Before_Threshold_Crossing=**                                      |(True or False)Radius frames of data before crossing must lie on the same side of the threshold                                                                                                                                                                                                                |
-|**/Ensure_Range_Frames_After_Threshold_Crossing=**                                       |(True or False)Radius frames of data after crossing must lie on the same side of the threshold                                                                                                                                                                                                                 |
-|**/Start_At_Event=**                                                                     |The search begins from the start event                                                                                                                                                                                                                                                                         |
-|**/End_At_Event=**                                                                       |The search ends at the end event                                                                                                                                                                                                                                                                               |
-|**/Event_Instance=**                                                                     |There may be several instances of an event crossing satisfying the criteria. A value of 0 results in all crossing being assigned a label. A positive number indicates the event (in sequence) to select. A negative number indicates the event starting from the last event and progressing to the first event.|
+  * **New Event Label Name**: Name to assign event that reaches threshold value.
+  * **Signal Component**: Direction of signal to use (X, Y, Z, ALL)
+  * **Frame Window**: Number of frames to check for threshold condition.
+  * **Frame Offset**: Shift event by a specified number of frames.
+  * **Time Offset**: Shift event by time (in seconds).
+  * **Threshold**: Value the signal must cross to trigger the event.
+  * **Event Instance**: Specify which instance of the event to label. (0 = all)
+  * **Label on Ascent/Descent**: Choose to place event when threshold is cross in an increasing signal (ascent) or decreasing signal (descent).
+  * **Ensure Window Before/After**: Full frame window is available before or after detected point to avoid errors.
+  * **Event Sequence**: Specify range in which to search for threshold crossings.
+  * **Event Subsequence**: Specify subrange in which to search for threshold crossings.
-----
-==== Ensure Range Parameter ====
-For example, consider the following signal from which an Event should be created when the signal crosses above the threshold (e.g. Ascending):
-{{:Thresholdexamplesignal.gif}}
+===== Examples =====
+The following examples will go through the use of the Event_Threshold command in the Visual3D application.
-There are many options to this command because there are many possible choices for the most appropriate event.
+==== Example 1: Detecting Peak Ground Reaction Force ====
+This example uses the **Event_Threshold** command to detect the event Max_GRF when the vertical ground reaction force (GRF_Z) crosses 1000N in the ascending direction:
-<HTML><ul></HTML>
+<code>
-<HTML><li></HTML>For the first occurrence:
+Event_Threshold
-/Ensure_Range_Frames_Before_Threshold_Crossing=**true**
+/RESULT_EVENT_NAME= Max_GRF
-/Ensure_Range_Frames_After_Threshold_Crossing=**false**
+/SIGNAL_TYPES=FORCE
-OR
+! /SIGNAL_FOLDER=ORIGINAL
-/Ensure_Range_Frames_Before_Threshold_Crossing=**false**
+/SIGNAL_NAMES=GRF_Z
-/Ensure_Range_Frames_After_Threshold_Crossing=**false**
+! /SIGNAL_COMPONENTS=
-/Event_Instance=1<HTML></li></HTML>
+! /FRAME_OFFSET=0
-<HTML><li></HTML>For the last occurrence:
+! /TIME_OFFSET=
-/Ensure_Range_Frames_Before_Threshold_Crossing=**false**
+! /EVENT_SEQUENCE=
-/Ensure_Range_Frames_After_Threshold_Crossing=**true**
+! /EXCLUDE_EVENTS=
-OR
+! /EVENT_SEQUENCE_INSTANCE=0
-/Ensure_Range_Frames_Before_Threshold_Crossing=**false**
+! /EVENT_SUBSEQUENCE=
-/Ensure_Range_Frames_After_Threshold_Crossing=**false**
+! /SUBSEQUENCE_EXCLUDE_EVENTS=
-/Event_Instance=-1<HTML></li></HTML>
+! /EVENT_SUBSEQUENCE_INSTANCE=0
-<HTML><li></HTML>For all occurrences:
+! /EVENT_INSTANCE=0
-/Ensure_Range_Frames_Before_Threshold_Crossing=**false**
+/THRESHOLD= 1000
-/Ensure_Range_Frames_After_Threshold_Crossing=**false**
+/ON_ASCENT= TRUE
-/Event_Instance=0<HTML></li></HTML>
+! /ON_DESCENT=
-<HTML><li></HTML>If you would like the event to be at the frame before the first crossing:
+! /FRAME_WINDOW=8
-/Ensure_Range_Frames_Before_Threshold_Crossing=**false**
+! /ENSURE_FRAMES_BEFORE=FALSE
-/Ensure_Range_Frames_After_Threshold_Crossing=**false**
+! /ENSURE_FRAMES_AFTER=FALSE
-/Event_Instance=-1<HTML></li></HTML><HTML></ul></HTML>
+;
+</code>
-==== THRESHOLD Parameter ====
+==== Example 2: Maintaining Event Window after Threshold Closing ====
+In this example, the events **FP3_Y** and **FP3_Y_ENSURE** are created using the command. The event **FP3_Y_ENSURE** will use the "Ensure Window After" option within the dialog box, which guarantees that the event window remains open for a specified duration after the triggering condition is met.
-The Threshold parameter can be:
+To ensure correct functionality of the example, the following must be done:
+  - Import the SIGNAL_TYPE/FOLDER or enter these parameters manually into the text editor.
+  - Specify only one signal component at a time.
+  - One of either **ON_ASCENT** or **ON_DESCENT** must be selected, if neither option is selected then no events will be created. In this example, we will chose to label on Ascent.
-**a number**
+<code>
-**a PROCESSED METRIC**
+Event_Threshold
-**an expression**
+/RESULT_EVENT_NAME= FP3_Y
-\\
+/SIGNAL_TYPES= FORCE
-For example:
+/SIGNAL_NAMES= FP3
+! /SIGNAL_FOLDER= ORIGINAL
+/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
+! /SELECT_X=
+! /SELECT_Y=
+! /SELECT_Z=
+! /SELECT_RESIDUAL=
+! /START_AT_EVENT=
+! /END_AT_EVENT=
+/THRESHOLD= 0.05
+/ON_ASCENT= TRUE
+/ON_DESCENT= FALSE
+/FRAME_WINDOW= 25
+/ENSURE_FRAMES_BEFORE= FALSE
+/ENSURE_FRAMES_AFTER= FALSE
+;
-**a number**
+Event_Threshold
-/Threshold= 1
+/RESULT_EVENT_NAME= FP3_Y_ENSURE
-**a PROCESSED METRIC**
+/SIGNAL_TYPES= FORCE
-If a METRIC value is stored in the PROCESSED folder, the Event_Threshold command will recognize and use the signal based only on the signal nema.
+/SIGNAL_NAMES= FP3
-Given a METRIC signal named THRESH stored in the PROCESSED folder, you can specify the parameter as:
+! /SIGNAL_FOLDER= ORIGINAL
-/Threshold= THRESH
+/SIGNAL_COMPONENTS= Y
-**an expression**
+! /FRAME_OFFSET= 0
-It is also possible to use expressions, but when using expressions you must use the full signal name.
+! /TIME_OFFSET=
-Given a METRIC signals THRESH that is stored in a folder labeled TEST
+! /EVENT_SEQUENCE=
-/Threshold= METRIC::TEST::THRESH
+! /EXCLUDE_EVENTS=
-But you can also elaborate this expression, such as
+! /EVENT_SEQUENCE_INSTANCE= 0
-/Threshold= 1.0 + 0.2 * METRIC::TEST::THRESH
+! /EVENT_SUBSEQUENCE=
-\\
+! /SUBSEQUENCE_EXCLUDE_EVENTS=
+! /EVENT_SUBSEQUENCE_INSTANCE= 0
+! /EVENT_INSTANCE= 0
+! /SELECT_X=
+! /SELECT_Y=
+! /SELECT_Z=
+! /SELECT_RESIDUAL=
+! /START_AT_EVENT=
+! /END_AT_EVENT=
+/THRESHOLD= 0.05
+/ON_ASCENT= TRUE
+/ON_DESCENT= FALSE
+/FRAME_WINDOW= 25
+/ENSURE_FRAMES_BEFORE= FALSE
+/ENSURE_FRAMES_AFTER= TRUE
+;
+</code>
+=== Result ===
+After running this pipeline, you will notice 3 events have been created:
+  * 2 instances of **FP3_Y**, crosses the threshold (0.05) two times during the trial.
+  * 1 instance of **FP3_Y_ENSURE**, crosses the threshold (0.05) and stays above the threshold for the frame window (25) one time during the trial.
+{{:EventThreshold_FP3_Y_Ensure_Graph.jpg}}
-----
-==== Example ====
+===== Notes =====
-\\
+=== Visual3D Versions supporting Subject Prefixes ===
-**Create events using the Event_Threshold command**: **FP3_Y and FP3_Y_ENSURE**\\
-\\
-The event **FP3_Y_ENSURE** will use the Ensure Window After option on the dialog box.\\
-\\
-**Make sure to:**\\
-) Import the SIGNAL_TYPE/FOLDER or enter these parameters manually into the text editor\\
-) Only one signal component may be specified at a time\\
-) Select label on Ascent/Descent - if neither are selected no events will be created\\
-\\
-|<code>\\ Event_Threshold\\ /RESULT_EVENT_NAME= FP3_Y\\ /SIGNAL_TYPES= FORCE\\ /SIGNAL_NAMES= FP3\\ ! /SIGNAL_FOLDER= ORIGINAL\\ /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\\ ! /SELECT_X= \\ ! /SELECT_Y= \\ ! /SELECT_Z= \\ ! /SELECT_RESIDUAL= \\ ! /START_AT_EVENT= \\ ! /END_AT_EVENT= \\ /THRESHOLD= 0.05\\ /ON_ASCENT= TRUE\\ /ON_DESCENT= FALSE\\ /FRAME_WINDOW= 25\\ /ENSURE_FRAMES_BEFORE= FALSE\\ /ENSURE_FRAMES_AFTER= FALSE\\ ; \\ </code>  |  {{:EventThreshold_FP3_Y.jpg}}|
-\\
-|<code>\\ Event_Threshold \\ /RESULT_EVENT_NAME= FP3_Y_ENSURE\\ /SIGNAL_TYPES= FORCE\\ /SIGNAL_NAMES= FP3\\ ! /SIGNAL_FOLDER= ORIGINAL\\ /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\\ ! /SELECT_X= \\ ! /SELECT_Y= \\ ! /SELECT_Z= \\ ! /SELECT_RESIDUAL= \\ ! /START_AT_EVENT= \\ ! /END_AT_EVENT= \\ /THRESHOLD= 0.05\\ /ON_ASCENT= TRUE\\ /ON_DESCENT= FALSE\\ /FRAME_WINDOW= 25\\ /ENSURE_FRAMES_BEFORE= FALSE\\ /ENSURE_FRAMES_AFTER= TRUE\\ ; \\ </code>  |  {{:EventThreshold_FP3_Y_Ensure.jpg}}|
-\\
-\\
-\\
-=== Example - Result ===
-\\
-|Three events should be created:\\ 2 Instances of **FP3_Y** -\\ \\ The FP3_Y signal crosses the threshold (0.05) two times during the trial\\ \\ 1 Instance of **FP3_Y_ENSURE** -\\ \\ The FP3_Y signal crosses the threshold (0.05) and stays above the threshold for the frame window (25) one time during the trial  |{{:EventThreshold_FP3_Y_Ensure_Graph.jpg}}  |
-==== 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.