====== Theia3D Merge ======

This tutorial demonstrates the process of merging Theia3D's output [[Visual3D:Documentation:C3D_Signal_Types:C3D_Format|C3D]] files and other C3D files. The typical scenario is to merge Theia3D's motion capture output and analog signals such as force platform recordings.

There are two methods for achieving this merge:

  - Users can [[#Merging_C3D_files_interactively|interactively]] merge C3D files using the Visual3D interface.
  - Users can use the [[#Manage_Theia3D_Merge|Manage_Theia3D_Merge]] pipeline command.

==== Demo Files ====

Download the [[https://drive.google.com/file/d/1KwwDEz4jKxVoACnUY1MpGajpZMsHozvH/view?usp=sharing|zip file]] containing folder paths and files for this tutorial.

==== Merging C3D files interactively ====

=== Open Theia3D C3D File ===

If you use TMBATCH, select the default folder paths, which should be in the form. \\
STUDY : GROUP : SESSION : ACTION : TRIAL : pose_filt_0.c3d

The relative path for this example data is:
...\Visual3D_Tutorial\001_THEIA\WALK\001\pose_filt_0.c3d

Open this file:

Visual3D recognizes this as a Theia3D output file and will automatically create a model and assign the motion file.
The workspace status TAB will display the model and movement trial.
Note that the standing trial was created virtually based on the c3d parameters in the movement trial
The name of the static file is the name of the first movement file loaded with _Static applied to the name.

{{:Theia3D_Tutorial_1.jpg?500}}

Switch to Model Builder mode.

The segments and landmarks have been created automatically.

{{:Theia3D_Tutorial_2.jpg?500}}

Edit the Right Thigh segment

{{:Theia3D_Tutorial_3.jpg?500}}

Note that Theia3D stores [[Visual3D:Documentation:C3D_Signal_Types:ROTATION_DATA_TYPE|ROTATION signals]], not TARGETS.
If a ROTATION signal is selected for a location, only the position information is used from the signal
The "Ignore Calibaration" button is selected as Theia3D exports the 6 DOF pose of the segment.
Unless there is a reason to modify the coordinate system, the default is to assign the ROTATION signal to the pose of the segment.
Switch to the Signals and Events TAB and animate the motion file.

Note the ROTATION folder is open in this image displaying the ROTATION signals exported by Theia3D.

{{:Theia3D_Tutorial_4.jpg?500}}

=== Import Analog signals and Force Platform parameters from QTM C3D File ===

The QTM files should be stored in the following

STUDY : GROUP : SESSION_QTM : ACTION : Trial#.c3d

The QTM filenames should be similar to the Theia3D TRIAL path name. For example,

The relative path for this example data is:

\Visual3D_Tutorial\001_QTM\WALK\MoCapNwalk_001.c3d\\
Use the following command to import analog signals and force platform parameters from the QTM generated c3d file.

[[Visual3D:Documentation:Pipeline:File_Commands:Import_Signals_From_C3D_File|Import_Signals_From_C3D_File]]
For this example, we only need to specify a few of the possible parameters for this command and leave the remaining parameters to their default values

<code>
Import_Signals_From_C3D_File
/ANALOG_RATIO=5
/IMPORT_FORCE_PLATFORM_PARAMETERS=TRUE
;
</code>

After executing this command the analog signals and force platform parameters have been added to the Theia3D file.

{{:Theia3D_Tutorial_5.jpg?500}}

=== Exporting the merged C3D file (Optional) ===

The resulting C3D file is still named pose_filt_0.c3d, which is a bit of a nuisance in Visual3D as the short filename for all files would be the same.

From the **File** menu, open the **Export** subfolder and select **Export C3D File.** The //Export C3D File// dialog box will open.\\
{{:Tutorial2_8.jpg?500}}\\

From the **File to Export** drop down Select //pose_filt_0.c3d.//
Click **Browse.**
From the //Save As// dialog box browse to the location where you store your files and enter //New_Filename.c3d// in the **File name** field.\\
**Note:**
Click **Save.**
From the //Export C3D File// dialog box Click **Export.**\\
**Note:** Leave all other options at the default values. Many of these options are available to handle irregularities in the c3d file format, and should only be used when necessary.

Given the merged c3d file, you can save the file as a cmz file
or you can [[Visual3D:Documentation:Pipeline:File_Commands:Export_C3DFile|export the c3d file]]

==== Manage_Theia3D_Merge ====

Visual3D has a pipeline command dedicated to merging theia3D output files with other synchronized files containing marker and analog signals and force platform parameters
In order to automate the merge, it was necessary to make some assumptions about filenames and folder paths similar to the [[#Merging_C3D_files_interactively|previous example]].
If you use Theia's TMBATCH, select the default folder paths. This should be in the form.

STUDY : GROUP : SESSION_THEIA : ACTION : TRIAL : pose_filt_0.c3d

The Other files should be stored in the following

STUDY : GROUP : SESSION_OTHER : ACTION : Trial#.c3d

The OTHER filenames should be similar to the Theia3D TRIAL path name. For this tutorial the file paths begin at the session level,\\
001_THEIA : WALK : TRIAL1 : pose_filt_0.c3d\\
001_QTM : WALK : Trial1.c3d
​
While this example may include only one Theia3D file and one Other file, the command will act on all SESSIONS, ACTIONS and TRIALS in the filepath.
A cmz file is created for each session and stored in the corresponding Theia3D session
=== Import Analog Files ===

Having all files named pose_filt_0.c3d is a bit of a nuisance for Visual3D and the files are renamed by the command.
The new name is a concatenation of the name and TRIAL name. For this example\\
WALK_TRIAL1.c3d

Having the sessions in parallel was implemented because Theia3D keeps evolving and there may be multiple versions of the Theia3D Session for the same original videos. 

For example: SESSION_V2 and SESSION_V3

Getting the Theia3D files into this folder structure is straightforward as it is the default from Theia.

Note that the command requires the specification of the full root folder.
For this documentation I have represented all but the last folder in the hierarchy

{{:Theia3D_Tutorial_61.jpg?500}}

<code>
Manage_Theia3D_Merge
/ROOT_FOLDER=\\Mac\Home\Desktop\TestData\Merge\Wiki Example\Visual3D_Theia_Tutorial1\
! /HMX_INDEX_MASK=
! /USE_HMX_INDEX=FALSE
! /ACTION=
! /TAGS=ACTION
/IMPORT_ANALOG_FILES=TRUE
! /MERGE_THEIA3D_FILES=FALSE
! /MERGE_THEIA3D_AND_OTHER_FILES=FALSE
! /MERGE_EVENT_LABELS=FALSE
/THEIA3D_SESSION_FOLDER=001_THEIA
/THEIA3D_FILE_MASK=*pose_filt_0.c3d
! /THEIA3D_FILE_MASK_FOR_MODEL=
! /THEIA3D_PREFIX=
! /THEIA3D_SUBJECT_TAG=
/THEIA3D_COLOR=Black
/OTHER3D_SESSION_FOLDER=001_QTM
/OTHER3D_FILE_MASK=*.c3d
! /OTHER3D_MODEL_MASK=
! /OTHER3D_MODEL_TEMPLATE_MASK=
! /OTHER3D_PREFIX=
! /OTHER3D_SUBJECT_TAG=
/OTHER3D_COLOR=Black
/NUMBER_OF_SESSION_FILES_ALLOWED=3
! /SAVE_DEFAULT_CMZ_FILES=TRUE
! /DEFAULT_CMZ_NAME=<SESSION>
! /OPEN_CMZ_LIBRARY=FALSE
/INPUT_DATA_FOLDER_PRIMARY=TRIAL
/INPUT_DATA_FOLDER_SECONDARY=ACTION
/INPUT_STATIC_DATA_FOLDER=SESSION
! /KINETIC_THORAX=RTA
! /ANALOG_FILTER_CUTOFF=12
! /TARGET_FILTER_CUTOFF=12
/FP_AUTO_BASELINE=Do_Not_Compute
! /VISUAL3D_PIPELINE_POST_MERGE=
! /VISUAL3D_PIPELINE_PREMERGE=
;
</code>

The Visual3D workspace is as follows: Note the name of the files WALK_001.c3d and WALK_001_STATIC.c3c

{{:Theia3D_Tutorial_7.jpg?500}}

The data and animation should look the same as the previous example

{{:Theia3D_Tutorial_5.jpg?500}}

=== Merge Targets and Analog Signals ===

The following command options merge Theia3D files with QTM files that have markers, a standing trial, and a model template.
To distinguish the marker and markerless data, subject prefixes were added.
The result will have two models associated with the movement trials.

{{:Theia3D_Tutorial_62.jpg?500}}

<code>
Manage_Theia3D_Merge
/ROOT_FOLDER=\\Mac\Home\Desktop\TestData\Merge\Wiki Example\Visual3D_Theia_Tutorial1\
! /HMX_INDEX_MASK=
! /USE_HMX_INDEX=FALSE
! /ACTION=
! /TAGS=ACTION
! /IMPORT_ANALOG_FILES=FALSE
! /MERGE_THEIA3D_FILES=FALSE
/MERGE_THEIA3D_AND_OTHER_FILES=TRUE
! /MERGE_EVENT_LABELS=FALSE
/THEIA3D_SESSION_FOLDER=001_THEIA
/THEIA3D_FILE_MASK=*pose_filt_0.c3d
! /THEIA3D_FILE_MASK_FOR_MODEL=
/THEIA3D_PREFIX=ML:
/THEIA3D_SUBJECT_TAG=ML
/THEIA3D_COLOR=Black
/OTHER3D_SESSION_FOLDER=001_QTM
/OTHER3D_FILE_MASK=*.c3d
/OTHER3D_MODEL_MASK=*static*.c3d
/OTHER3D_MODEL_TEMPLATE_MASK=*.mdh
/OTHER3D_PREFIX=M:
/OTHER3D_SUBJECT_TAG=M
/OTHER3D_COLOR=Black
/NUMBER_OF_SESSION_FILES_ALLOWED=3
! /SAVE_DEFAULT_CMZ_FILES=TRUE
! /DEFAULT_CMZ_NAME=<SESSION>
! /OPEN_CMZ_LIBRARY=FALSE
/INPUT_DATA_FOLDER_PRIMARY=TRIAL
/INPUT_DATA_FOLDER_SECONDARY=ACTION
/INPUT_STATIC_DATA_FOLDER=SESSION
! /KINETIC_THORAX=RTA
! /ANALOG_FILTER_CUTOFF=12
! /TARGET_FILTER_CUTOFF=12
/FP_AUTO_BASELINE=Do_Not_Compute
! /VISUAL3D_PIPELINE_POST_MERGE=
! /VISUAL3D_PIPELINE_PREMERGE=
;
</code>

After executing this command the workspace will have one motion file associated with two model files

{{:Theia3D_Tutorial_9.jpg?500}}

One model file is for the marker data
Note the prefix M: on the marker names

{{:Theia3D_Tutorial_10.jpg?500}}

One model file is for the Theia3D data
Note the prefix ML: on the rotation names

{{:Theia3D_Tutorial_11.jpg?500}}

The resulting animation will display both models.

{{:Theia3D_Tutorial_12.jpg?500}}