3. Error Messages

This section addresses specific error dialogs that may arise during the use of Theia3D or TMBatch.

3.1. Organize Videos Errors

3.1.1. Input directory has no mp4 or avi files.

_images/error_nomp4oravifiles.png

Explanation

This error message arises when attempting to use the Organize Videos Tool to organize video files as required by Theia3D. Theia3D requires video data to be .mp4 or .avi file formats, so if the directory selected for organizing contains video files of a different format (e.g. .mkv, .mov, etc.) Theia3D will be unable to organize or load these videos.

Possible Solutions

To ensure your video data can be organized, loaded, and processed by Theia3D, they should be in .mp4 or .avi file formats. If possible, re-export the original videos to the correct file format, or convert the existing video files to the correct file format before attempting to organize, load, or process these videos.

3.2. Video Loading Errors

3.2.1. Videos not formatted properly.

_images/error_videoformat.png

Explanation

This error message arises when loading video data. It indicates that the folder selected when browsing to load video data contains data that is not formatted as required by Theia3D (See Data Formats). The video data may all be located within a single folder (i.e. all video files together in one folder), instead of each video file being nested within its own folder with a matching camera ID folder name.

Possible Solutions

  1. Organize the videos, then try again.

In order to load the desired video data, it must first be organized as required by Theia3D. This can be done using the Organize Videos tool under the Tools dropdown menu. For detailed instructions on the use of this tool, you can watch the Organize Tools tutorial video.

  1. Load the calibration file first.

As indicated in the error message, data that is all located within one folder instead of within camera ID folders can be loaded if the calibration file for the movement trial is loaded before the video data. Using this approach, the video data will then be automatically organized within camera ID folders to meet the Theia3D data organization requirements moving forward.

3.2.2. Only __ videos found.

_images/error_videonumber.png

Explanation

This error message arises when loading video data. It indicates that the folder selected when browsing for video data to load contains fewer than six camera views.

Possible Solutions

Theia3D requires six or more camera views in order to load any video data. If at least six cameras were used to collect the data, locate the missing videos and add them to the trial folder in properly formatted camera ID folders. If fewer than six cameras were used to collect the data, it cannot be loaded and should be recollected with six or more cameras.

3.2.3. Videos not the same length.

_images/error_unequalvideos.png

Explanation

This error message arises when loading video data. It indicates that the videos from the selected trial are of unequal lengths.

Possible Solutions

Theia3D requires videos to be of equal lengths in order to be loaded. If your videos are of different lengths, this usually indicates an issue with your camera hardware setup or settings, or video download settings.

For OptiTrack Prime Color cameras, verify that you have selected the correct video export settings, particularly Dropped Frames: Black Frame. If Dropped Frames: Drop Frame was used, this can result in exported video files being unequal in length, and the videos should be exported again using the correct setting.

3.2.4. Unsupported video codec detected.

_images/error_unsupportedcodec.png

Explanation

This error message arises when loading video data. It indicates that the videos files from the selected trial were written using an unsupported video file codec.

Possible Solutions

Theia3D requires video files to be encoded using certain supported video codecs. If the videos you are trying to load were encoded with an unsupported codec, they cannot be loaded by Theia3D. When this error is encountered, the best solution is to re-export the videos in a supported codec, or to convert the existing videos to a supported codec.

For OptiTrack Prime Color cameras, verify that you have selected the correct video export settings, particularly Video Format: MJPEG. If the incorrect video format was selected, the video files may not be written using a video codec supported by Theia3D and will need to exported from Motive again, in the proper format.

_images/opti_exportsettings.png

3.2.5. Invalid video.

_images/error_invalidvideo.png

Explanation

This error message arises when loading video data. It indicates that the videos files from the selected trial were written using an unsupported video chroma format for codec h264. Supported formats are 8, 10, or 12 bit YUV 4:2:0.

Possible Solutions

Theia3D requires video files to be encoded using certain supported video codecs and color chroma formats. If the videos you are trying to load were created with an unsupported video chroma format, they cannot be loaded by Theia3D. When this error is encountered, the best solution is to re-export or convert the videos to a supported chroma format.

3.3. Calibration Loading Errors

3.3.1. Unable to load calibration.

_images/error_loadcalibration.png

Explanation

This error message arises when loading a calibration file. It indicates that the selected calibration contains camera IDs that do not match those for the loaded videos.

Possible Solutions

  1. Check that the correct calibration file was selected.

The calibration file may be incorrect for the loaded videos. Confirm that you selected the correct calibration file, which should have been generated using a calibration trial from the same data collection session as the loaded movement trial videos.

  1. Check the camera IDs within the calibration file and the loaded video file names.

If Organize Videos is performed more than once to organize the video data and different delimiters or different parts of the file names were used to assign ‘Cam ID’, the camera IDs may not match between the calibration file and the loaded videos. If this is the case, the camera ID folder names for the calibration trial and movement trials should be changed to be consistent, and the camera IDs within the calibration file should be modified to match the camera ID folder names.

  1. Check that the number of cameras in the calibration file matches the number of videos loaded.

The number of camera views loaded in Theia3D and the number of cameras contained within the calibration file may not match. If the number of camera views loaded in Theia3D does not match the number of cameras listed in the calibration file, double check that you have selected the correct calibration file, that you are not missing any camera views from your loaded movement trial, and that the calibration file has not been modified.

3.3.2. Required camera parameter groups not present.

_images/error_parametergroups.png

Explanation

This error message arises when loading a calibration file. It indicates that the selected calibration file does not contain the required calibration parameters to calibrate the camera system of the loaded videos. The calibration file may be missing intrinsic parameters, extrinsic parameters, or a combination of both, which prevent it from calibrating the camera system for the video data.

Possible Solutions

  1. Check that the calibration file is an extrinsic calibration file.

The selected calibration file may be a lens intrinsic calibration file, rather than an extrinsic calibration file. Confirm that you selected the correct calibration file, which was either saved after processing a chessboard or object calibration in Theia3D, or was generated by third party software such as Qualisys Track Manager or Vicon Nexus following wand calibration.

  1. Check that the calibration file has not been modified.

The selected calibration file may have been modified, and some calibration parameters may have been deleted. If parts of the calibration file have been modified or deleted, you may need to replace it with a backup of the original calibration file (if generated from third party software), or generate a new calibration file by reprocessing the chessboard or object calibration trial in Theia3D.

3.3.3. Qualisys calibration has inconsistent FOV.

_images/error_inconsistentFOV.png

Explanation

This error message may arise when loading a calibration file exported from Qualisys Track Manager after performing a wand calibration. It indicates that the selected calibration file has inconsistent field of view parameters for the cameras contained within the calibration file. The field of view parameters are important for determining the area of the camera sensor used in the recording of the calibration trial.

The FOV parameters may be inconsistent if the videos for the currently loaded trial were recorded at a camera resolution that differs from that used during the wand calibration. The resolution of the videos must be consistent between the calibration trial and the recorded movement trials.

Possible Solutions

Perform a new wand calibration using the same camera resolutions as used for your movement trials. If the cameras have not moved since the movement trials were recorded, it may be possible to record and export a new wand calibration file using the same video resolutions as used for the movement trials. This would allow the videos to be calibrated properly.

3.4. Workspace Loading Errors

3.4.1. Data not loaded.

_images/error_datanotloaded.png

Explanation

This error message arises when attempting to load a saved Theia3D workspace. It indicates that the trial folder selected when browsing to load a workspace is missing required files, such as video or .t3d files.

Possible Solutions

  1. Replace any missing video files.

If the workspace failed to load due to one or more missing video files and the raw video data for the trial is still available, identify which video files are missing from the workspace folder and copy them from the raw video data trial folder.

  1. Reprocess the trial and replace the saved workspace.

If the workspace failed to load due to one or more missing .t3d files, it is necessary to reprocess the trial from the raw data. Follow the typical steps for processing an individual movement trial: load videos, load calibration, load or change the preferences, run analysis, and save workspace.

3.5. Calibration Processing Errors

3.5.1. Camera extrinsics optimization step 3 failed.

_images/error_calibrationoptimizationfail.png

Explanation

This error message arises when the chessboard calibration algorithm is unable to calculate the position and orientation of the cameras relative to the chessboard. More than one chessboard may have been detected in the calibration trial videos, which can be caused by extra chessboards present in the capture volume or mirrors positioned around the capture volume.

Possible Solutions

  1. Reduce the Frame Grab Step.

If the chessboard was detected in too few frames to be calibrated due to a high Frame Grab Step value being used, it may be possible to calibrate the system with a lower Frame Grab Step value. Lower the Frame Grab Step value and run the calibration again.

  1. Collect a new calibration trial.

If the camera system has not be taken down or modified since the data were collected and the data were collected relatively recently (within 48 hours), a new calibration trial can be recorded. Address the source of the problem (e.g. remove extra chessboards or cover mirrors) and collect a new calibration trial.

3.5.2. Unable to construct a continuous volume from overlapping chessboard frames.

_images/error_calibrationcontinuousvolumefail.png

Explanation

This error message arises when the chessboard calibration trial does not contain sufficient frames of overlapping visibility of the chessboard in 3 or cameras throughout the trial. This prevents the camera system from being properly calibrated, as there is insufficient information to calculate the position and orientation of all cameras in the system in 3D space.

Possible Solutions

  1. Reduce the Frame Grab Step

If the chessboard was detected in too few overlapping frames between camera groupings to form a continuous volume, it may be possible to calibrate the system with a lower Frame Grab Step value. Lower the Frame Grab Step value and run the calibration again.

  1. Collect a new calibration trial.

If it is not possible to reduce the Frame Grab Step to increase the overlapping visibility of the chessboard, it will be required to record a new calibration trial. If the camera system has not been taken down or modified since the data were collected and the data were collected relatively recently, a new calibration trial can be recorded. When recording the new calibration trial(s), be sure to focus on achieving an overlap in visibility of the chessboard surface in 3 or more cameras throughout the trial, and ensure that all camera groupings are linked by this overlap.

3.6. Run Analysis Errors

3.6.1. Track people not complete

_images/error_trackincomplete.png

Explanation

This error arises when Theia3D is not able to adequately track the people identified within the 2D views throughout 3D space. There are two primary causes of this error:

  1. An incorrect calibration file was loaded.

If an incorrect calibration file was loaded, meaning that the camera system is not properly calibrated, then it will not be possible for the people identified within the 2D videos to be tracked throughout 3D space.

  1. The Analysis Bounding Box was used with dimensions (length, width, height) of 0.

If the Restrict skeletons to bounding box option was selected but no dimensions were provided for the bounding box, the people visible in the 2D camera views cannot be tracked in 3D space and the Track people not complete error message will appear.

Possible Solutions

  1. Check the Restrict skeletons to bounding box option.

If you intended to use the Restrict skeletons to bounding box option, either provide the dimensions of your desired bounding box or use the Use Camera Locations option to define the bounding box. If you did not intend to use the Restrict skeletons to bounding box option, deselect it. After making either modification, you will need to Run Analysis (without 2D) to update the person tracking and modelling results.

  1. Check that the correct calibration was loaded.

If an incorrect calibration file was loaded, the camera system may not be calibrated properly leading to improper 3D reconstructions from the 2D data. Review the position and orientation of the global coordinate system in each 2D camera view - they should all show the global coordinate system at the same position and orientation. If the global coordinate system is out of place, it is likely that an incorrect calibration was loaded. Locate and load the correct calibration file, and Run Analysis again.

  1. Check that there are people sufficiently visible to be tracked.

If there are no people or insufficient views of any people captured in the videos, nobody will be tracked. Be sure that your cameras are set up to sufficiently capture any participants with 3 or more cameras at all times, and record new movement trials.

3.6.2. Abnormally high tracking errors.

_images/error_abnormallyhightrackingerrors.png

Explanation

This error message arises when abnormally high tracking errors are detected for one or more camera views, as reported in the error dialog. As indicated by the dialog, this usually indicates a problem with the camera calibration and may be possible to resolve using the Check Calibration tool.

Possible Solutions

  1. Record a new calibration.

If the camera system has not be taken down or modified since the data were collected and the data were collected relatively recently (within 48 hours), a new calibration trial can be recorded. A new calibration may resolve the calibration issue and tracking errors in the movement trial.

  1. Use the Check Calibration tool.

As indicated by the error dialog, it may be possible to resolve or improve the camera calibration using the Check Calibration tool. Apply this tool to obtain and potential improvements.