This tutorial demonstrates the process of merging Theia3D's output 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:

1. Users can interactively merge C3D files using the Visual3D interface.
2. Users can use the Manage_Theia3D_Merge pipeline command.

Download the zip file containing folder paths and files for this tutorial.

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.

Switch to Model Builder mode.

The segments and landmarks have been created automatically.

Edit the Right Thigh segment

Note that Theia3D stores 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.

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.

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

Import_Signals_From_C3D_File
/ANALOG_RATIO=5
/IMPORT_FORCE_PLATFORM_PARAMETERS=TRUE
;

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

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.

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 export the c3d file

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 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

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

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=
;

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

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

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.

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=
;

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

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

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

The resulting animation will display both models.