Differences

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

--- visual3d:documentation:pipeline:event_commands:event_copy [2024/06/19 12:49] – sgranger
+++ visual3d:documentation:pipeline:event_commands:event_copy [2025/02/26 17:04] (current) – wikisysop
@@ Line 1: / Line 1: @@
-{{{{{{{{to make a copy of an event label, you can use a pipeline command or you can select the event in the data tree using the right mouse button.
+====== Event Copy ======
-===== interactive selection from the data tree: =====
+==== Overview ====
+The **Event_Copy** command allows users to __create a new event by copying an existing event and applying optional modifications__. Users can specify an offset for the copied event in terms of frames, time or percentage of a defined range. Additionally, users can control the sequence of copied events, exclude certain events from copying, or define specific start and end events for more refined event duplication.
-copyeventmenu.jpg]
+This command is particularly useful for scenarios where new events need to be derived from existing ones while maintaining precise temporal relationships.
-===== from the edit events dialog =====
-editeventsdlg.jpg
+The functionality of this command can also be achieved by right-clicking the event label within the data tree and selecting the "Event Copy" from the context menu. The interactive selection from the data tree is shown below:
-===== pipeline command: =====
-**event_copy**
+{{:visual3d:documentation:pipeline:event_commands:interactive_selection_eventcopy.png?320|}}
-/event_name= the name of the original event
-/new_event_name= the name to be given to the **new event**
-/[[#frame_offset|frame_offset]]= the frame offset from the event_frame
-/[[#time_offset|time_offset]]= the time offset from the event frame
-/[[#percent_offset|percent_offset]]= an offset from the event frame as a percentage of the ranged defined by the event_sequence
-/[[visual3d:documentation:c3d_signal_types:event_label_data_type#event_sequence|event_sequence]]= sequence of events that defines the ranges
-/[[visual3d:documentation:c3d_signal_types:event_label_data_type#exclude_events|exclude_events]]= an inclusive event that excludes the range
-/[[visual3d:documentation:c3d_signal_types:event_label_data_type#event_instance|event_instance]]= the instance of the existing event to copy.
-/[[visual3d:documentation:c3d_signal_types:event_label_data_type#event_instance|range_instance]]= the instance of the existing event to copy.
-/start_at_event= start of range to find the event (legacy-superceded by event_sequence)
-/end_at_event= end of range to find the event (legacy-superceded by event_sequence)
-**;**
-==== copy_event ====
-the name of the legacy command. visual3d should continue to recognize this command.
-===== event copy dialog =====
-as of version 5 this dialog is complicated. interaction with the dialog is described [[visual3d:documentation:pipeline:event_commands:event_management_commands|here]].
+==== Pipeline Command ====
+The command below is the command as seen in the Visual3D application.
-copyeventlabeldlgex1.jpg
+<code>
+/EVENT_NAME=
+/NEW_EVENT_NAME=
+!/EVENT_INSTANCE=0
+!/EVENT_INSTANCE_AS_LIST=FALSE
+!/RANGE_INSTANCE=0
+!/EVENT_SEQUENCE=
+!/START_AT_EVENT=
+!/END_AT_EVENT=
+!/FRAME_OFFSET=
+!/TIME_OFFSET=
+!/PERCENT_OFFSET=
+</code>
-===== frame_offset =====
+==== Command Parameters ====
+The following table shows the command parameters and descriptions:
-frame offset can be a number or an expression.
+|**Parameter**     |**Description**|
+|**/EVENT_NAME=**  |The name of the event to be copied.|
+|**/NEW_EVENT_NAME=**  |The name of the new copied event.|
+|**!/EVENT_INSTANCE=0** |Defines how many event occurrences to consider.|
+|**!/EVENT_INSTANCE_AS_LIST=FALSE**| Indicates whether the event instance is treated as a list.|
+|**!/RANGE_INSTANCE=0**| Specifies which instance of an event range should be used.|
+|**!/EVENT_SEQUENCE=** |Determines whether the copied event follows a specific sequence.|
+|**!/EXCLUDE_EVENTS=** |Specifies events that should not be copied, allowing more refined duplication.|
+|**!/START_AT_EVENT=** |Specifies a starting event to define the range of copying.|
+|**!/END_AT_EVENT=**   |Specifies an ending event to define the range of copying.|
+|**!/FRAME_OFFSET=**   |The number of frames by which to offset the copied event.|
+|**!/TIME_OFFSET=**    |The time offset (in seconds) to apply to the copied event.|
+|**!/PERCENT_OFFSET=** |A percentage offset relative to a defined event range.|
-for example, if the offset is defined by a metric signal in the processed folder labeled shift.
-**/frame_offset**= metric::processed::shift
+==== Dialog ====
-===== time_offset =====
+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 pipeline command. The dialog is shown below.
-time offset can be a number or an expression.
+{{:visual3d:documentation:pipeline:event_commands:eventcopy_dialog.png?400|}}
-for example, if the offset is defined by a metric signal in the processed folder labeled shift.
+  * **Optional- Select Range Instance**:
+When set to 0, copies all instances of the event. When set to n, copy the //n//th instance of the event.
+If n<1, count instances from the last event; e.g. -1 = last instance.
-**/time_offset**= metric::processed::shift
+  * **Optional - Select Event Instance**:
-for example, to create an event 1 second prior to an existing event.
+When set to 0, it means all occurrences of the event will be processed. When **Interpret Event Instance As List** is checked, the event is treated as a list rather than a single value.
-**/time_offset**= -1.0
+==== Examples ====
-===== percent_offset =====
+The following examples will go through the use of the **Event_Copy** command in the Visual3D application.
-the percent offset can be a number or an expression.
+=== Example 1: Event_At_Midstance ===
-the percent is the percentage of the range within the event_sequence.
+The stance phase of the gait cycle is the period when the foot is in contact with the ground, it is defined by the labels RON and ROFF. The following command will create an event mid way between RON and ROFF.
-for example, if the offset is defined by a metric signal in the processed folder labeled percent.
+<code>
+Event_Copy
+/EVENT_NAME=RON
+/NEW_EVENT_NAME=MID_STANCE
+!/FRAME_OFFSET=
+!/TIME_OFFSET=
+/PERCENT_OFFSET=50
+!/EVENT_INSTANCE=0
+!/RANGE_INSTANCE=0
+/EVENT_SEQUENCE=RON+ROFF
+!/EXCLUDE_EVENTS=
+!/START_AT_EVENT=
+!/END_AT_EVENT=
+;
+</code>
-**/percent_offset**= metric::processed::percent
+The dialog corresponding to the example command is shown below:
-===== event instance =====
-event_instance=0 -> copy all instances of the event
+{{:CopyEventLabelDlgEx1.jpg?350}}
-event_instance=n -> copy the nth instance of the event
+This command will use all instances of a range defined by the **Event_Sequence** and **Exclude_Event**, and will use every occurrence of the **Event_Name** within this sequence.
-if n<1 count instances from the last event; e.g. -1 = last instance
+=== Example 2: Copying the last event in the sequence ===
-===== range instance =====
+The event sequence used in the **Event_Copy** command includes the first event, but not the last event. This idiosyncratic behavior was introduced to handle sequences that had the same event label name at each end of the sequence.
-range_instance=0 -> use all instances of the range
+In order to copy the last event, you need to select the first event and an offset of 100%. For example, given a sequence of events A-B-C and you want to copy Event C and name it C2.
-range_instance=n -> use the nth instance of the range
+<code>
+Event_Copy
+/EVENT_NAME=A
+/NEW_EVENT_NAME=C2
+!/FRAME_OFFSET=
+!/TIME_OFFSET=
+/PERCENT_OFFSET=100
+!/EVENT_INSTANCE=0
+!/RANGE_INSTANCE=0
+/EVENT_SEQUENCE=A+B+C
+!/EXCLUDE_EVENTS=
+!/START_AT_EVENT=
+!/END_AT_EVENT=
+;
+</code>
-if n<1 count instances from the last range; e.g. -1 = last range
-===== example_event_at_midstance =====
+=== Example 3: Create an Event based on a time threshold between 2 Events ===
+In this example, an event named BAD is created if the time between two events (RHS-> RHS) exceeds a threshold. The following is the breakdown of the command:
+  - Define a Stride: the time between two consecutive RHS.
+  - Measure Stride Time: Calculates the duration of each STRIDE.
+  - Identify Long Strides: Checks if any STRIDE duration is longer than 4 seconds, if this is the case, it is flagged.
+  - Mark as "BAD": For each stride that's longer than 4 seconds, it creates a new event called "BAD" at the time of the second RHS.
-given that stance phase is defined by the labels ron and roff
+<code>
+! Define an Event Sequence
+Event_Define_Event_Sequence
+/EVENT_SEQUENCE_NAME=STRIDE
+/EVENT_SEQUENCE=RHS+RHS
+!/EXCLUDE_EVENTS=
+!/INSIDE_OF_SEQUENCE=
+!/OFFSET_FROM_START=
+!/OFFSET_FROM_END=
+!/OFFSET_BY=PERCENT
+/EVENT_SEQUENCE_INSTANCE=0
+;
-the following command will create an event mid way between ron and roff.
+! Compute the times of the Event_Sequence
+Metric_Time_Between_Events
+/RESULT_METRIC_NAME=STRIDE_TIME
+!/RESULT_METRIC_FOLDER=PROCESSED
+/EVENT_SEQUENCE=STRIDE
+/EXCLUDE_EVENTS=
+/GENERATE_MEAN_AND_STDDEV=FALSE
+!/APPEND_TO_EXISTING_VALUES=FALSE
+;
-**event_copy**
+! Create a binary signal from the stride time and threshold (4 in this case)
-/event_name=ron
+Evaluate_Expression
-/new_event_name=mid_stance
+/EXPRESSION=(METRIC::PROCESSED::STRIDE_TIME>4)
-! /frame_offset=
+!/SIGNAL_TYPES=
-! /time_offset=
+!/SIGNAL_FOLDER=ORIGINAL
-/percent_offset=50
+!/SIGNAL_NAMES=
-! /event_instance=0
+/RESULT_TYPES=METRIC
-! /range_instance=0
+!/RESULT_FOLDERS=PROCESSED
-/event_sequence=ron+roff
+/RESULT_NAME=STRIDE_TIME_BINARY
-! /exclude_events=
+!/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
-! /start_at_event=
+;
-! /end_at_event=
-**;**
-copyeventlabeldlgex1.jpg
-this command will use all instances of a range defined by the event_sequence and exclude event, and will use every occurrence of the event_name within this sequence.
+! Create a pipeline parameter from the binary signal
+Set_Pipeline_Parameter_To_Data_Value
+/SIGNAL_TYPES=METRIC
+/SIGNAL_FOLDER=PROCESSED
+/SIGNAL_NAMES=STRIDE_TIME_BINARY
+!/SIGNAL_COMPONENTS=ALL_COMPONENTS
+/PARAMETER_NAME=INSTANCE
+;
-===== example - copying the last event in the sequence =====
+! Create indices for a for each loop
+**Get_Pipeline_Parameter_Count**
+/PARAMETER_NAME=NUMCOUNT
+/PARAMETER_VALUE=::INSTANCE
+;
-the event sequence used in the event_copy command includes the first event, but not the last event. this idiosyncratic behavior was introduced to handle sequences that had the same event label name at each end of the sequence.
+Set_Pipeline_Parameter_From_For_Loop
+/PARAMETER_NAME=COUNT
+/PARAMETER_INDEX_START=1
+/PARAMETER_INDEX_END=::NUMCOUNT
+/PARAMETER_INDEX_STEP=1
+!/PARAMETER_INDEX_TYPE=INTEGER
+;
-in order to copy the last event, you need to select the first event and an offset of 100%
+For_Each
+/ITERATION_PARAMETER_NAME=INDEX
+/ITEMS=::COUNT
+;
-for example, given a sequence of events a-b-c and you want to copy event c and name it c2.
+! If the binary signal is 1 execute event copy
+Expression_Loop
+/ITERATION_PARAMETER_NAME=TEST
+/EXPRESSION=METRIC::PROCESSED::STRIDE_TIME_BINARY[&::INDEX&]
+/AS_INTEGER=true
+;
-event_copy
+Event_Copy
-/event_name=a
+/EVENT_NAME=RHS
-/new_event_name=c2
+/NEW_EVENT_NAME=BAD
-!/frame_offset=
+!/EVENT_INSTANCE=0
-! /time_offset=
+/RANGE_INSTANCE=::INDEX
-/percent_offset=100
+/EVENT_SEQUENCE=STRIDE_TIME
-! /event_instance=0
+!/EXCLUDE_EVENTS=
-! /range_instance=0
+!/START_AT_EVENT=
-/event_sequence=a+b+c
+!/END_AT_EVENT=
-! /exclude_events=
+/FRAME_OFFSET=10
-! /start_at_event=
+!/TIME_OFFSET=
-! /end_at_event=
+!/PERCENT_OFFSET=
-**;**
+;
-===== example - create an event based on a time threshold between 2 events =====
+Expression_Loop_End
+/ITERATION_PARAMETER_NAME=TEST
+;
+End_For_Each
+/ITERATION_PARAMETER_NAME=INDEX
+;
+</code>
+==== Notes ====
+  * The /Percent_Offset parameter is only effective when /Start_At_Event and /End_At_Event are specified.
+  * Offset values (Frame_Offset, Time_Offset, Percent_Offset) should be used cautiously to ensure event placement aligns with analysis needs.
-for example, create an event (bad) if the time between two events (rhs to rhs) exceeds a threshold.
-! define an event sequence
-**event_define_event_sequence**
-/event_sequence_name=stride
-/event_sequence=rhs+rhs
-! /exclude_events=
-! /inside_of_sequence=
-! /offset_from_start=
-! /offset_from_end=
-! /offset_by=percent
-/event_sequence_instance=0
-**;**
-! compute the times of the event_sequence
-**metric_time_between_events**
-/result_metric_name=stride_time
-! /result_metric_folder=processed
-/event_sequence=stride
-/exclude_events=
-/generate_mean_and_stddev=false
-! /append_to_existing_values=false
-**;**
-! create a binary signal from the stride time and threshold (4 in this case)
-**evaluate_expression**
-/expression=(metric::processed::stride_time>4)
-! /signal_types=
-! /signal_folder=original
-! /signal_names=
-/result_types=metric
-! /result_folders=processed
-/result_name=stride_time_binary
-! /apply_as_suffix_to_signal_name=false
-**;**
-! create a pipeline parameter from the binary signal
-**set_pipeline_parameter_to_data_value**
-/signal_types=metric
-/signal_folder=processed
-/signal_names=stride_time_binary
-! /signal_components=all_components
-/parameter_name=instance
-**;**
-! create indices for a for each loop
-**get_pipeline_parameter_count**
-/parameter_name=numcount
-/parameter_value=::instance
-**;**
-**set_pipeline_parameter_from_for_loop**
-/parameter_name=count
-/parameter_index_start=1
-/parameter_index_end=::numcount
-/parameter_index_step=1
-! /parameter_index_type=integer
-**;**
-**for_each**
-/iteration_parameter_name=index
-/items=::count
-**;**
-! if the binary signal is 1 execute event copy
-**expression_loop**
-/iteration_parameter_name=test
-/expression=metric::processed::stride_time_binary[&::index&]
-/as_integer=true
-**;**
-**event_copy**
-/event_name=rhs
-/new_event_name=bad
-! /event_instance=0
-/range_instance=::index
-/event_sequence=stride_time
-! /exclude_events=
-! /start_at_event=
-! /end_at_event=
-/frame_offset=10
-! /time_offset=
-! /percent_offset=
-**;**
-**expression_loop_end**
-/iteration_parameter_name=test
-**;**
-**end_for_each**
-/iteration_parameter_name=index
-**;**
-}}}}}}}}