Run Theia processing on video files

Vicon Nexus 2.12 and later enables you to process Nexus video data from within Theia, without having to launch Theia and manually process the data.

You can either use the Theia Batch Interface to run Theia processing on all the video trials in a specified folder or use the supplied pipeline operation to run Theia processing on one or more selected video trials.

After you have run Theia processing on your trial data, you can use an additional supplied pipeline operation to combine it with your Nexus trial to add the rotation data from Theia3D to your Nexus trial. To calculate the joint angles, you can continue to use Nexus with Vicon ProCalc schemes or use ProCalc independently of Nexus. Alternatively, you can use pipeline operations that are supplied with Theia3D to generate the kinematics and kinetics (note that, to calculate joint kinetics, a force plate is required), and use Visual3D to merge the rotation data and perform the data analysis.

Capture and transcode video trials in Nexus

Before you begin using the Theia functionality within Nexus, capture and transcode the required trials.

1. In Nexus, capture the optical and video trials in the usual way, ensuring your system includes at least two optical cameras, as well as video cameras.
2. Before you compress all the video trials, ensure you are using a recommended Theia video processor with the appropriate settings.
3. Compress and transfer all the required video trials, ensuring that you select the correct video encoder (see Transfer and transcode digital video files).
   For Nexus 2.13 and later, we recommend using the h.264 Best Quality/Largest File option.

Run Theia processing on video trials

Nexus provides two options for running Theia processing on your video trials. The Theia Batch Interface enables you to process all the video trials in a specified session folder. If you want to process only one trial or a few trials, or add Theia processing to an existing pipeline, you may prefer to use the supplied Theia pipeline operation instead.

Run Theia processing on all trials in a specified folder

From the Nexus Communications pane, you can select the Theia tab to access the Theia Batch Interface. From here you can select the required video files and process them. The files are processed through Theia3D, resulting in the output of C3D file(s) that contain rotation data for each subject.

To run Theia processing on all trials in a specified folder:

1. Ensure Theia3D is NOT already running on the machine on which you want to process the files

2. In the Communications pane, click the Theia tab, enter the paths in the fields shaded in pink, and set any other properties as required, for example, Theia preferences.
   
   

   • Folder: Enter or browse to the full path of the session folder containing the trials that you want to process in Theia. Theia will attempt to process all trials in this folder.
     Note that when you exit and relaunch Nexus, the path is remembered.

   • Theia executable: Enter or browse to the full path for the Theia3D.exe file, for example, C:\Program Files\Theia\Theia3D.
     Note that when you exit and relaunch Nexus, the path is remembered.
   • Theia preferences: If you want to use the preferences that you use in Theia, enter the full path to the required Theia prefererences file. This must be exported from Theia and saved as a PXT file on the local machine.
   • Create folder hierarchy: If you want a folder hierarchy to be created in which to store the files, and the necessary video files to be copied into it, ensure that this check box is selected. Unless you have already created the folder hierarchy (eg, if you are re-running the process), you will normally leave this option selected. The folder structure that is created consists of a folder named Theia that is a child of the session folder that contains the trials, with subfolders named Trialname_c3d, which contain the C3D files (filtered and unfiltered) that are output by Theia processing.

     

   • Run Theia processing: When selected, the video files are formatted in the correct Theia3D-readable format and then Theia3D is launched and processes all the detected video files in the Folder location. If you only want to format the files and do not want to launch Theia, clear this option.

3. When you have entered the required information, click Process trials in folder.
   Nexus identifies the number of trials that are found in the folder and starts the process on the first trial, which launches Theia.
   The right side of the Theia tab displays the progress of the processing and in the Theia window, a percentage progress bar is also displayed.
   
   
   
   
   
   

   If Theia closes, Nexus relaunches Theia and retries once only to reopen the trial that it attempted to process. If the trial won't open, it moves on to the next trial.
   If you want to stop Theia launching, click Cancel processing.

   When processing is finished, the right side of the Theia tab displays the text 'Batch Processing: Finished.' and the Theia data is placed in a subfolder in the specified file path, if you selected Create folder hierarchy. The Theia data includes:

   • The Theia video format and calibration file

   • Theia-generated C3D files. For each video file, Theia generates two C3D files: filtered and non-filtered. (If necessary, you can change the filtering in Theia3D.)

   Note that Theia3D remains open after processing is finished.

If required, you can view the output rotations in the Subject tree, the 3D Perspective view, and in the Graph view.

You can now merge this rotation data, which will be used to calculate the joint information, back into the original Nexus trial (see Combine processed Theia data with a Nexus trial).

Run Theia processing on one or more selected video trials

You can use the supplied pipeline operation to run Theia processing on a single video trial, or multiple trials marked in Data Management, resulting in the output of C3D file(s) that contain rotation data for each subject.

To process one or more selected video trials:

1. Ensure Theia3D is NOT already running on the machine on which you want to process the trial.
   
2. Load the trial(s) on which you want to run Theia processing and, if necessary, mark them in the usual way, in Data Management.
3. In the Pipeline Tools, expand the Data Processing pipeline operations and then double-click Theia to add it to the current pipeline.
4. In the Properties pane, specify the required settings:
   • Theia executable: Enter or browse to the full path for the Theia3D.exe file, for example, C:\Program Files\Theia\Theia3D.
     Note that when you exit and relaunch Nexus, the path is remembered.
   • Theia preferences: If you want to use the preferences that you use in Theia, enter the full path to the required Theia prefererences file. This must be exported from Theia and saved as a PXT file on the local machine.
   • Create folder hierarchy: If you want a folder hierarchy that is used by Theia to be created, and the necessary video files to be copied into it, ensure that this check box is selected. Unless you have already created the folder hierarchy (eg, if you are re-running the process), you will normally leave this option selected. The folder structure that is created consists of a folder named Theia that is a child of the session folder that contains the trials, with subfolders named Trialname_c3d, which contain the C3D files (filtered and unfiltered) that are output by Theia processing.

     

   • Run Theia processing: When selected, the video files are formatted in the correct Theia3D-readable format and then Theia3D is launched and processes all the detected specified video files.
     If you only want to format the files and do not want to launch Theia, clear this option.
5. Run the pipeline operation on the video trial data.
   Theia launches and the trial is processed.
   If Theia closes, Nexus relaunches Theia and retries once only to reopen the trial that it attempted to process. If the trial won't open, it moves on to the next trial.
   If you want to stop Theia launching, click Cancel processing.

   When processing is finished, the Theia data is placed in a subfolder in the specified file path, if you selected Create folder hierarchy. The Theia data includes:

   • The Theia video format and calibration file

   • Theia generated C3D files. For each video file, Theia generates two C3D files: filtered and non-filtered. (If necessary, you can change the filtering in Theia3D.)

   Note that Theia3D remains open when processing is finished.

If required, you can view the output rotations in the Subject tree, the 3D Perspective view and in the Graph view.

You can now merge this rotation data, which will be used to calculate the joint information, back into the original Nexus trial (see Combine processed Theia data with a Nexus trial).

Combine processed Theia data with a Nexus trial

When you have run Theia processing on your trial data, you can run a pipeline operation that merges the rotation data with your Nexus trial.

To combine processed Theia data with a Nexus trial:

1. Run Theia processing on your trial data (see Run Theia processing on one or more selected video trials or Run Theia processing on all trials in a specified folder) and ensure that you have also run any processing needed to give you the required model outputs on the optical data for your trial.
2. Load the trial that you want to combine with your Theia data in the usual way, in Data Management.

   

3. In the Pipeline Tools, expand File Import pipeline operations, then double-click Add Theia Data to add it to the current pipeline.
4. In the Properties pane, specify the required settings:

   • Theia C3D folder: The Standard Folder location is the default location for Theia data, which is within the folder structure created by the previous Theia processing. The folder structure consists of a folder named Theia, which is a child of the session folder that contains the trials, and within this folder, the subfolders, whose names are 'TrialName _c3d'.
     
     
     
     If you didn't save the processed data to the standard location for Theia processing, change the Theia C3D Folder to the relevant location by clicking to the right of the Standard Folder field and then clearing the Macro box. You can then enter or browse to the folder location.

     Tip
     Ensure the names of the files on which you want to run the Add Theia Data operation conform to the naming convention so that they begin with the trial name, followed by _subjectNumber.c3d or *_filt_subjectNumber.c3d, for example, walking_100_50_01_0.c3d or walking_100_50_01_filt_0.c3d.

   • Filtered: Select this option to run the operation on the filtered data. If cleared, the operation runs on the raw, unfiltered data.
5. Run the pipeline operation.
   On the Subjects Resources tab, in the Model Outputs for the relevant subject, the rotations are displayed and can also be visualized in the 3D Perspective view.At the top of the Subjects tree, the subject name has an asterisk ( * ) appended to it, to indicate that the data has changed and can now be saved.

   

6. Save the C3D to retain the merged rotations in your Nexus trial.

After you have finished merging the rotations into your Nexus trial data, you can use Nexus to calculate the joint information (see Calculate joint angles).

Calculate joint angles and kinetics

The Run Theia ProCalc Scheme pipeline operation enables you to generate joint information (ProCalc angles) and kinetics from combined Nexus-Theia trial data.

To calculate the joint angles:

1. Ensure Vicon ProCalc 1.6 is installed.
2. Ensure you have merged the Theia rotation data with your Nexus trial by running the Add Theia Data pipeline operation (see Combine processed Theia data with a Nexus trial).
3. Ensure the trial for which you want to generate joint angles is loaded in the usual way, in Data Management.
4. In the Pipeline Tools, expand Data Processing pipeline operations, then double-click Run Theia ProCalc Scheme to add it to the current pipeline.
5. With Run Theia ProCalc Scheme selected, in the Properties pane, specify the required settings from the Schemes section:
   In the Variable Scheme field, select from:
   • CalculateKinematicsFromTheia: (Default option) Automatically calculates joint angles from the rotations.
     
   • CalculateKineticsFromTheia: Automatically calculates kinetics. Note that a force plate is required to calculate joint kinetics.
   • CalculatePluginGaitBonesFromTheia: Automatically calculates Plug-in Gait bones, This is useful if you want to display meshes in Vicon Polygon. (If you also need to calculate joint angles, first run the CalculateKinematicsFromTheia scheme.)

     

     Note that the default location for these schemes is C:\Program Files\Vicon\ProCalc\Resources. If you make a change in ProCalc that moves or deletes these schemes, they will not be available from this menu.
6. Ensure the default option (CalculateKinematicsFromTheia) is selected and run the pipeline operation.
   The ProCalc joint angles are displayed in the Model Outputs for the relevant subject. Their names end in the suffix _Theia, for easy identification.

   

7. To compare Theia-generated outputs with the Nexus outputs, select equivalent outputs (for example, LHipAngles and LeftHipAngles_Theia), and display them in a Graph view.