15. Batch Processing

The TMBatch program.

One of the benefits offered by Theia3D markerless motion capture is automated tracking, which allows it to analyze large datasets without human intervention or supervision. This is achieved using the TMBatch companion application to Theia3D, which allows a list of trials to be curated and batch analyzed sequentially. While batch processing is efficient and does not require supervision, we always recommend that you manually examine and check the quality of your markerless data and calibrations using Theia3D, before setting up a batch analysis. This can prevent poor calibrations or other issues with the data from going unnoticed until after the batch analysis has been completed.

There are a variety of tools available within TMBatch to organize and analyze multiple trials. The data to be processed must be in a single directory that can contain as many levels of subdirectories as desired to organize the data. However, each branch of the directory must end with a folder containing the data for a single trial. This must be a folder of video data as described in Video Data that also contains the calibration file for the trial. It is critical that the IDs of the cameras in the calibration file are the same as the IDs of the video file subfolders. When using this tool, the first step is to make sure your video data are organized and the calibration has been added to the files. Once these steps are complete, your data is prepared for batch processing. Proceed to Settings and Trials for details on setting up and executing a batch analysis.

15.1. File Menu

The File dropdown menu.

The two prerequisites for batch processing of video data is that the videos are organized in the required nested folder structure as described in Video Data, and that every trial has an assigned calibration file. Therefore, the Organize Videos and Assign Calibration Files tools are included for use in TMBatch.

The File dropdown menu Open into options dialog.

The Open into options allow you to easily open the currently selected batch processing directory, in either Windows Explorer or the command line.

15.2. Help Menu

The Help dropdown menu.

Help	Opens the online documentation for the software.
Manual	Opens the pdf documentation to the software.
About	The About dialog shows the following information: Software version number Release date Contact information

The TMBatch About dialog window.

15.3. Settings

The Settings section provides widgets to set up the current batch analysis. The Browse button enables the user to select the root folder. The data to be processed must be organized in this single root folder that can contain as many levels of subdirectories as desired to organize the data. However, each branch of the directory must end with a folder containing the data for a single trial. This must be a folder of video data as described in Video Data that also contains the calibration files for the cameras. It is critical that the IDs of the cameras in the calibration file are the same as the IDs of the video file subfolders. The Settings section enables the user to input the batch analysis root directory and the output format that will be generated by the batch analysis:

Batch Path	Currently selected batch analysis root folder.
Browse	Select the batch analysis root folder.
Refresh	Refresh the batch analysis root folder to update the Trials list with changes to the folder.
Save Workspace	If selected, a workspace is saved for each trial in a folder called inputdirectory_workspace. This folder is in the same location and has the same structure as inputdirectory.
Save JSON	If selected, the pose data for all individuals tracked in each trial will be saved in a folder called inputdirectory_json. This folder is in the same location and has the same structure as intputdirectory.
Save C3D	If selected, the pose .c3d files will be saved for each trial in a folder called inputdirectory_c3d. This folder is in the same location and has the same structure as inputdirectory.
Save Fbx	If selected, the pose .fbx files will be saved for each trial in a folder called inputdirectory_fbx. This folder is in the same location and has the same structure as inputdirectory. The coordinate system convention used in the .fbx file can be selected from the dropdown box.
Use Hierarchical Names	(Only applicable when Save C3d is selected) If selected, the pose .c3d files will be created with file names that combine the folder names from the lowest n levels of the batch analysis folder hierarchy, where n is the selected Level dropdown value. For example, if selected and Level=3 for data that is structured as [subject] / [action] / [trial] / [camID], the output files will be named: [subject]_[action]_[trial]_pose_filt_#.c3d.

Note: The batch analysis may encounter errors if the folder structure, calibration file, or preferences are incorrect. These issues may be identified in the Trials list once the root folder has been selected, however the user is urged to read and understand the requirements for these data structures and files prior to running a batch analysis.

15.4. Trials

The Trials list is populated with all valid trials within the selected batch analysis root folder, once a folder has been selected. Above the trials list are the following options:

Search: Filters trials via string compare and regular expression. Built-in filter options based on trial states can be accessed using the @ symbol, including those shown below.

Available filter options in the Search bar using the @ symbol.

After searching, the selection box next to ‘Trials’ can be toggled to select or deselct all trials that were returned based on the string search. Helps with batching a subset of the root folder.

Details: Show trial metadata like assigned calibrations, trial length (# frames), and frame rate (FPS).

Right-clicking on any trial within the Trials list will provide the following options:

Open into allows the location of the selected trial data to be opened in Windows Explorer or the command line, as described above in File Menu.

Reset Analysis Range will reset the Analysis Frame Range preference to be reset so that the entire trial will be analyzed from the first to last frame of data.

The Trials list has the following features within each row. Right-click on the Trials list header to enable or disable specific details columns as desired.

Dropdown	Dropdown triangle icon that expands to show the processing steps for each trial. Indicates success, warnings, or failures for each step where required.
Checkbox	Selection square that indicates whether the trial is included in the batch analysis. Initially, all trials are selected.
Trial Path	The full path to the trial.
State:	Circle that indicates the status of the trial: Unknown, or not yet analyzed Success Skipped Already done Cancelled Warning Failed
Calibration Indicator	Icon that indicates the status of the calibration file for the trial: valid structure and calibration file. more than one calibration file was found. the trial does not have a calibration file.
Calibration Filename	Filename for the calibration file assigned to the trial. Allows easy distinction when different calibration files should be used for different movement trials within one batch analysis.
Preferences Indicator	Icon that indicates the status of the preferences file for the trial. default preferences will be used. custom preferences file will be used. more than one preferences file was found.
Preferences Filename	Filename for the preferences file assigned to the trial. Allows easy distinction when different preferences should be used for different movement trials within one batch analysis.
# Frames	Length of the trial, expressed as the number of frames.
FPS:	Video frame rate of the trial, expressed as Frames Per Second (FPS).
Cutoff Freq	GCVSPL Cutoff Frequency that will be used to analyze the trial as selected in the preference file for the trial, expressed in Hz. See details below for how to edit the preferences file to change the Cutoff Freq.
Excluded Cameras	List of cameras that will be excluded when processing the trial, based on the list of excluded cameras in the preferences file.
Tracking BBox	Maximum and minimum 3D corner positions of the tracking bounding box, when applied. Expressed as a set of six values: (min_X, min_Y, min_Z, max_X, max_Y, max_Z), where the minimum corner is located at (origin_X-length/2, origin_Y-width/2, origin_Z-height/2) and the maximum corner is located at (origin_X+length/2, origin_Y+width/2, origin_Z+height/2).

At the bottom of the TMBatch window, the Run Batch button is used to start the batch analysis. After clicking Run Batch, the TMBatch performs a check to identify trials that have already been analyzed. If it finds any, a dialog is shown offering the user to skip or re-run these trials. This allows data to be added to a directory and that directory to be batch processed again without reprocessing completed trials. Once the batch has started, Theia3D will run in the background a full analysis on each checked trial in the list. After the batch has finished, the results of each trial can be viewed in Theia3D by loading the saved workspace belonging to the trial.

Modifying the Trials List

The Trials list can be easily modified using to include or exclude groups of trials to allow portions of the trial list to be left out of the batch analysis. This can be useful if you are only interested in analyzing specific portions of your data, for example only analyzing one action. The easiest way to make modifications to the Trials list is using the Search bar above the Trials list in combination with the selection box next at the top of the Trials list, which selects or deselects all currently displayed trials. This can be performed to exclude specific subsets of trials, or include specific subsets of trials from the batch analysis.

An example procedure for using this technique for modifying the Trials list is as follows:

1. Ensure all trials are currently selected using the ‘select/deselect all’ box at the top of the Trials list.

2. Use a specific search term in the Search bar to display a subset of trials you wish to exclude.

3. Confirm the currently displayed trials are those that you wish to exclude.

4. Use the ‘select/deselect all’ box at the top of the Trials list to deselect these trials.

5. Clear the Search bar.

6. Confirm that the subset of trials is now deselected within the complete Trials list.

Note: The list of trials displayed after using the search bar is not the current batch analysis list, but just a list of the trials from within the batch analysis directory that meet the search criteria.

15.5. Preferences

The preferences file associated with each trial determines the prefences used when that trial is analyzed. This allows you to customize the preferences used across different trials within a single batch analysis, providing greater control over the analysis process. If there are not any preferences .pxt files assigned to the trials within your selected batch analysis root folder, the Preferences column will indicate that the default preferences will be used for your trials.

Right-clicking on the preferences column displays a context menu for the preferences, with the following options:

Edit	Opens the Settings dialog to change the preferences for the current trial.
Copy	Copies the preferences of the current trial to the clipboard.
Paste	Pastes the preferences in the clipboard to the selected trials, or if no trials are selected, to the current trial.

Modifying the Preferences

An example procedure for modifying the preferences assigned to a subset of trials is as follows:

1. Select one of the trials in the subset whose preferences you wish to modify.

2. Right-click on the Preferences column for that trial, and select Edit.

3. Modify the preferences in the Settings window to your desired preferences, and click Save.

4. Right-click on the Preferences column for the same trial, and select Copy.

5. Select the remaining trials in the subset whose preferences you wish to modify, using shift+click to select sequential groups of trials or ctrl+click to select individual trials.

6. Right-click on the Preferences column for one of the currently selected trials, and select Paste.