Differences

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

--- visual3d:documentation:pipeline:signal_commands:cross_correlation [2024/06/19 13:38] – removed sgranger
+++ visual3d:documentation:pipeline:signal_commands:cross_correlation [2024/11/15 19:00] (current) – [RESULT] wikisysop
@@ Line 1: / Line 1: @@
+====== Cross Correlation ======
+The Cross_Correlation command can be used to determine if there is a relationship between two signals when one is shifted relative to the other. This command can also be used to calculate the self-similarity of a signal with a time-delayed version of itself. In this case the command calculates the signal's autocorrelation.
+More about calculating cross-correlations can be found on [[https://en.wikipedia.org/wiki/Cross-correlation|Wikipedia]] and on [[http://paulbourke.net/miscellaneous/correlate/|Paul Bourke's website]].
+===== Cross_Correlation =====
+The **Cross_Correlation** command calculates the cross-correlation between two signals.
+<code>
+Cross_Correlation
+! /SIGNAL_OWNER1=
+/SIGNAL_TYPE1=
+/SIGNAL_FOLDER1=
+/SIGNAL_NAME1=
+! /SIGNAL_COMPONENT1=
+! /SIGNAL_OWNER2=
+/SIGNAL_TYPE2=
+/SIGNAL_FOLDER2=
+/SIGNAL_NAME2=
+! /SIGNAL_COMPONENT2=
+! /RESULT_OWNER=
+! /RESULT_FOLDER= PROCESSED
+/RESULT_NAME=
+! /MAX_DELAY=10
+! /DATA_WRAP=FALSE
+;
+</code>
+{{:Cross_Correlation_Dialog.png}}
+===== Parameters =====
+Understand the parameters of the Cross_Correlation command.
+==== SIGNAL1 ====
+The /SIGNAL_OWNER1, /SIGNAL_TYPE1, /SIGNAL_FOLDER1, and /SIGNAL_NAME1 parameters allow the user to specify which signal (by [[visual3d:documentation:pipeline:file_commands:file_names|file]], [[visual3d:documentation:visual3d_signal_types:data_tree|data type]], [[visual3d:documentation:visual3d_signal_types:data_tree|folder]], and name) should be used as the first signal for the cross-correlation calculation.
+==== SIGNAL2 ====
+Similarly, the /SIGNAL_OWNER2, /SIGNAL_TYPE2, /SIGNAL_FOLDER2, and /SIGNAL_NAME2 parameters allow the user to specify the second signal for the cross-correlation calculation.
+==== RESULT ====
+The /RESULT_OWNER, /RESULT_FOLDER, and /RESULT_NAME parameters allow the user to specify where the result of the cross-correlation calculation should be saved.
+  * The result's data type the DERIVED folder.
+  * The result's folder defaults to being the PROCESSED folder.
+==== MAX_DELAY ====
+The /MAX_DELAY parameter indicates the number of frames the signal will be shifted to determine the correlation. This parameter can be considered as the "window" of frames to be compared across the signal.
+The size of the resulting signal is determined as twice the value of the /MAX_DELAY plus one, e.g., a delay of 10 will result in 21 values (-10 to 10). A result at -10 will indicate that Signal ONE was shifted -10 frames relative to Signal TWO. A result at 10 will indicate that Signal ONE was shifted +10 frames relative to Signal TWO.
+Setting the /MAX_DELAY parameter to a value that is too small will likely be inadequate to capture the correlation of two signals. Setting the /MAX_DELAY parameter to be the length of the two signals will cover all possible correlations. To further review the shift between the two signals, an example script and power point can be downloaded [[https://www.has-motion.com/download/examples/Cross_Correlation/2015_05_06.zip|here]].
+==== DATA_WRAP ====
+The /DATA_WRAP parameter is a binary flag indicating whether the signal should be considered to loop.
+With no Data Wrap and a MAX_DELAY of half the length of the signal, the first and last frames of the resulting signal will only be comparing half the signal. With Data Wrap, all frames of the resulting signal will be a correlation resulting from comparing all frames of the two signals.
+===== Example: Find the Frame Offset with Highest Correlation =====
+If you want just the frame offset with the highest correlation, you could use the sample script below to calculate the cross-correlation between the two signals, sort these cross-correlation values, and extract the shift responsible for the largest cross-correlation.
+<code>
+Cross_Correlation
+! /SIGNAL_OWNER1=
+/SIGNAL_TYPE1=DERIVED
+/SIGNAL_FOLDER1=COP_TEST
+/SIGNAL_NAME1=LCOP_MAG_ORIGINAL_SIGNAL
+/SIGNAL_COMPONENT1=X
+! /SIGNAL_OWNER2=
+/SIGNAL_TYPE2=ANALOG
+/SIGNAL_FOLDER2=PROCESSED
+/SIGNAL_NAME2=Force.Fz2
+/SIGNAL_COMPONENT2=X
+! /RESULT_OWNER=
+! /RESULT_FOLDER=PROCESSED
+/RESULT_NAME=CrossCorrResult
+/MAX_DELAY=100
+! /DATA_WRAP=FALSE
+;
+Evaluate_Expression
+/EXPRESSION=SORT(DERIVED::PROCESSED::CrossCorrResult, -1, 2)
+! /SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+ /RESULT_TYPES=DERIVED
+ /RESULT_FOLDERS=PROCESSED
+ /RESULT_NAME=CrossCorrResult_Sorted
+! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
+;
+Metric_Explicit
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=CrossCorrResult
+/METRIC_VALUE=DERIVED::PROCESSED::CrossCorrResult_Sorted[1,1]
+;
+</code>