--- title: "Run Theia processing on video files" canonical: "https://help.vicon.com/space/Nexus215/11375075/Run%20Theia%20processing%20on%20video%20files" format: markdown --- 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. > Macro (scroll-only) > > > Macro (toc) > ⚠️ **Note** > ⚠️ Before you begin, in addition to upgrading to Nexus 2.12 or later, ensure you have installed Vicon ProCalc 1.5 or later and are using Theia3D 2020 6 1106 or later. > Macro (scroll-pagebreak) ## 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](https://vicon-help.atlassian.net/wiki/spaces/Nexus215/pages/11373374)). 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. > Macro (scroll-only) > > > Macro (toc) > Macro (scroll-pagebreak) ### > Macro (anchor) 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. > ✅ ** Tip** > ✅ Unlike the **[Theia](#RunTheiaprocessingonvideofiles-RunTheiaSelectedTrials)**[ pipeline operation](#RunTheiaprocessingonvideofiles-RunTheiaSelectedTrials), which loads each trial into Nexus, when you use the Theia Batch Interface, you can process your optical data at the same time in Nexus while Theia runs and processes the video data in the background. **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**. > Macro (inline-media-image) - **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. > Macro (inline-media-image) > Macro (inline-media-image) 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. ![image](media://2b9b330f-30e5-494a-917c-f7a441e576c2) 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](#CombineTheiaNexus)). > Macro (scroll-pagebreak) ### > Macro (anchor) 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. ![image](media://93df1365-feaa-4d5a-810b-8da34ce5956d) **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. ![image](media://2b9b330f-30e5-494a-917c-f7a441e576c2) 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](#CombineTheiaNexus)). > Macro (scroll-pagebreak) ## > Macro (anchor) 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. > ⚠️ **Note** > ⚠️ If your trials contain multiple subjects, the workflow is different from that for a single subject in that you cannot merge the Theia data into your Nexus trial using the **Add Theia Data** operation. **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](#RunTheiaSelectedTrials) or [Run Theia processing on all trials in a specified folder](#RunTheiaAllTrials)) 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**'. > Macro (inline-media-image) 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. :check_mark: **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](#CalculateJointAngles)). ## > Macro (anchor) 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](#CombineTheiaNexus)). 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.