Differences

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

--- visual3d:documentation:pipeline:event_commands:event_tpr_signal [2024/07/17 15:22] – sgranger
+++ visual3d:documentation:pipeline:event_commands:event_tpr_signal [2025/04/28 18:38] (current) – wikisysop
@@ Line 1: / Line 1: @@
 ====== Event TPR Signal ======
-TPR signal is based on matching data from a range of frames against the same (or a different signal). When the two ranges match an Event Label is created at the midpoint of the range. For example, if one occurrence of heel strike has been identified, this command can be used to determine all other heel strike events in a file.
+===== Overview =====
-A description of the use of TPR for determining gait events when a force platform signal is present is presented in the following article:
+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.
+  * TPR signal is based on matching data from a range of frames against the same (or a different signal).
+  * When the two ranges match, an Event Label is created at the midpoint of the range.
+  * For example, if one occurrence of heel strike has been identified, this command can be used to determine all other heel strike events in a file.
-**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.
-==== Event TPR Signal Command Details ====
+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.
-The command details are below:
+<code>
+Event_TPR_Signal
+/SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+/SIGNAL_NAMES=
+! /PATTERN_FILE=
+! /PATTERN_TYPE=
+! /PATTERN_FOLDER=ORIGINAL
+! /PATTERN_SIGNAL=
+/PATTERN_EVENT_NAME=
+! /PATTERN_EVENT_INSTANCE=1
+! /SELECT_X=FALSE
+! /SELECT_Y=FALSE
+! /SELECT_Z=FALSE
+! /TPR_WINDOW=7
+! /TOLERANCE=20.0
+/EVENT_NAME=
+;
+</code>
-|**Event_TPR_Signal**        |                                                                                                              |
+===== Command Parameters =====
-|**/Pattern_File=**          |The file from which to find the pattern signal. If this is blank, the pattern signal is taken from each trial.|
-|**/Pattern_Type=**          |The type of signal used as the test signal.                                                                   |
-|**/Pattern_Signal=**        |The names of the signals used as the test signal.                                                             |
-|**/Pattern_Folder=**        |The name of the signal folder used as the test signal.                                                        |
-|**/Signal_Types=**          |The type of signal to be compared with the test signal.                                                       |
-|**/Signal_Names=**          |The names of the signals to be compared with the test signal.                                                 |
-|**/Signal_Folder=**         |The name of the signal folder compared with the test signal.                                                  |
-|**/Pattern_Event_Name=**    |The event at which the pattern signal is centered.                                                            |
-|**/Pattern_Event_Instance=**|The occurence of the event at which the pattern signal is centered.                                           |
-|**/Event_Name=**            |The name to be given to the threshold event.                                                                  |
-|**/Select_X=**              |(True or False)Use this component of the signals.                                                             |
-|**/Select_Y=**              |(True or False)Use this component of the signals.                                                             |
-|**/Select_Z=**              |(True or False)Use this component of the signals.                                                             |
-|**/TPR_Window=**            |The range of frames of data used for the comparison.                                                          |
-|**/Tolerance=**             |The "goodness of fit" for the match.                                                                          |
-\\
+The following table shows the command parameters and descriptions:
+|**Parameter**              |**Description**    |
+|**/SIGNAL_TYPES=**         | Type of signal used for matching: typically `LINK_MODEL_BASED`, `ANALOG`, or `TARGET`. |
+|**!/SIGNAL_FOLDER=**       | Folder the matching signal is located in (e.g., `ORIGINAL`, `FILTERED`, `PROCESSED`). |
+|**/SIGNAL_NAMES=**         | The label of the signal being scanned for pattern matches (e.g., `Rectified_EMG1`). |
+|**!/PATTERN_FILE=**        | Filename of the file containing the reference waveform pattern. |
+|**!/PATTERN_TYPE=**        | The type of signal in the pattern file - must match the matching signal type. |
+|**!/PATTERN_FOLDER=**      | Folder used when the pattern was saved (e.g., `FILTERED`, `NORMALIZED`). |
+|**!/PATTERN_SIGNAL=**      | Signal name from which the pattern was originally taken. |
+|**/PATTERN_EVENT_NAME=**   | Event used in the original pattern file that marks the center of the pattern window. |
+|**!/PATTERN_EVENT_INSTANCE=**| Which instance of the pattern event to use (e.g., 1 = first, 2 = second). |
+|**!/SELECT_X, Y, Z=FALSE** | Indicates which component(s) of the signal vector to compare - set `TRUE` for any axis you want matched. |
+|**!/TPR_WINDOW=**          | Length of the matching window (in frames). Must match the length used when saving the pattern file. |
+|**!/TOLERANCE=**           | Similarity threshold for match detection. Lower = stricter matching. Value depends on signal type. |
+|**/EVENT_NAME=**           | Name of the event that will be created when a match is found. |
+=====Dialog=====
 A dialog will pop up when pipeline selection is edited by double clicking with the left mouse button (see diagram below).
@@ Line 40: / 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 70: / 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.