Differences

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

--- visual3d:documentation:pipeline:event_commands:event_maximum [2024/07/16 19:27] – created sgranger
+++ visual3d:documentation:pipeline:event_commands:event_maximum [2025/04/29 19:04] (current) – wikisysop
@@ Line 1: / Line 1: @@
-====== Event_Maximum ======
+====== Event Maximum ======
-\\
+===== Overview =====
-**Specify an Event Label(s) at the specified local Maxima of a signal.**
+The **Event_Maximum** command is used to detect the maximum value of a specified signal within a defined event sequence or range, and create an event at that location. This command can evaluate different components of a signal (X, Y, Z, Residual) and can apply offsets to shift the detected event if needed.
+  * Useful for identifying peak forces, peak joint angles, or maximum accelerations during specific phases of a motion, such as between initial contact and toe-off during gait.
+  * If the global maxima are needed, see the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Global_Maximum|Event_Global_Maximum]] command
+  * To review the difference between local and global maximum values please see [[Visual3D:Documentation:Pipeline:General_Information:Global_vs_Loca_Max_and_Min|here]]
-**If the global maxima are needed, see the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Global_Maximum|Event_Global_Maximum]] command\\
+===== Pipeline Command =====
-**\\
+The command below is as seen in the Visual3D application:
-To review the difference between local and global maximum values please see [[Visual3D:Documentation:Pipeline:General_Information:Global_vs_Loca_Max_and_Min|here]].
-==== Visual3D_Version5 ====
+<code>
+Event_Maximum
+/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
+! /FRAME_WINDOW=8
+! /THRESHOLD=
+;
+</code>
-In version 5 the command has been extended to include the Event_Sequence and Exclude_Events parameters.
+===== Command Parameters =====
+The following table shows the command parameters and descriptions:
-|**Event_Maximum**\\ \\ /RESULT_EVENT_NAME=EVENT_MAX\\ \\ /SIGNAL_TYPES=TARGET\\ \\ /SIGNAL_FOLDER=ORIGINAL\\ \\ /SIGNAL_NAMES=LFT2\\ \\ /SIGNAL_COMPONENTS=Z\\ \\ /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=0.14\\ \\ **;**|{{EventMaximumDlg5.jpg}}|
+|**Parameter**  |**Description**|
+|**/RESULT_EVENT_NAME=**|The name assigned to the detected peak event.|
+|**!/SIGNAL_TYPES=**|Indicates type of signal analyzed.|
+|**!/SIGNAL_FOLDER=ORIGINAL**|Specifies the folder containing the target signal (typically ORIGINAL)|
+|**!/SIGNAL_NAMES=**|The name of the signal to analyze.|
+|**!/SIGNAL_COMPONENTS**|Which components to evaluate (X, Y, Z, Residual)|
+|**!/FRAME_OFFSET=**|Optional offset in frames to shift the detected event.|
+|**!/TIME_OFFSET=**|Optional offset in seconds to shift the detected event.|
+|**!/EVENT_SEQUENCE=**|Defines the sequence of events used.|
+|**!/EXCLUDE_EVENTS=**|Events to exclude within the sequence.|
+|**!/EVENT_SEQUENCE_INSTANCE=0**|Specifies which instance of the sequence to evaluate (0 to consider ALL)|
+|**!/EVENT_SUBSEQUENCE=**|Defines a smaller sequence within the main even sequence.|
+|**!/SUBSEQUENCE_EXCLUDE_EVENTS**|Events to exclude from the subsequence.|
+|**!/EVENT_SUBSEQUENCE_INSTANCE=0**|Specifies which instance of the subsequence to evaluate.|
+|**!/EVENT_INSTANCE=**|Specifies which instance of the event to label (0 for all, positive for first occurrences, negative for last occurrences).|
+|**!/FRAME_WINDOW=**|Number of frames around the maximum that must satisfy the threshold.|
+|**!/THRESHOLD=**|Defines the minimum value the signal must reach to qualify as a peak.|
-\\
-Other options within the command such as **Exclude Event**, and **Select Subsequence** are explained in detail on the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Global_Maximum#Examples|Event_Global_Maximum]] page.
-If /Threshold is empty, all local maximum are identified.
+===== Dialog =====
+The command can be edited in a text editor or in the dialog. To edit in the dialog, click on the **Edit** button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below:
-If /Threshold has a value or expression, only local maximum that are greater than the threshold are identified.
+{{:visual3d:documentation:pipeline:event_commands:event_max_dialog.png?400|}}
+  * **New Event Label Name**: Name of event created at the local maximum points.
+  * **Signal Component**: Which direction of the signal to analyze.
+  * **Frame Window**: Size of window to look for a local maximum around each frame.
+  * **Frame Offset**: Shift the resulting event by a number of frames.
+  * **Time Offset**: Move the event by a time shift (in seconds)
+  * **Threshold**: Only create an event if the maximum exceeds this value.
+  * **Event Instance to Create**: Choose which maximum to create if there are multiple peaks in a search window
+  * **Event Sequence and Instance for Range**: Limits where to search for maxima
+  * **Subsequence and Instance within Event Sequence**: Further limits search inside smaller phase within main event range.
 ----
+===== Examples =====
+The following examples will go through the use of the **Event_Maximum** command in the Visual3D application.
-\\
+==== Example 1: Simple Use Case ====
+The first example will cover the command using the dialog as well as the command text. To create the RKFlex_MaxLocal event using the Event_Maximum dialog box:
+. Add the **Event_Maximum** command to the pipeline. Then, enter information into dialog box:
-=== Example - Dialog Box ===
+**Event_Name:** RKFlex_MaxLocal\\
+**Select Frame Offset:** 0\\
+**Signal Components:** X\\
+**Event Sequence Instance:**0\\
-To create the RKFlex_MaxLocal event using the Event_Maximum dialog box:
-\\
+|{{:visual3d:documentation:pipeline:event_commands:eventmax_ex1_dialogbox.png?600|}}|<code>
+Event_Maximum
+/RESULT_EVENT_NAME=RKFlex_MaxLocal
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=RFT
+/SIGNAL_NAMES=AngAcc
+/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=40
+! /THRESHOLD=
+;
+</code>|
+. Close the dialog, on the Signals and Events tab, select the desired signal from the data tree, in this case **Right_Knee_Angle**. Navigate into the LINK_MODEL_BASED items folder, and select the checkbox beside the signal.
-|**1. Enter information into dialog box:**\\ \\ **Event_Name:** RKFlex_MaxLocal\\ \\ **Select Frame Offset:**0\\ \\ **Signal Components:**X\\ \\ **Select an event sequence and Instance for the range:**\\ \\ **Event Sequence Instance:**0\\ \\ **Defined Events:**RHS + RHS\\ \\ Click **OK**  |  {{Event_Max_RKFlex_MaxLocal.jpg}}|
+. Open the pipeline workshop again, and then click on **Import Selected Signals**.\\
+{{:Event_Max_RKFlex_MaxLocal_Import.jpg?600}}
-\\
+**RKFlex_MaxLocal** will be created at the maximum values during the full gait cycle. As seen below:
+|{{:visual3d:documentation:pipeline:event_commands:eventmax_ex1_corrected_graph.png?600|}}|
-|**2. Select desired signal:**\\ \\ Select **signal from data tree** Right_Knee_Angle\\ \\ Click **Import Selected Signals**  |  {{Event_Max_RKFlex_MaxLocal_Import.jpg}}|
-\\
+==== Example 2: Complex ====
-**RKFlex_Max** will be created at the minimum value during the gait cycle within the specified frame window.\\
-\\
-Other options within the command such as **Exclude Event**, and **Select Subsequence** are explained in detail on the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Global_Maximum#Examples|Event_Global_Maximum]] page.
+In this example, the local maxima of the right foot angular acceleration during the full trial is identified. Then, the values of this event are extracted.
-----
+Use the Event_Maximum command to find the peaks in the acceleration signal, the component is set to Y and frame window is increased to 60.
+The signal used to represent the acceleration was taken from the KINETIC_KINEMATIC folder - RFT (Right Foot)
+<code>
+Event_Maximum
+/RESULT_EVENT_NAME=Right_Accel_Peak_Stance
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=RFT
+/SIGNAL_NAMES=AngAcc
+/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=60
+! /THRESHOLD=
+;
+</code>
+Then use Metric_Signal_Value_At_Event to extract the actual Y-acceleration values at these peaks for analysis:
+<code>
+Metric_Signal_Value_At_Event
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=RFT
+/SIGNAL_NAMES=AngAcc
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=Right_Accel_Peak_Stance_Times
+! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
+/SIGNAL_COMPONENTS=Y
+! /COMPONENT_SEQUENCE=
+/EVENT_NAME=Right_Accel_Peak_Stance
+! /EVENT_INSTANCE=0
+! /SCALE_FACTORS=1
+! /GENERATE_GLOBAL_MEAN_AND_STDDEV=TRUE
+! /GENERATE_LOCAL_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+! /GENERATE_VECTOR_LENGTH_METRIC=FALSE
+! /RETAIN_NO_DATA_VALUES=FALSE
+;
+</code>
+===== Notes =====
+=== Version 5 ===
+In version 5 the command has been extended to include the Event_Sequence and Exclude_Events parameters.
+|{{:EventMaximumDlg5.jpg}}|<code>
+Event_Maximum
+/RESULT_EVENT_NAME=EVENT_MAX
+/SIGNAL_TYPES=TARGET
+/SIGNAL_FOLDER=ORIGINAL
+/SIGNAL_NAMES=LFT2
+/SIGNAL_COMPONENTS=Z
+/FRAME_OFFSET=0
+!/TIME_OFFSET=
+!/EVENT_SEQUENCE=
+!/EXCLUDE_EVENTS=
+!/EVENT_SEQUENCE_INSTANCE=0
+!/EVENT_SUBSEQUENCE=
+!/SUBSEQUENCE_EXCLUDE_EVENTS=
+!/EVENT_INSTANCE=0
+!/FRAME_WINDOW-8
+/THRESHOLD=0.14
+;
+</code>|
+  * Other options within the command such as **Exclude Event**, and **Select Subsequence** are explained in detail on the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Global_Maximum#Examples|Event_Global_Maximum]] page.
+  * If /Threshold is empty, all local maximum are identified.
+  * If /Threshold has a value or expression, only local maximum that are greater than the threshold are identified.
+=== Version 4 ===
-===== Version 4 =====
+<code>
+Event_Maximum
+/Signal_Types=The type of signal to be evaluated
+/Signal_Names=The names of the signals to be evaluated
+/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
+/Frame_Window=The range of frames of data that must be below the maximum
+/Start_At_Event=The search begins from the start event
+/End_At_Event=The search ends at the end event
+/Event_Instance=
+;
+</code>
-|\\ \\ \\ <code>\\ Event_Maximum\\ /Signal_Types=The type of signal to be evaluated\\ /Signal_Names=The names of the signals to be evaluated\\ /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\\ /Frame_Window=The range of frames of data that must be below the maximum\\ /Start_At_Event=The search begins from the start event\\ /End_At_Event=The search ends at the end event\\ /Event_Instance=\\ ;\\ </code>\\ \\ \\   |  Dialog that pops up when pipeline selection is edited by double clicking with the left mouse button.\\ {{MinMaxDlg.jpg}}  |
+Dialog that pops up when pipeline selection is edited by double clicking with the left mouse button.
-**Event Instance:** There may be several local maxima. A value of 0 results in all maxima 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.
+{{:MinMaxDlg.jpg}}