Differences

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

--- visual3d:documentation:pipeline:event_commands:event_global_maximum [2024/07/12 13:29] – removed sgranger
+++ visual3d:documentation:pipeline:event_commands:event_global_maximum [2025/04/28 17:39] (current) – [Dialog] wikisysop
@@ Line 1: / Line 1: @@
+====== Event Global Maximum ======
+===== Overview =====
+This command identifies the global maximum of a specified signal within a given time range and creates an event at that peak value. This command is useful for detecting peak joint angles, force plate data peaks, or maximum velocity in motion capture trials.
+  * The result will be one maximum value over the range.
+  * If the local maxima are needed, see the [[Visual3D:Documentation:Pipeline:Event_Commands:Event_Maximum|Event_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]]
+===== Pipeline Command =====
+The following command shows the most recent update, **Version 6**.
+<code>
+Event_Global_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
+! /THRESHOLD=
+;
+</code>
+Older versions of the command are listed in the notes section at the end of this page.
+===== Command Parameters =====
+The following table shows the command parameters and descriptions:
+|**Parameter**                     |**Description**|
+|**/RESULT_EVENT_NAME=**           | Name of the event that will be created at the frame where the signal reaches its global maximum. |
+|**!/SIGNAL_TYPES=**               | The type of signal being analyzed (e.g., `ANALOG`, `LINK_MODEL_BASED`, `TARGET`). |
+|**!/SIGNAL_FOLDER=**              | Folder the signal is pulled from (e.g., `ORIGINAL`, `PROCESSED`, etc.). |
+|**!/SIGNAL_NAMES=**               | Label(s) of the signal(s) to analyze (e.g., `Left_Knee_Angle`). |
+|**!/SIGNAL_COMPONENTS=**          | Specific components (X, Y, Z) or index of the signal vector to use. |
+|**!/FRAME_OFFSET=**               | Number of frames to shift the result event forward or backward from the identified maximum. |
+|**!/TIME_OFFSET=**                | Time (in seconds) to shift the result event from the identified maximum. |
+|**!/EVENT_SEQUENCE=**             | Defines the sequence of events within which the search should occur. |
+|**!/EXCLUDE_EVENTS=**             | Events that will exclude a sequence if found within it. |
+|**!/EVENT_SEQUENCE_INSTANCE=**   | Specifies which instance of the sequence to use (0 = all, 1 = first, -1 = last, etc.). |
+|**!/EVENT_SUBSEQUENCE=**          | Define a narrower range within the main event sequence to search. |
+|**!/SUBSEQUENCE_EXCLUDE_EVENTS=**| Exclude a subsequence based on the presence of specific events. |
+|**!/EVENT_SUBSEQUENCE_INSTANCE=**| Choose a specific subsequence instance (0 = all, 1 = first, etc.). |
+|**!/THRESHOLD=**                  | Minimum value the signal must reach to qualify as a maximum. |
+===== 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 command. The dialog box is shown below:
+{{:visual3d:documentation:pipeline:event_commands:egm_dialog.png?500|}}
+  * **New Event Label Name**: Name for the event that will be created at the global maximum.
+  * **Signal Component**: Signal direction selection (X, Y, Z).
+  * **Frame Offset**: Number of frames to shift the created event forward or backward from the maximum point.
+  * **Time Offset**: Shifts event by time (in seconds).
+  * **Threshold**: Min. signal value required to accept a maximum.
+  * **Event Sequence and Instance for range**: Search for maximum based on event ranges.
+  * **Subsequence and Instance within the Event Sequence**: Search inside a sub-range within the event sequence.
+===== Examples =====
+The following example will go through the use of the **Event_Global_Maximum** command in the Visual3D application.
+This command may be used to create an event RKFlex_Max at the maximum knee flexion angle during the gait cycle. The gait cycle is indicated by the RHS events. This example will go through different use cases of this command:
+\\
+**Example 1)** The maximum value of the signal may be over the entire signal
+\\
+**Example 2)** The maximum value of the signal may be during an event sequence
+\\
+**Example 3)** A specific event sequence may be excluded
+**NOTE:** If no events are specified in the Event Sequence, a global maximum over the whole trial will be created.\\
+==== Example 1: Simple Use Case ====
+This example will be done showing both the dialog box and corresponding command text.
+To create the RKFlex_Max event using the Event_Global_Maximum dialog box:
+\\
+**1. Enter information into dialog box:**
+\\
+  * **Event_Name:** RKFlex_Max
+  * **Select Frame Offset:** 0
+  * **Signal Components:** X
+  * **Event Sequence Instance:** 0
+  * **Defined Events:** RHS + RHS
+  * Click **OK**
+|{{:Event_Global_Max_RKFlex_Max.jpg?500}}|  <code>
+Event_Global_Maximum
+/RESULT_EVENT_NAME=RKFlex_Max
+! /SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+/SIGNAL_COMPONENTS=X
+! /FRAME_OFFSET=0
+! /TIME_OFFSET=
+/EVENT_SEQUENCE=RHS+RHS
+! /EXCLUDE_EVENTS=
+! /EVENT_SEQUENCE_INSTANCE=0
+! /EVENT_SUBSEQUENCE=
+! /SUBSEQUENCE_EXCLUDE_EVENTS=
+! /EVENT_SUBSEQUENCE_INSTANCE=0
+! /THRESHOLD=
+;
+</code>|
+**2. Select desired signal:**
+\\
+  * Select **signal from data tree** Right_Knee_Angle
+  * Click **Import Selected Signals**
+{{:Event_Global_Max_RKFlex_Max_Import.jpg?550}}
+Two instances of **RKFlex_Max** were created, one in between each sequence of **RHS+RHS**.
+{{:Event_Global_Max_RKFlex_Max_Graph.jpg?550}}
+----
+==== Example 2: Exclude Sequence ====
+In this example an event **BAD** was created between one sequence of **RHS + RHS**. Using the same parameters as the previous example, set the **Exclude Sequences containing events** parameter to **BAD**
+|{{:Event_Global_Max_RKFlex_Max_Exclude.jpg}}|<code>
+Event_Global_Maximum
+/RESULT_EVENT_NAME=RKFlex_Max
+! /SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+/SIGNAL_COMPONENTS=X
+! /FRAME_OFFSET=0
+! /TIME_OFFSET=
+/EVENT_SEQUENCE=RHS+RHS
+/EXCLUDE_EVENTS=BAD
+! /EVENT_SEQUENCE_INSTANCE=0
+! /EVENT_SUBSEQUENCE=
+! /SUBSEQUENCE_EXCLUDE_EVENTS=
+! /EVENT_SUBSEQUENCE_INSTANCE=0
+! /THRESHOLD=
+;
+</code>|
+Only one RKFlex_Max event was created because the second sequence containing the event **BAD** was excluded:
+{{:Event_Global_Max_RKFlex_Max_Exclude_Graph.jpg?550}}
+----
+==== Example 3: Subsequence ====
+Subsequences can be used to create an event that occurs within a sequence within a sequence.
+In this example **RKFlex_Max** was created as the maximum value between **LTO + LHS** when these events fall between the **RHS** events.
+Using the same parameters as the previous example, set the **Subsqeuence** parameter to **LTO + LHS**
+|{{:Event_Global_Max_RKFlex_Max_Subsequence.jpg}}|<code>
+Event_Global_Maximum
+/RESULT_EVENT_NAME=RKFlex_Max
+! /SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+/SIGNAL_COMPONENTS=X
+! /FRAME_OFFSET=0
+! /TIME_OFFSET=
+/EVENT_SEQUENCE=RHS+RHS
+! /EXCLUDE_EVENTS=
+! /EVENT_SEQUENCE_INSTANCE=0
+/EVENT_SUBSEQUENCE=LTO+LHS
+! /SUBSEQUENCE_EXCLUDE_EVENTS=
+! /EVENT_SUBSEQUENCE_INSTANCE=0
+! /THRESHOLD=
+;
+</code>|
+**RKFlex_Max** event was created between **RHS** events that contained the **LTO to LHS** subsequence.
+{{:Event_Global_Max_RKFlex_Max_Subsequence_Graph.jpg?550}}
+----
+====Notes====
+=== Version 4 ===
+<code>
+Event_Global_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
+/Radius= 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
+</code>
+Dialog that pops up when pipeline selection is edited by double clicking with the left mouse button.
+{{:Eventglobalminmaxdlg.gif}}