Event Threshold

Overview

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 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.

The command acts on the data at the sampling rate of the signal selected (i.e. not necessarily at the POINT rate)

The command looks for the threshold crossing in which the threshold has been crossed for all frames in the selected FRAME_WINDOW (before and/or after).

In other words, if any subframe does not meet the criteria, the threshold crossing is ignored.

The event time is determined by rounding up the time of crossing to the next POINT frame.

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.

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
;

Command Parameters

The following table shows the command parameters and descriptions:

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.

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.

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.

Examples

The following examples will go through the use of the Event_Threshold command in the Visual3D application.

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:

Event_Threshold
/RESULT_EVENT_NAME= Max_GRF
/SIGNAL_TYPES=FORCE
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=GRF_Z
! /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= 1000
/ON_ASCENT= TRUE
! /ON_DESCENT=
! /FRAME_WINDOW=8
! /ENSURE_FRAMES_BEFORE=FALSE
! /ENSURE_FRAMES_AFTER=FALSE
;

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.

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.

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
;

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
;

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.

Example 3: Creating Thresholds Using Sub-frames in Analog Data

When creating a new event using Event_Threshold, if this event is created using an analog data signal it may behave slightly differently from thresholds created using other signal types. Analog signals contain sub-frames, as such there may be cases where a threshold is met by certain sub frames and not others. In order for an event to be created, all sub-frames for each frame within the frame window must satisfy the defined threshold.

Say for a hypothetical signal you were wondering if an event would be created at frame 100 and you had set a frame window of 8 frames before the event and the following is true:

Frame 97 and before: all subframes below threshold
Frame 98: all subframes above threshold except one which is below
Frame 99 and after: all subframes above threshold

In this case, no event would be created because frame 98 and the sub-frames within it do not meet the threshold criteria.

The following examples show 2 cases in which a new event would or wouldn't be created given the threshold conditions:

! create a signal that is a copy of the frame numbers

Evaluate_Expression
/EXPRESSION=CURRENT_SIGNAL
/SIGNAL_TYPES=FRAME_NUMBERS
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=FRAMES
! /SIGNAL_COMPONENTS=
! /RESULT_TYPES=DERIVED
! /RESULT_FOLDERS=PROCESSED
 /RESULT_NAME=SCOTT
! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
;

! Create an event at a threshold crossing of 100

Event_Threshold
/RESULT_EVENT_NAME=TEST
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT
/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=100
/ON_ASCENT=TRUE
/ON_DESCENT=FALSE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;

! set two frames of data near the event to zero

Set_Data_To_New_Values
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT
! /SIGNAL_COMPONENTS=ALL_COMPONENTS
/RESULT_TYPES=DERIVED
! /RESULT_FOLDERS=PROCESSED
/RESULT_SUFFIX=_0
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_INSTANCE=0
/START_FRAME=101
/END_FRAME=102
! /USE_POINT_RATE=TRUE
/REPLACEMENT_VALUES=0
! /THRESHOLD_HIGH=NO_DATA
! /THRESHOLD_LOW=NO_DATA
! /SET_DATA_AT_SINGLE_EVENT=FALSE
;

! attempt to create the event and no event will be created

Event_Threshold
/RESULT_EVENT_NAME=TEST_0
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT_0
/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=100
/ON_ASCENT=TRUE
/ON_DESCENT=FALSE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;

Example 2 uses an analog signal. In this case ANALOGTIME. Depending on the analog frame rate in the c3d file you opened, you might need to play around with the frame set to zero.

Evaluate_Expression
/EXPRESSION=CURRENT_SIGNAL
/SIGNAL_TYPES=FRAME_NUMBERS
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=ANALOGTIME
! /SIGNAL_COMPONENTS=
! /RESULT_TYPES=DERIVED
! /RESULT_FOLDERS=PROCESSED
/RESULT_NAME=SCOTT_ANALOG
! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
;

! Event created

Event_Threshold
/RESULT_EVENT_NAME=TEST_ANALOG
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT_ANALOG
/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=1
/ON_ASCENT=TRUE
/ON_DESCENT=FALSE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;
Set_Data_To_New_Values
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT_ANALOG
! /SIGNAL_COMPONENTS=ALL_COMPONENTS
/RESULT_TYPES=DERIVED
! /RESULT_FOLDERS=PROCESSED
/RESULT_SUFFIX=_0
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /EVENT_INSTANCE=0
/START_FRAME=1200
/END_FRAME=1203
/USE_POINT_RATE=FALSE
/REPLACEMENT_VALUES=0
! /THRESHOLD_HIGH=NO_DATA
! /THRESHOLD_LOW=NO_DATA
! /SET_DATA_AT_SINGLE_EVENT=FALSE
;

! Event not created

Event_Threshold
/RESULT_EVENT_NAME=TEST_ANALOG_0
/SIGNAL_TYPES=DERIVED
/SIGNAL_FOLDER=PROCESSED
/SIGNAL_NAMES=SCOTT_ANALOG_0
/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=100
/ON_ASCENT=TRUE
/ON_DESCENT=FALSE
! /FRAME_WINDOW=8
/ENSURE_FRAMES_BEFORE=TRUE
/ENSURE_FRAMES_AFTER=TRUE
;

Notes

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.

HAS-Motion Software Documentation

Table of Contents