====== Event Explicit ======

==== Overview ====
The **Event_Explicit** command is used to manually define and place a custom event label in Visual3D by specifying the exact time at which the event occurs. Unlike automatically detected events (e.g., heel strike detected via force plata date), this command allows users to explicitly set an event based on external input or predefined criteria such as specifying a frame or time.

This command is useful when importing event markers from external sources, synchronizing motion capture events with force data, or manually inserting key moments in the movement cycle.

==== Pipeline Command ====
The command below is as seen in the Visual3D application, with the option to name and specify frame OR time.

<code>
Event_Explicit
/EVENT_NAME=
! /FRAME=
! /TIME=
;
</code>

==== Command Parameters ====
The following table shows the command parameters and descriptions:

|**Parameter**|**Description**|
|**/EVENT_NAME=**|Specifies the name of the event being created.|
|**! /FRAME=**| Defines the frame at which the event occurs.|
|**! /TIME=**|Defines the exact time (in seconds) at which the event occurs.|

==== 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 pipeline command. The dialog is shown below.

{{:visual3d:documentation:pipeline:event_commands:event_explicit_dialog_box.png?400|}}

In this dialog, the user is given the options to name the event, and specify either a frame or time to create the event label.
==== Examples ====
The following examples will go through the use of the **Event_Explicit** command in the Visual3D application. 

=== Example 1: Simple Use Case ===
In the first example, let's say the user knows the specific time when the subject's left foot comes in contact with the ground in a walking trial, at the time of 1.25 seconds.

Here is how the command would be defined in the pipeline:

<code>
Event_Explicit
/EVENT_NAME= LEFT_FOOT_CONTACT
! /FRAME=
/TIME= 1.25
</code>

In the dataset used for this example, 1.25 seconds represents the exact point when contact is made, this is can be seen clearly by the graph produced with the highlighted event label.

{{:visual3d:documentation:pipeline:event_commands:graph_example1.png?400|}}

=== Example 2: Create events using the START and END of trial ===
The following command will create an event label named 'START' at the first frame of the trial.

<code>
Event_Explicit
/Event_Name= START
/Frame= 1
/Time=
;
</code>

The next **Event_Explicit** command will create an event labelled 'END' placed on the last frame of data, in some cases, the user may not know how many frames there are, which is why [[Visual3D:Documentation:Definitions:EOF_(End_of_File)|EOF]] is used to recognize the last frame in the file.

<code>
Event_Explicit
/Event_Name= END
/Frame= EOF
/Time=
;
</code>

When creating an event a certain number of frames offset from the [[Visual3D:Documentation:Definitions:EOF_(End_of_File)|EOF]], a minus (-) sign can be used to specify how many frames before the End of File that the desired event takes place.

<code>
Event_Explicit
/Event_Name= EOF_MINUS_10
/Frame= EOF - 10
/Time=
;
</code>

This graph shows that the event labels were placed in the desired locations.

{{:visual3d:documentation:pipeline:event_commands:graph_example2.png?500|}}

=== Example 3: Create an event at multiple frames ===

This functionality was introduced into the command in **Version 6**. It will create three instances of the event label 'TEST' at frames 1, 5 and 10:

<code>
Event_Explicit
/Event_Name= TEST
/Frame= LIST(1,5,10)
/Time=
;
</code>


=== Example 4: Create an event at one second intervals ===
This final example represents the **Event_Explicit** command used within a loop in order to create an event at one second intervals throughout the file.

<code>
Set_Pipeline_Parameter_From_For_Loop
/PARAMETER_NAME=COUNT
/PARAMETER_INDEX_START=1
/PARAMETER_INDEX_END=METRIC::TIME::TOTAL
/PARAMETER_INDEX_STEP=1
! /PARAMETER_INDEX_TYPE=INTEGER
;

For_Each
/ITERATION_PARAMETER_NAME=INDEX
! /ITERATION_PARAMETER_COUNT_NAME=
/ITEMS=::COUNT
;

Event_Explicit
/EVENT_NAME=TEST
! /FRAME=
/TIME=::INDEX
;

End_For_Each
/ITERATION_PARAMETER_NAME=INDEX
;
</code>