Differences

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

--- visual3d:tutorials:theia:theia3d_merge [2024/06/26 20:08] – removed sgranger
+++ visual3d:tutorials:theia:theia3d_merge [2025/09/24 16:01] (current) – wikisysop
@@ Line 1: / Line 1: @@
+====== Theia3D Merge ======
+** The [[#Manage_Theia3D_Merge|Manage_Theia3D_Merge]] command is no longer recommended since [[visual3d:documentation:pipeline:pipeline_commands:manage_file_merge]] was updated to be used for file types other than just from Theia3D.**
+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,\\
+_THEIA : WALK : TRIAL1 : pose_filt_0.c3d\\
+_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}}