Differences

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

--- visual3d:documentation:pipeline:event_commands:event_tpr_signal [2025/04/23 18:30] – [Overview] wikisysop
+++ visual3d:documentation:pipeline:event_commands:event_tpr_signal [2025/04/28 18:38] (current) – wikisysop
@@ Line 1: / Line 1: @@
 ====== Event TPR Signal ======
-==== Overview ====
+===== Overview =====
 The Event_TPR_Signal command performs pattern recognition on a signal by scanning the trial for segments that match a **Target Pattern Recognition (TPR) file**. When a segment of the trial is sufficiently similar to the pattern, an event is placed at the frame of best match.
@@ Line 9: / Line 9: @@
-==== Pipeline Command ====
+A **pattern file** mut be available. This file defines the reference shape that Visual3D will try to match in the trial, it must also use the same signal type and coordinate structure.
+===== 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.
 <code>
@@ Line 31: / Line 33: @@
 </code>
-==== Event TPR Signal Command Details ====
+===== Command Parameters =====
-The command details are below:
+The following table shows the command parameters and descriptions:
-|**Event_TPR_Signal**        |                                                                                                              |
+|**Parameter**              |**Description**    |
-|**/Pattern_File=**          |The file from which to find the pattern signal. If this is blank, the pattern signal is taken from each trial.|
+|**/SIGNAL_TYPES=**         | Type of signal used for matching: typically `LINK_MODEL_BASED`, `ANALOG`, or `TARGET`. |
-|**/Pattern_Type=**          |The type of signal used as the test signal.                                                                   |
+|**!/SIGNAL_FOLDER=**       | Folder the matching signal is located in (e.g., `ORIGINAL`, `FILTERED`, `PROCESSED`). |
-|**/Pattern_Signal=**        |The names of the signals used as the test signal.                                                             |
+|**/SIGNAL_NAMES=**         | The label of the signal being scanned for pattern matches (e.g., `Rectified_EMG1`). |
-|**/Pattern_Folder=**        |The name of the signal folder used as the test signal.                                                        |
+|**!/PATTERN_FILE=**        | Filename of the file containing the reference waveform pattern. |
-|**/Signal_Types=**          |The type of signal to be compared with the test signal.                                                       |
+|**!/PATTERN_TYPE=**        | The type of signal in the pattern file - must match the matching signal type. |
-|**/Signal_Names=**          |The names of the signals to be compared with the test signal.                                                 |
+|**!/PATTERN_FOLDER=**      | Folder used when the pattern was saved (e.g., `FILTERED`, `NORMALIZED`). |
-|**/Signal_Folder=**         |The name of the signal folder compared with the test signal.                                                  |
+|**!/PATTERN_SIGNAL=**      | Signal name from which the pattern was originally taken. |
-|**/Pattern_Event_Name=**    |The event at which the pattern signal is centered.                                                            |
+|**/PATTERN_EVENT_NAME=**   | Event used in the original pattern file that marks the center of the pattern window. |
-|**/Pattern_Event_Instance=**|The occurence of the event at which the pattern signal is centered.                                           |
+|**!/PATTERN_EVENT_INSTANCE=**| Which instance of the pattern event to use (e.g., 1 = first, 2 = second). |
-|**/Event_Name=**            |The name to be given to the threshold event.                                                                  |
+|**!/SELECT_X, Y, Z=FALSE** | Indicates which component(s) of the signal vector to compare - set `TRUE` for any axis you want matched. |
-|**/Select_X=**              |(True or False)Use this component of the signals.                                                             |
+|**!/TPR_WINDOW=**          | Length of the matching window (in frames). Must match the length used when saving the pattern file. |
-|**/Select_Y=**              |(True or False)Use this component of the signals.                                                             |
+|**!/TOLERANCE=**           | Similarity threshold for match detection. Lower = stricter matching. Value depends on signal type. |
-|**/Select_Z=**              |(True or False)Use this component of the signals.                                                             |
+|**/EVENT_NAME=**           | Name of the event that will be created when a match is found. |
-|**/TPR_Window=**            |The range of frames of data used for the comparison.                                                          |
-|**/Tolerance=**             |The "goodness of fit" for the match.                                                                          |
-\\
+=====Dialog=====
 A dialog will pop up when pipeline selection is edited by double clicking with the left mouse button (see diagram below).
@@ Line 64: / Line 65: @@
   * Changing the **radius** will change the number of frames used.
   * The parameter SIGNAL_TYPES and SIGNAL_NAMES are required parameters and need to be specified. This can be done by editing the command via the "Text" button or importing the selected signals through the "Import Selected Signals" button.
-  * If you wish to save the TPR signal for further use in other cmo files for pattern matching, then use the dialog to set the parameters and then click **Save TPR Signal** button. The button will not appear until you have completed setting the parameters. After clicking the button, a browser will open and you can select a folder and filename for your TPR signal file. The file extension will be .tps. Go to [[Visual3D:Documentation:Pipeline:Event_Commands:Event_TPR_File|Event_TPR_File]] for details on the command to apply the saved .tps file.
+  * If you wish to save the TPR signal for further use in other CMZ files for pattern matching, then use the dialog to set the parameters and then click **Save TPR Signal** button. The button will not appear until you have completed setting the parameters. After clicking the button, a browser will open and you can select a folder and filename for your TPR signal file. The file extension will be .tps. Go to [[Visual3D:Documentation:Pipeline:Event_Commands:Event_TPR_File|Event_TPR_File]] for details on the command to apply the saved .tps file.
-==== Example ====
+===== Examples =====
+The following examples will show the use of the Event_TPR_Signal command in the Visual3D application.
+====Example 1: Matching Opposite-side Gait Events====
+In some cases, users may already have events defined for one side of the participant's body- instead of having to redefine these events for the opposite side, let this command use the Target Pattern Recognition feature to identify them automatically. The following steps can be taken for this example:
+**1.** As you can see, a .c3d file is loaded in which contains ONLY **Left-side** events.
+{{:visual3d:documentation:pipeline:event_commands:only_left_events_shown.png?300|}}
+**2.** Either in the command dialog box, or within the text editor, enter the following details, this is converting the Left Heel Strike event to the same on the Right Side:
+|{{:visual3d:documentation:pipeline:event_commands:event_tpr_ex1.png?400|}}|<code>
+Event_TPR_Signal
+/SIGNAL_TYPES=LINK_MODEL_BASED
+! /SIGNAL_FOLDER=ORIGINAL
+/SIGNAL_NAMES=R Hip Angle
+/PATTERN_FILE=[USER SELECTION]
+/PATTERN_TYPE=LINK_MODEL_BASED
+! /PATTERN_FOLDER=ORIGINAL
+/PATTERN_SIGNAL=L Hip Angle
+/PATTERN_EVENT_NAME=LHS
+! /PATTERN_EVENT_INSTANCE=1
+/SELECT_X=TRUE
+! /SELECT_Y=FALSE
+! /SELECT_Z=FALSE
+! /TPR_WINDOW=7
+! /TOLERANCE=20.0
+/EVENT_NAME=RHS
+;
+</code>|
+For the **Pattern File**, I have it set for the trial which contains the pre-determined events. This will essentially be applying the same logic that goes for one side of the participant's body to the other.
+After this pipeline command has been run, the RHS event will begin to show as well. However, if you were to graph the R Hip Angle, you may notice that there are many more occurrences than expected, the number of frames being evaluated may need to be changed in order to better represent the number of occurrences. The following adjustment was made:
+<code>
+/TPR_WINDOW=30
+</code>
+The following image shows both the Left and Right Hip Angles with the highlighted events (Blue- LHS, Red- RHS):
+{{:visual3d:documentation:pipeline:event_commands:tpr_image_ex.png?500|}}
+====Example 2====
+Automatically detect right foot strike during running using the Y-axis acceleration of the right ankle, based on a template waveform. Then, save a refined version of this event’s pattern and evaluate how well it aligns with the force plate contact (`RHS`).
-Below is an example script:
 <code>
@@ Line 94: / Line 141: @@
+----
+=====Notes=====
+A description of the use of TPR for determining gait events when a force platform signal is present is presented in the following article:
+**Stanhope SJ, Kepple TM, McGuire DA, Roman NL.**(1990) "A Kinematic-Based Technique for Event Time Determination During Gait." Medical and Biological Engineering and Computing 28:355-360.